feat(cli): --version, -V, and version subcommand (closes #26)

There was no way to discover the installed Trailmark version from the
CLI. Adds three equivalent paths, all printing `trailmark <version>`:

- `trailmark --version`
- `trailmark -V`
- `trailmark version`

The long/short flags use argparse's built-in action="version" which
prints and exits with status 0. The subcommand form dispatches through
main() and uses the same version string.

Also bumps __version__ and pyproject.toml to 0.2.2 and refreshes the
lockfile.

5 new tests in test_cli_parser.py cover each form end-to-end.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tob-scott-a

README.md

@@ -243,6 +243,10 @@ Requires Python ≥ 3.12.
 ## Usage
 
 ```bash
+# Report the installed version
+trailmark --version     # or: trailmark -V
+trailmark version       # subcommand form
+
 # Full JSON graph (Python, the default)
 trailmark analyze path/to/project
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trailmark"
-version = "0.2.1"
+version = "0.2.2"
 description = "Parse source code into a queryable graph of functions, classes, calls, and semantic annotations"
 readme = "README.md"
 requires-python = ">=3.12"

src/trailmark/__init__.py

@@ -1,3 +1,3 @@
 """Trailmark: Parse source code into queryable graphs for security analysis."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

src/trailmark/cli.py

@@ -8,17 +8,31 @@
 from pathlib import Path
 from typing import Any
 
+from trailmark import __version__
 from trailmark.query.api import QueryEngine
 
+_VERSION_STRING = f"trailmark {__version__}"
+
 
 def build_parser() -> argparse.ArgumentParser:
     """Construct the Trailmark CLI's argparse tree."""
     parser = argparse.ArgumentParser(
         prog="trailmark",
-        description="Parse source code into queryable graphs",
+        description=f"Parse source code into queryable graphs (v{__version__})",
+    )
+    parser.add_argument(
+        "--version",
+        "-V",
+        action="version",
+        version=_VERSION_STRING,
     )
     subparsers = parser.add_subparsers(dest="command")
 
+    subparsers.add_parser(
+        "version",
+        help="Print the Trailmark version and exit",
+    )
+
     analyze = subparsers.add_parser(
         "analyze",
         help="Analyze a directory and output the code graph",
@@ -133,6 +147,9 @@ def main() -> None:
         parser.print_help()
         sys.exit(1)
 
+    if args.command == "version":
+        print(_VERSION_STRING)
+        return
     if args.command == "analyze":
         _run_analyze(args)
     elif args.command == "augment":

tests/test_cli_parser.py

@@ -58,7 +58,48 @@ def test_command_dest(self, parser: argparse.ArgumentParser) -> None:
     def test_all_subcommands_registered(
         self, subparsers_map: dict[str, argparse.ArgumentParser]
     ) -> None:
-        assert set(subparsers_map) == {"analyze", "augment", "entrypoints", "diff"}
+        assert set(subparsers_map) == {
+            "analyze",
+            "augment",
+            "entrypoints",
+            "diff",
+            "version",
+        }
+
+
+class TestVersionFlag:
+    """Regression for issue #26 — the CLI must expose its version."""
+
+    def test_long_flag_prints_and_exits(
+        self, parser: argparse.ArgumentParser, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        import trailmark
+
+        with pytest.raises(SystemExit) as excinfo:
+            parser.parse_args(["--version"])
+        assert excinfo.value.code == 0
+        out = capsys.readouterr().out
+        assert out.strip() == f"trailmark {trailmark.__version__}"
+
+    def test_short_flag_prints_and_exits(
+        self, parser: argparse.ArgumentParser, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        import trailmark
+
+        with pytest.raises(SystemExit) as excinfo:
+            parser.parse_args(["-V"])
+        assert excinfo.value.code == 0
+        out = capsys.readouterr().out
+        assert out.strip() == f"trailmark {trailmark.__version__}"
+
+    def test_version_subcommand_registered(
+        self, subparsers_map: dict[str, argparse.ArgumentParser]
+    ) -> None:
+        assert "version" in subparsers_map
+
+    def test_version_subcommand_parses(self, parser: argparse.ArgumentParser) -> None:
+        args = parser.parse_args(["version"])
+        assert args.command == "version"
 
 
 class TestAnalyzeSubparser:
@@ -206,3 +247,16 @@ def test_entrypoints_json_flag(self, parser: argparse.ArgumentParser) -> None:
     def test_augment_repeatable_sarif(self, parser: argparse.ArgumentParser) -> None:
         args = parser.parse_args(["augment", "p", "--sarif", "a.sarif", "--sarif", "b.sarif"])
         assert args.sarif == ["a.sarif", "b.sarif"]
+
+
+class TestVersionSubcommandExecution:
+    def test_main_version_prints_version(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        import trailmark
+        from trailmark.cli import main
+
+        monkeypatch.setattr("sys.argv", ["trailmark", "version"])
+        main()
+        out = capsys.readouterr().out
+        assert out.strip() == f"trailmark {trailmark.__version__}"