trailmark 0.2.1__tar.gz → 0.2.2__tar.gz

{trailmark-0.2.1 → trailmark-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trailmark
-Version: 0.2.1
+Version: 0.2.2
 Summary: Parse source code into a queryable graph of functions, classes, calls, and semantic annotations
 Project-URL: Homepage, https://github.com/trailofbits/trailmark
 Project-URL: Repository, https://github.com/trailofbits/trailmark
@@ -260,6 +260,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
 

{trailmark-0.2.1 → trailmark-0.2.2}/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
 

{trailmark-0.2.1 → trailmark-0.2.2}/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"

{trailmark-0.2.1 → trailmark-0.2.2}/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"

{trailmark-0.2.1 → trailmark-0.2.2}/src/trailmark/analysis/entrypoints.py

@@ -1106,9 +1106,9 @@ def _detect_pyproject_scripts(
 ) -> dict[str, EntrypointTag]:
     """Read ``[project.scripts]`` from pyproject.toml and tag each target.
 
-    Entries take the form ``name = "module.path:function"``. We locate the
-    matching node by (file path suffix, function name) because Trailmark's
-    node IDs use file basenames rather than full module paths.
+    Entries take the form ``name = "module.path:function"``. We first try the
+    matching node ID directly, then fall back to an unambiguous file path suffix
+    match for parses rooted below the import root.
     """
     pyproject = repo_root / "pyproject.toml"
     if not pyproject.exists():
@@ -1149,12 +1149,20 @@ def _resolve_script_target(
     func_name: str,
 ) -> str | None:
     """Find the node id matching a ``module.path:function`` script target."""
+    exact_id = f"{module_path}:{func_name}"
+    unit = graph.nodes.get(exact_id)
+    if unit is not None and unit.name == func_name:
+        return exact_id
+
     suffix = module_path.replace(".", "/") + ".py"
+    matches: list[str] = []
     for node_id, unit in graph.nodes.items():
         if unit.name != func_name:
             continue
         if unit.location.file_path.endswith(suffix):
-            return node_id
+            matches.append(node_id)
+    if len(matches) == 1:
+        return matches[0]
     return None
 
 

{trailmark-0.2.1 → trailmark-0.2.2}/src/trailmark/cli.py

@@ -8,17 +8,31 @@ import sys
 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":

{trailmark-0.2.1 → trailmark-0.2.2}/src/trailmark/parsers/_common.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 from collections.abc import Callable
+from contextvars import ContextVar
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -39,13 +40,49 @@ def make_location(node: Node, file_path: str) -> SourceLocation:
     )
 
 
+_DIRECTORY_PARSE_ROOT: ContextVar[Path | None] = ContextVar(
+    "_DIRECTORY_PARSE_ROOT",
+    default=None,
+)
+
+
 def module_id_from_path(file_path: str) -> str:
-    """Derive a module ID from a file path."""
+    """Derive a module ID from a file path.
+
+    Single-file parsing preserves the historical filename-stem ID. Directory
+    parsing uses a root-relative dotted path so same-named files in different
+    directories do not overwrite each other when their graphs are merged.
+    """
     p = Path(file_path)
+    root = _DIRECTORY_PARSE_ROOT.get()
+    if root is not None:
+        try:
+            rel_path = _absolute_lexical_path(p).relative_to(root)
+        except ValueError:
+            pass
+        else:
+            if rel_path.stem == "__init__":
+                module_path = rel_path.parent
+                if module_path == Path("."):
+                    return _escape_module_path_part(root.name)
+            else:
+                module_path = rel_path.with_suffix("")
+            return ".".join(_escape_module_path_part(part) for part in module_path.parts)
+
     stem = p.stem if p.stem != "__init__" else p.parent.name
     return stem
 
 
+def _absolute_lexical_path(path: Path) -> Path:
+    """Return an absolute path without resolving symlink targets."""
+    return Path(os.path.abspath(path))
+
+
+def _escape_module_path_part(part: str) -> str:
+    """Escape separators used in dotted module IDs."""
+    return part.replace("\\", "\\\\").replace(".", "\\.")
+
+
 _EXCLUDED_DIRS = frozenset(
     {
         ".git",
@@ -98,9 +135,13 @@ def parse_directory(
         extensions: File extensions to include.
     """
     merged = CodeGraph(language=language, root_path=dir_path)
-    for fpath in walk_source_files(dir_path, extensions):
-        file_graph = parse_file_fn(fpath)
-        merged.merge(file_graph)
+    token = _DIRECTORY_PARSE_ROOT.set(_absolute_lexical_path(Path(dir_path)))
+    try:
+        for fpath in walk_source_files(dir_path, extensions):
+            file_graph = parse_file_fn(fpath)
+            merged.merge(file_graph)
+    finally:
+        _DIRECTORY_PARSE_ROOT.reset(token)
     return merged
 
 

{trailmark-0.2.1 → trailmark-0.2.2}/tests/test_cli_parser.py

@@ -58,7 +58,48 @@ class TestTopLevelParser:
     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 @@ class TestParseBehavior:
     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__}"

trailmark-0.2.2/tests/test_common_parser.py

@@ -0,0 +1,154 @@
+"""Tests for parser utilities shared across language implementations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from trailmark.models.edges import CodeEdge, EdgeKind
+from trailmark.models.graph import CodeGraph
+from trailmark.models.nodes import CodeUnit, NodeKind, SourceLocation
+from trailmark.parsers._common import module_id_from_path, parse_directory
+
+
+def _fake_parse_file(file_path: str) -> CodeGraph:
+    """Build a tiny graph using the shared module ID helper."""
+    module_id = module_id_from_path(file_path)
+    function_id = f"{module_id}:helper"
+    location = SourceLocation(file_path=file_path, start_line=1, end_line=1)
+    return CodeGraph(
+        nodes={
+            module_id: CodeUnit(
+                id=module_id,
+                name=module_id,
+                kind=NodeKind.MODULE,
+                location=location,
+            ),
+            function_id: CodeUnit(
+                id=function_id,
+                name="helper",
+                kind=NodeKind.FUNCTION,
+                location=location,
+            ),
+        },
+        edges=[
+            CodeEdge(
+                source_id=module_id,
+                target_id=function_id,
+                kind=EdgeKind.CONTAINS,
+            )
+        ],
+        language="test",
+        root_path=file_path,
+    )
+
+
+def test_module_id_from_path_preserves_single_file_stem_behavior(tmp_path: Path) -> None:
+    file_path = tmp_path / "src" / "compat.py"
+    file_path.parent.mkdir()
+    file_path.write_text("")
+
+    assert module_id_from_path(str(file_path)) == "compat"
+
+
+def test_parse_directory_uses_root_relative_module_ids(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    tests = tmp_path / "tests"
+    src.mkdir()
+    tests.mkdir()
+    (src / "compat.py").write_text("")
+    (tests / "compat.py").write_text("")
+
+    graph = parse_directory(
+        _fake_parse_file,
+        language="test",
+        dir_path=str(tmp_path),
+        extensions=(".py",),
+    )
+
+    assert set(graph.nodes) == {
+        "src.compat",
+        "src.compat:helper",
+        "tests.compat",
+        "tests.compat:helper",
+    }
+    assert {(edge.source_id, edge.target_id) for edge in graph.edges} == {
+        ("src.compat", "src.compat:helper"),
+        ("tests.compat", "tests.compat:helper"),
+    }
+
+
+def test_parse_directory_escapes_dotted_path_components(tmp_path: Path) -> None:
+    dotted_dir = tmp_path / "a.b"
+    dotted_file_parent = tmp_path / "a"
+    dotted_dir.mkdir()
+    dotted_file_parent.mkdir()
+    (dotted_dir / "c.py").write_text("")
+    (dotted_file_parent / "b.c.py").write_text("")
+
+    graph = parse_directory(
+        _fake_parse_file,
+        language="test",
+        dir_path=str(tmp_path),
+        extensions=(".py",),
+    )
+
+    assert set(graph.nodes) == {
+        r"a\.b.c",
+        r"a\.b.c:helper",
+        r"a.b\.c",
+        r"a.b\.c:helper",
+    }
+
+
+def test_parse_directory_uses_package_path_for_init_files(tmp_path: Path) -> None:
+    pkg = tmp_path / "pkg"
+    subpkg = pkg / "subpkg"
+    subpkg.mkdir(parents=True)
+    (pkg / "__init__.py").write_text("")
+    (subpkg / "__init__.py").write_text("")
+
+    graph = parse_directory(
+        _fake_parse_file,
+        language="test",
+        dir_path=str(tmp_path),
+        extensions=(".py",),
+    )
+
+    assert set(graph.nodes) == {
+        "pkg",
+        "pkg:helper",
+        "pkg.subpkg",
+        "pkg.subpkg:helper",
+    }
+
+
+def test_parse_directory_uses_lexical_path_for_symlinked_files(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    outside = tmp_path / "outside"
+    src = root / "src"
+    tests = root / "tests"
+    outside.mkdir()
+    src.mkdir(parents=True)
+    tests.mkdir()
+    (outside / "compat.py").write_text("")
+    (tests / "compat.py").write_text("")
+    try:
+        (src / "compat.py").symlink_to(outside / "compat.py")
+    except OSError:
+        pytest.skip("symlink creation is not supported on this platform")
+
+    graph = parse_directory(
+        _fake_parse_file,
+        language="test",
+        dir_path=str(root),
+        extensions=(".py",),
+    )
+
+    assert set(graph.nodes) == {
+        "src.compat",
+        "src.compat:helper",
+        "tests.compat",
+        "tests.compat:helper",
+    }

{trailmark-0.2.1 → trailmark-0.2.2}/tests/test_entrypoints.py

@@ -46,8 +46,8 @@ class TestSelfAnalysis:
         engine = QueryEngine.from_directory(str(SRC), language="python")
         surface = engine.attack_surface()
         node_ids = {ep["node_id"] for ep in surface}
-        assert "cli:main" in node_ids, (
-            f"Expected cli:main (the pyproject.toml script target) in {node_ids}"
+        assert "trailmark.cli:main" in node_ids, (
+            f"Expected trailmark.cli:main (the pyproject.toml script target) in {node_ids}"
         )
 
 
@@ -106,6 +106,28 @@ class TestPyprojectScripts:
         ids = {ep["node_id"] for ep in engine.attack_surface()}
         assert "app:main" in ids
 
+    def test_pyproject_script_ambiguous_suffix_is_skipped(self, tmp_path: Path) -> None:
+        """Suffix fallback must not select an order-dependent script target."""
+        (tmp_path / "pyproject.toml").write_text(
+            "[project]\n"
+            'name = "demo"\n'
+            'version = "0.0.0"\n'
+            "[project.scripts]\n"
+            'demo = "pkg.app:main"\n',
+        )
+        src_pkg = tmp_path / "src" / "pkg"
+        tests_pkg = tmp_path / "tests" / "pkg"
+        src_pkg.mkdir(parents=True)
+        tests_pkg.mkdir(parents=True)
+        (src_pkg / "app.py").write_text("def main():\n    pass\n")
+        (tests_pkg / "app.py").write_text("def main():\n    pass\n")
+
+        engine = QueryEngine.from_directory(str(tmp_path))
+        surface = {ep["node_id"]: ep for ep in engine.attack_surface()}
+
+        assert surface["src.pkg.app:main"]["trust_level"] == "trusted_internal"
+        assert surface["tests.pkg.app:main"]["trust_level"] == "trusted_internal"
+
     def test_malformed_pyproject_is_tolerated(self, tmp_path: Path) -> None:
         """A broken pyproject.toml must not crash detection."""
         (tmp_path / "pyproject.toml").write_text("this is not valid toml = [")
@@ -169,7 +191,24 @@ class TestOverrideFile:
         )
         engine = QueryEngine.from_directory(str(tmp_path))
         ids = {ep["node_id"] for ep in engine.attack_surface()}
-        assert "app:serve" in ids
+        assert "pkg.app:serve" in ids
+
+    def test_override_ambiguous_module_reference_is_skipped(self, tmp_path: Path) -> None:
+        """Ambiguous module references should not tag the first suffix match."""
+        src_pkg = tmp_path / "src" / "pkg"
+        tests_pkg = tmp_path / "tests" / "pkg"
+        src_pkg.mkdir(parents=True)
+        tests_pkg.mkdir(parents=True)
+        (src_pkg / "app.py").write_text("def serve():\n    pass\n")
+        (tests_pkg / "app.py").write_text("def serve():\n    pass\n")
+        self._write_override(
+            tmp_path,
+            '[[entrypoint]]\nnode = "pkg.app:serve"\nkind = "api"\n',
+        )
+
+        engine = QueryEngine.from_directory(str(tmp_path))
+
+        assert engine.attack_surface() == []
 
     def test_override_unknown_node_is_skipped(self, tmp_path: Path) -> None:
         (tmp_path / "app.py").write_text("def real():\n    pass\n")
@@ -886,7 +925,7 @@ class TestBulkOverrideRules:
         engine = QueryEngine.from_directory(str(tmp_path), language="python")
         ids = {ep["node_id"] for ep in engine.attack_surface()}
         # In public/ AND matches name_regex -> yes
-        assert "web:handle_login" in ids
+        assert "public.web:handle_login" in ids
         # In public/ but fails name_regex -> no
         assert "util:helper" not in ids
         # Matches name_regex but not in public/ -> no

{trailmark-0.2.1 → trailmark-0.2.2}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 ]
 
 [options]
-exclude-newer = "2026-04-16T18:39:10.32177Z"
+exclude-newer = "2026-04-17T00:53:06.94394Z"
 exclude-newer-span = "P1W"
 
 [[package]]
@@ -599,7 +599,7 @@ wheels = [
 
 [[package]]
 name = "trailmark"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "rustworkx" },