fix docs drift and javascript module detection

Author: tob-scott-a

AGENTS.md

@@ -5,9 +5,10 @@ Development context for AI agents working on this codebase.
 ## Project Overview
 
 Trailmark parses source code into directed graphs of functions, classes,
-calls, and semantic metadata for security analysis. It supports 16
-languages via tree-sitter (plus a bundled Circom grammar) and uses
-rustworkx for graph traversal.
+calls, and semantic metadata for security analysis. It supports more than
+twenty language frontends via tree-sitter-language-pack plus bundled
+custom grammars, and uses rustworkx for graph traversal. Treat
+`README.md` as the authoritative public feature list.
 
 ## Architecture
 
@@ -19,17 +20,22 @@ CodeGraph (data) -> GraphStore (indexed storage) -> QueryEngine (facade)
 - **GraphStore** wraps CodeGraph in a rustworkx PyDiGraph. Validates
   node existence. Returns model objects.
 - **QueryEngine** resolves names to node IDs, delegates to GraphStore,
-  returns plain dicts for JSON serialization.
+  and returns JSON-serializable data structures for user-facing APIs.
 
 ## Key Conventions
 
-- All public methods return `False` or `[]` for missing nodes. Never raise.
-- QueryEngine returns dicts; GraphStore returns model objects.
+- Query/read methods should return `False`, `[]`, or empty sets for
+  missing nodes where practical. Factory methods and invalid-input paths
+  may raise `ValueError` or exit via the CLI.
+- QueryEngine returns JSON-serializable data structures; GraphStore
+  returns model objects and node IDs.
 - Node IDs follow `module:function`, `module:Class`, `module:Class.method`.
 - Edge confidence: `certain`, `inferred`, `uncertain`.
 - Annotation sources: `"llm"`, `"docstring"`, `"manual"`.
 - Frozen dataclasses for immutable data. `CodeGraph` is mutable.
 - No relative (`..`) imports. Use `from trailmark.*`.
+- Update `README.md` and `tests/test_readme.py` when documented behavior
+  changes.
 
 ## File Layout
 
@@ -46,6 +52,7 @@ src/trailmark/
     python/        # One subpackage per language
     javascript/
     ...
+  analysis/        # Higher-level passes: entrypoints, diff, augment, preanalysis
   storage/
     graph_store.py # GraphStore: rustworkx-backed indexed storage
   query/
@@ -57,10 +64,11 @@ tests/             # pytest test suite
 ## Running Checks
 
 ```bash
-uv run ruff check --fix src/ tests/
-uv run ruff format src/ tests/
-uv run ty check
-pytest -q
+uv sync --all-groups
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv tool install ty && ty check
+uv run pytest -q tests/
 ```
 
 ## Mutation Testing
@@ -85,6 +93,10 @@ This is not needed on Linux/CI (Ubuntu).
 - Follow the three-layer pattern: add to CodeGraph first, then GraphStore
   (with validation), then QueryEngine (with name resolution and dict
   conversion).
-- Add tests at each layer: `test_models.py`, `test_storage.py`,
-  `test_query.py`.
-- Update `README.md` if adding user-facing API.
+- Analysis passes live under `trailmark.analysis` and should usually
+  persist results as annotations or named subgraphs rather than
+  bypassing the graph model.
+- Add tests at each relevant layer: `test_models.py`, `test_storage.py`,
+  `test_query.py`, plus focused parser/analysis/doc regression tests.
+- Update `README.md` and the matching regression tests if adding or
+  changing user-facing API.

README.md

@@ -43,7 +43,7 @@ A language-specific parser walks the directory, parses each file into a tree-sit
 | Language | Extensions | Key constructs |
 | --- | --- | --- |
 | Python | `.py` | functions, classes, methods |
-| JavaScript | `.js`, `.jsx` | functions, classes, arrow functions |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | functions, classes, arrow functions |
 | TypeScript | `.ts`, `.tsx` | functions, classes, interfaces, enums |
 | PHP | `.php` | functions, classes, interfaces, traits |
 | Ruby | `.rb` | methods, classes, modules |
@@ -111,11 +111,17 @@ The `QueryEngine` provides a high-level API over the indexed graph:
 | `attack_surface()` | Entrypoints tagged with trust level and asset value |
 | `complexity_hotspots(n)` | Functions with cyclomatic complexity ≥ n |
 | `functions_that_raise(exc)` | Functions whose parser-detected exception list includes `exc` |
-| `annotate(name, kind, desc, source)` | Add a semantic annotation to a node |
+| `annotate(name, kind, description, source)` | Add a semantic annotation to a node |
 | `annotations_of(name, kind=None)` | Get annotations for a node, optionally filtered by kind |
 | `nodes_with_annotation(kind)` | Every node tagged with the given annotation kind |
 | `clear_annotations(name, kind=None)` | Remove annotations from a node |
 | `diff_against(other)` | Structural diff of this engine's graph vs. another |
+| `preanalysis()` | Run the built-in pre-analysis passes and store annotations/subgraphs |
+| `augment_sarif(path)` | Merge SARIF findings into the graph |
+| `augment_weaudit(path)` | Merge weAudit findings into the graph |
+| `findings(kind=None)` | Return nodes carrying finding-style annotations |
+| `subgraph(name)` | Return the nodes in a named subgraph |
+| `subgraph_names()` | List every named subgraph currently on the graph |
 | `summary()` | Node counts, edge counts, dependencies |
 | `to_json()` | Full graph export |
 
@@ -220,8 +226,16 @@ graph TD
 
 ## Installation
 
+The examples below track the current development branch. For the latest
+published package, install from PyPI. For the exact feature set described
+here, install from a checkout and run commands via `uv run`.
+
 ```bash
+# Latest published release
 uv pip install trailmark
+
+# Current checkout / development branch
+uv sync --all-groups
 ```
 
 Requires Python ≥ 3.12.
@@ -394,6 +408,15 @@ before = QueryEngine.from_directory("before/")
 diff = engine.diff_against(before)
 # diff contains: summary_delta, nodes {added/removed/modified},
 # edges {added/removed}, entrypoints {added/removed/modified}
+
+# Run the built-in audit-oriented preanalysis passes
+engine.preanalysis()
+engine.findings()
+engine.subgraph_names()
+
+# Programmatic augmentation hooks for external tooling
+engine.augment_sarif("results.sarif")
+engine.augment_weaudit("findings.json")
 ```
 
 ## Development
@@ -410,7 +433,7 @@ uv run ruff format
 uv tool install ty && ty check
 
 # Tests
-uv run pytest -q
+uv run pytest -q tests/
 
 # Mutation testing (on macOS, set this env var to avoid rustworkx fork segfaults)
 OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES uv run mutmut run

src/trailmark/__init__.py

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

src/trailmark/parsers/javascript/parser.py

@@ -46,7 +46,7 @@
 
 _FUNCTION_EXPR_TYPES = frozenset({"arrow_function", "function", "function_expression"})
 
-_EXTENSIONS = (".js", ".jsx")
+_EXTENSIONS = (".js", ".jsx", ".mjs", ".cjs")
 
 
 class JavaScriptParser:
@@ -69,7 +69,7 @@ def parse_file(self, file_path: str) -> CodeGraph:
         return graph
 
     def parse_directory(self, dir_path: str) -> CodeGraph:
-        """Parse all .js/.jsx files under dir_path."""
+        """Parse all supported JavaScript files under ``dir_path``."""
         return parse_directory(
             self.parse_file,
             "javascript",

tests/test_javascript_parser.py

@@ -4,6 +4,7 @@
 
 import os
 import tempfile
+from pathlib import Path
 
 from trailmark.models.edges import EdgeConfidence, EdgeKind
 from trailmark.models.graph import CodeGraph
@@ -258,6 +259,18 @@ def test_export_class_extracted(self) -> None:
         names = {n.name for n in graph.nodes.values()}
         assert "ExportedWidget" in names
 
+
+class TestJavaScriptParserExtensions:
+    def test_parse_directory_includes_mjs_and_cjs(self, tmp_path: Path) -> None:
+        (tmp_path / "alpha.mjs").write_text("export function alpha() { return 1; }\n")
+        (tmp_path / "beta.cjs").write_text("function beta() { return 2; }\n")
+
+        graph = JavaScriptParser().parse_directory(str(tmp_path))
+
+        names = {n.name for n in graph.nodes.values()}
+        assert "alpha" in names
+        assert "beta" in names
+
     def test_rest_parameter(self) -> None:
         graph = _parse_extra()
         fn = next(n for n in graph.nodes.values() if n.name == "withRest")

tests/test_polyglot.py

@@ -46,6 +46,11 @@ def test_skips_vendor_directories(self, tmp_path: Path) -> None:
     def test_missing_path_returns_empty(self, tmp_path: Path) -> None:
         assert detect_languages(str(tmp_path / "does-not-exist")) == []
 
+    def test_detects_modern_javascript_module_extensions(self, tmp_path: Path) -> None:
+        (tmp_path / "route.mjs").write_text("export function handler() {}\n")
+        (tmp_path / "worker.cjs").write_text("function worker() {}\n")
+        assert detect_languages(str(tmp_path)) == ["javascript"]
+
 
 class TestFromDirectoryAuto:
     def test_auto_detects_and_merges(self, tmp_path: Path) -> None:
@@ -117,3 +122,9 @@ def test_single_language_preserved(self, tmp_path: Path) -> None:
         surface = engine.attack_surface()
         assert len(surface) == 1
         assert surface[0]["node_id"] == "a:main"
+
+    def test_auto_parses_mjs_files_into_nodes(self, tmp_path: Path) -> None:
+        (tmp_path / "route.mjs").write_text("export function handler() { return 1; }\n")
+        engine = QueryEngine.from_directory(str(tmp_path), language="auto")
+        summary = engine.summary()
+        assert summary["functions"] >= 1

tests/test_readme.py

@@ -16,7 +16,9 @@
 
 import pytest
 
+import trailmark
 from trailmark.cli import build_parser
+from trailmark.parsers.javascript.parser import _EXTENSIONS as JS_EXTENSIONS
 from trailmark.query.api import _PARSER_MAP, QueryEngine
 
 
@@ -72,6 +74,20 @@ def test_python_version_matches_pyproject(
             )
 
 
+class TestPackageMetadata:
+    def test_dunder_version_matches_pyproject(
+        self,
+        pyproject_data: dict[str, object],
+    ) -> None:
+        """`trailmark.__version__` should match the packaged version."""
+        project_raw = pyproject_data.get("project")
+        assert isinstance(project_raw, dict), "pyproject.toml has no [project] table"
+        project = cast("dict[str, object]", project_raw)
+        version = project.get("version")
+        assert isinstance(version, str), "project.version is missing or not a string"
+        assert trailmark.__version__ == version
+
+
 class TestUsageSection:
     @pytest.fixture(scope="class")
     def cli_subcommands(self) -> set[str]:
@@ -108,6 +124,11 @@ def test_every_registered_parser_is_documented(self, readme_text: str) -> None:
                 f"Parser `{key}` is registered but not documented in README"
             )
 
+    def test_javascript_extensions_match_parser(self, readme_text: str) -> None:
+        """README's JavaScript extension list should match the parser."""
+        extensions = _extract_extensions_for_language(readme_text, "JavaScript")
+        assert set(extensions) == set(JS_EXTENSIONS)
+
 
 class TestQueryEngineAPI:
     EXPECTED_METHODS = (
@@ -125,6 +146,12 @@ class TestQueryEngineAPI:
         "nodes_with_annotation",
         "clear_annotations",
         "diff_against",
+        "preanalysis",
+        "augment_sarif",
+        "augment_weaudit",
+        "findings",
+        "subgraph",
+        "subgraph_names",
         "summary",
         "to_json",
     )
@@ -257,3 +284,22 @@ def _extract_languages_from_readme(readme_text: str) -> list[str]:
         langs.append(first_cell)
     assert langs, "No language rows parsed from Supported Languages table"
     return langs
+
+
+def _extract_extensions_for_language(readme_text: str, language: str) -> list[str]:
+    """Return the parsed extension list from a README Supported Languages row."""
+    section = re.search(
+        r"### Supported Languages\s*\n(.*?)(?=\n###|\n## )",
+        readme_text,
+        re.DOTALL,
+    )
+    assert section, "Could not find '### Supported Languages' section in README"
+    for line in section.group(1).splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if len(cells) < 2 or cells[0] != language:
+            continue
+        return [item.strip().strip("`") for item in cells[1].split(",") if item.strip()]
+    raise AssertionError(f"Could not find `{language}` row in Supported Languages table")