graphlm 0.4.2__tar.gz → 0.6.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {graphlm-0.4.2 → graphlm-0.6.0}/.github/workflows/ci.yml +16 -7
- {graphlm-0.4.2 → graphlm-0.6.0}/.github/workflows/release.yml +11 -8
- {graphlm-0.4.2 → graphlm-0.6.0}/CHANGELOG.md +135 -1
- graphlm-0.6.0/CLAUDE.md +90 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/DECISIONS.md +243 -0
- graphlm-0.6.0/DEMO.md +91 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/INNOVATIONS.md +249 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/PKG-INFO +17 -10
- {graphlm-0.4.2 → graphlm-0.6.0}/README.md +14 -9
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/__init__.py +132 -66
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/_html_template.html +6 -2
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/cli.py +131 -6
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/context.py +61 -23
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/cycles.py +30 -0
- graphlm-0.6.0/graphlm/cycles_render.py +103 -0
- graphlm-0.6.0/graphlm/degree.py +48 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/diff.py +61 -12
- graphlm-0.6.0/graphlm/enrich.py +128 -0
- graphlm-0.6.0/graphlm/evidence.py +418 -0
- graphlm-0.6.0/graphlm/exclusions.py +95 -0
- graphlm-0.6.0/graphlm/freshness.py +195 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/html_render.py +82 -30
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/mcp_server.py +23 -1
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/mermaid.py +72 -13
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/models.py +105 -1
- graphlm-0.6.0/graphlm/orientation.py +70 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/cpp.py +32 -12
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/csharp.py +33 -11
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/go.py +19 -2
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/java.py +5 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/php.py +105 -24
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/python.py +7 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/rust.py +8 -1
- graphlm-0.6.0/graphlm/pathnorm.py +18 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/query.py +123 -17
- graphlm-0.6.0/graphlm/redact.py +297 -0
- graphlm-0.6.0/graphlm/render.py +521 -0
- graphlm-0.6.0/graphlm/scan_guards.py +111 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/scanner.py +27 -161
- graphlm-0.6.0/graphlm/setup.py +341 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/skills.py +6 -3
- graphlm-0.6.0/graphlm/telemetry_render.py +104 -0
- graphlm-0.6.0/graphlm/testpaths.py +34 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/pyproject.toml +9 -3
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_cli.py +193 -10
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_context.py +89 -2
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_cycles.py +96 -0
- graphlm-0.6.0/tests/test_degree.py +104 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_diff.py +49 -1
- graphlm-0.6.0/tests/test_evidence.py +441 -0
- graphlm-0.6.0/tests/test_freshness.py +150 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_html_render.py +70 -3
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_integration.py +256 -2
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_mcp_server.py +12 -1
- graphlm-0.6.0/tests/test_orientation.py +142 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser.py +12 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser_cpp.py +36 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser_csharp.py +112 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser_go.py +35 -0
- graphlm-0.6.0/tests/test_parser_php.py +221 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser_rust.py +14 -0
- graphlm-0.6.0/tests/test_pathnorm.py +23 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_query.py +141 -1
- graphlm-0.6.0/tests/test_render.py +1439 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_scanner.py +440 -8
- graphlm-0.6.0/tests/test_setup.py +321 -0
- graphlm-0.6.0/tests/test_testpaths.py +51 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/uv.lock +229 -200
- graphlm-0.4.2/CLAUDE.md +0 -83
- graphlm-0.4.2/DEMO.md +0 -21
- graphlm-0.4.2/graphlm/redact.py +0 -188
- graphlm-0.4.2/graphlm/render.py +0 -428
- graphlm-0.4.2/tests/test_parser_php.py +0 -115
- graphlm-0.4.2/tests/test_render.py +0 -769
- {graphlm-0.4.2 → graphlm-0.6.0}/.env.example +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/.gitignore +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/CODE_OF_CONDUCT.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/CONTRIBUTING.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/LICENSE +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/SECURITY.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/docs/plans/PHASE1-HANDOFF.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/docs/plans/multi-language-implementation.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/docs/plans/multi-language-support.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/docs/plans/self-refreshing-graph.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/config.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/faithfulness.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/llm.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parser.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/base.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/parsers/javascript.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/prompts.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/provenance.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/graphlm/upgrade.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/innovation/DEMO.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/innovation/feat-ast-parser/DEMO.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/innovation/mcp-serve/DEMO.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/innovation/mermaid-ground-truth/DEMO.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/innovation/run-telemetry/DEMO.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/innovation/skeletons/DEMO.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/conftest.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/app.cpp +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/bar/baz.c +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/bar/baz.h +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/cycle_a.h +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/cycle_b.h +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/foo.c +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/foo.h +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/main.c +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cpp_project/src/qux.hpp +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/csharp_project/src/MyApp/Helpers/Util.cs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/csharp_project/src/MyApp/Models/User.cs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/csharp_project/src/MyApp/Program.cs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/csharp_project/src/MyApp/Services/UserService.cs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/csharp_project/src/MyApp/TooMany/A.cs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/csharp_project/src/MyApp/TooMany/B.cs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cyclic_project/app/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cyclic_project/app/main.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cyclic_project/app/routes.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/cyclic_project/app/services.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/go_project/foo/foo.go +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/go_project/main.go +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/go_project/pkg/pkg.go +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/go_project/rel/rel.go +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/go_project/toomany/a.go +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/go_project/toomany/b.go +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/.godot/cache.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/.graphlmignore +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/app.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/keep.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/notes.txt +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/tmp.generated.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ignore_project/vendor/lib.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/java_project/src/main/java/com/acme/App.java +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/java_project/src/main/java/com/acme/model/User.java +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/java_project/src/main/java/com/acme/service/UserService.java +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/java_project/src/main/java/com/acme/util/Helpers.java +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/java_project/src/main/java/com/acme/util/More.java +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/java_project/src/test/java/com/acme/AppTest.java +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/README.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/main.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/models/item.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/models/user.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/routes/items.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/routes/users.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/services/auth.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/services/item_service.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/app/services/user_service.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/docs/overview.md +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/migrations/001_create_users.sql +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/migrations/002_create_items.sql +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/pyproject.toml +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/static/css/app.css +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/static/js/app.js +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/templates/base.html +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/tests/test_auth.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/tests/test_items.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/large_project/tests/test_users.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/migrations/001_initial.sql +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/pyproject.toml +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/src/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/src/core/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/src/utils/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/tests/test_engine.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/medium_project/tests/test_utils.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/php_project/src/App/Models/User.php +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/php_project/src/App/Services/UserService.php +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/php_project/src/App/bootstrap.php +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/php_project/src/App/index.php +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/php_project/src/App/rel.php +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/rust_project/src/bar.rs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/rust_project/src/foo.rs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/rust_project/src/lib.rs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/rust_project/src/nested/deep.rs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/rust_project/src/nested/mod.rs +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/skeleton_project/big_module.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/small_project/main.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/small_project/mylib/__init__.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/small_project/mylib/helpers.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/small_project/pyproject.toml +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/small_project/test_helpers.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/Button.tsx +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/bar.ts +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/foo.ts +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/index.ts +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/nested/deep.ts +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/nested/legacy.js +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/util/helper.ts +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/fixtures/ts_project/src/util/index.ts +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_config.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_faithfulness.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_llm.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_models.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_packaging.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser_java.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_parser_javascript.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_prompts.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_provenance.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_skeleton.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_skills.py +0 -0
- {graphlm-0.4.2 → graphlm-0.6.0}/tests/test_upgrade.py +0 -0
|
@@ -21,12 +21,15 @@ jobs:
|
|
|
21
21
|
python-version: ["3.11", "3.12", "3.13"]
|
|
22
22
|
|
|
23
23
|
steps:
|
|
24
|
-
- uses: actions/checkout@
|
|
24
|
+
- uses: actions/checkout@v7
|
|
25
25
|
|
|
26
26
|
- name: Set up uv
|
|
27
|
-
uses: astral-sh/setup-uv@
|
|
27
|
+
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
28
28
|
with:
|
|
29
29
|
enable-cache: true
|
|
30
|
+
prune-cache: true
|
|
31
|
+
cache-dependency-glob: "**/uv.lock"
|
|
32
|
+
cache-suffix: "test-py${{ matrix.python-version }}"
|
|
30
33
|
|
|
31
34
|
- name: Set up Python ${{ matrix.python-version }}
|
|
32
35
|
run: uv python install ${{ matrix.python-version }}
|
|
@@ -40,7 +43,7 @@ jobs:
|
|
|
40
43
|
run: uv run pytest --cov=graphlm --cov-report=xml --cov-report=term-missing -v
|
|
41
44
|
|
|
42
45
|
- name: Upload coverage
|
|
43
|
-
uses: codecov/codecov-action@
|
|
46
|
+
uses: codecov/codecov-action@v6
|
|
44
47
|
if: matrix.python-version == '3.13'
|
|
45
48
|
with:
|
|
46
49
|
files: ./coverage.xml
|
|
@@ -53,12 +56,15 @@ jobs:
|
|
|
53
56
|
test-packs:
|
|
54
57
|
runs-on: ubuntu-latest
|
|
55
58
|
steps:
|
|
56
|
-
- uses: actions/checkout@
|
|
59
|
+
- uses: actions/checkout@v7
|
|
57
60
|
|
|
58
61
|
- name: Set up uv
|
|
59
|
-
uses: astral-sh/setup-uv@
|
|
62
|
+
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
60
63
|
with:
|
|
61
64
|
enable-cache: true
|
|
65
|
+
prune-cache: true
|
|
66
|
+
cache-dependency-glob: "**/uv.lock"
|
|
67
|
+
cache-suffix: "test-packs"
|
|
62
68
|
|
|
63
69
|
- name: Set up Python
|
|
64
70
|
run: uv python install 3.12
|
|
@@ -72,12 +78,15 @@ jobs:
|
|
|
72
78
|
typecheck:
|
|
73
79
|
runs-on: ubuntu-latest
|
|
74
80
|
steps:
|
|
75
|
-
- uses: actions/checkout@
|
|
81
|
+
- uses: actions/checkout@v7
|
|
76
82
|
|
|
77
83
|
- name: Set up uv
|
|
78
|
-
uses: astral-sh/setup-uv@
|
|
84
|
+
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
79
85
|
with:
|
|
80
86
|
enable-cache: true
|
|
87
|
+
prune-cache: true
|
|
88
|
+
cache-dependency-glob: "**/uv.lock"
|
|
89
|
+
cache-suffix: "typecheck"
|
|
81
90
|
|
|
82
91
|
- name: Set up Python
|
|
83
92
|
run: uv python install 3.12
|
|
@@ -37,12 +37,15 @@ jobs:
|
|
|
37
37
|
name: Build & smoke-test
|
|
38
38
|
runs-on: ubuntu-latest
|
|
39
39
|
steps:
|
|
40
|
-
- uses: actions/checkout@
|
|
40
|
+
- uses: actions/checkout@v7
|
|
41
41
|
|
|
42
42
|
- name: Set up uv
|
|
43
|
-
uses: astral-sh/setup-uv@
|
|
43
|
+
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
44
44
|
with:
|
|
45
45
|
enable-cache: true
|
|
46
|
+
prune-cache: true
|
|
47
|
+
cache-dependency-glob: "**/uv.lock"
|
|
48
|
+
cache-suffix: "release"
|
|
46
49
|
|
|
47
50
|
- name: Set up Python
|
|
48
51
|
run: uv python install 3.12
|
|
@@ -75,7 +78,7 @@ jobs:
|
|
|
75
78
|
print('ok:', p)"
|
|
76
79
|
|
|
77
80
|
- name: Upload build artifacts
|
|
78
|
-
uses: actions/upload-artifact@
|
|
81
|
+
uses: actions/upload-artifact@v7
|
|
79
82
|
with:
|
|
80
83
|
name: dist
|
|
81
84
|
path: dist/
|
|
@@ -88,16 +91,16 @@ jobs:
|
|
|
88
91
|
permissions:
|
|
89
92
|
contents: write # create the release + upload assets
|
|
90
93
|
steps:
|
|
91
|
-
- uses: actions/checkout@
|
|
94
|
+
- uses: actions/checkout@v7
|
|
92
95
|
|
|
93
96
|
- name: Download build artifacts
|
|
94
|
-
uses: actions/download-artifact@
|
|
97
|
+
uses: actions/download-artifact@v7
|
|
95
98
|
with:
|
|
96
99
|
name: dist
|
|
97
100
|
path: dist/
|
|
98
101
|
|
|
99
102
|
- name: Create GitHub Release
|
|
100
|
-
uses: softprops/action-gh-release@
|
|
103
|
+
uses: softprops/action-gh-release@v3
|
|
101
104
|
with:
|
|
102
105
|
files: dist/*
|
|
103
106
|
generate_release_notes: true
|
|
@@ -121,7 +124,7 @@ jobs:
|
|
|
121
124
|
id-token: write # Trusted Publishing (OIDC) — no API token secret
|
|
122
125
|
steps:
|
|
123
126
|
- name: Download build artifacts
|
|
124
|
-
uses: actions/download-artifact@
|
|
127
|
+
uses: actions/download-artifact@v7
|
|
125
128
|
with:
|
|
126
129
|
name: dist
|
|
127
130
|
path: dist/
|
|
@@ -141,7 +144,7 @@ jobs:
|
|
|
141
144
|
id-token: write
|
|
142
145
|
steps:
|
|
143
146
|
- name: Download build artifacts
|
|
144
|
-
uses: actions/download-artifact@
|
|
147
|
+
uses: actions/download-artifact@v7
|
|
145
148
|
with:
|
|
146
149
|
name: dist
|
|
147
150
|
path: dist/
|
|
@@ -7,6 +7,138 @@ and this project adheres to Semantic Versioning.
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.6.0] - 2026-09-23
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- **A fresh run leaves the output dir with exactly the artifacts it produced.** When graphlm regenerates a map — especially after an upgrade, or when you toggle a flag like `--json` — it now removes its *own* stale artifacts (e.g. a `GRAPH.json` left over from a prior version) so an agent can't glob an outdated machine-readable map beside a fresh `GRAPH.md`. Only graphlm's own exact artifact names are ever removed (never a directory, never a glob, symlinks skipped) — your `GRAPHICS.md` / `graph.json` / `GRAPH_notes.md` are untouched. When the prior map came from a **different graphlm version**, `GRAPH_DIFF` now says so explicitly ("prior graph from graphlm 0.5.0 — regenerated fresh under 0.6.0, not compared") instead of misreporting it as a first run or a corrupt file; the diff JSON gains `old_graphlm_version` / `new_graphlm_version` and its `diff_schema_version` is bumped to 2. `GRAPH.md`'s provenance line now names the graphlm version that produced it, and `GRAPH.html` embeds it as machine-readable data.
|
|
15
|
+
- **`GRAPH.json` is now opt-in (`--json`); the default outputs are `GRAPH.md` + `GRAPH.html`.** The Markdown map is the artifact a coding agent should read — the JSON's node/link arrays fill a context window far faster for the same information — so the CLI no longer writes `GRAPH.json` (or `GRAPH_DIFF.json`) unless you pass `--json`. Nothing else changes: graphlm keeps an internal JSON working copy (`.graphlm/.graph-state.json`) on every run, so the graph-vs-graph diff and `graphlm --serve` (MCP) work exactly as before with or without `--json`. The **library** default is unchanged — `generate_graph(output_dir=...)` and `GraphResult.write(...)` still write `GRAPH.json` by default (new `include_json=` param to opt out), so `md, json, html = result.write(dir)` and `load_map(".graphlm/GRAPH.json")` keep working (`write_outputs` now also runs the fresh-run cleanup described above). Upgrading users: a prior-version `.graphlm/GRAPH.json` is cleaned up automatically on the next run rather than left stale (and the diff reports the version change instead of a false "first run"). Note `--no-html` / `--no-diff` now also remove a prior `.html` / `_DIFF.*` they used to leave in place.
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **`GRAPH.md` opens with a compact orientation block.** The map's highest-signal facts — entry points, whether there are any production import cycles, and the highest-fan-in (blast-radius) files — used to sit hundreds of lines down, after a full directory tree, so an agent (or a human verifying the map) burned context scrolling to find the shape of the repo. A short `## Orientation` section now sits right under the provenance directive, before the directory tree. Fan-in is labelled "most imported (blast radius)", never "importance" — raw import degree measures reach, not architectural weight (ADR-015). The block is a summary of data still rendered in full below, omits any line it has no data for, and is absent entirely when the graph has no entry points, cycles, or edges. The MCP `overview` tool gains matching `production_cycles` / `test_only_cycles` counts and shares the same fan-in computation.
|
|
20
|
+
- **Test-code import cycles are labelled, not hidden.** graphlm's map treated a cycle among test files (fixtures, test helpers) exactly like a production cycle — so a repo with deliberately-cyclic parser fixtures showed "5 import cycles" at the top of its map, misleading an agent into thinking the *product* had circular imports. Cycles whose every member is a test file are now flagged (`Cycle.test_only`, and `test_only` / `production_count` / `test_only_count` on the MCP `cycles` tool) and rendered distinctly across all outputs: `GRAPH.md` lists production cycles first and groups test-code cycles under their own heading (with a clear "no production cycles" banner when *all* cycles are among tests); the Mermaid module graph outlines and colours test-only cycles in muted amber instead of alarming red; and `GRAPH.html` mutes test-file nodes. Tests remain fully in the map — this labels them, it does not drop them (`--no-tests` still does that). The label is derived deterministically from the file path and is exactly the set `--no-tests` would remove.
|
|
21
|
+
|
|
22
|
+
### Infrastructure
|
|
23
|
+
|
|
24
|
+
- **Module-size refactor: no module exceeds the 600-line limit.** `scanner.py`'s exclusion patterns and filesystem guards split into `exclusions.py` (`_ALWAYS_EXCLUDE`, `_should_exclude`) and `scan_guards.py` (`_symlink_hides_sensitive`, `_is_nested_checkout`, `_path_is_inside`, `load_graphlmignore`); `__init__.py`'s post-pass-2 enrichment helpers split into `enrich.py` (`build_meta`, `pass_usage`, `is_directory_granular`, `score_file_importance` — now public, un-underscored). A dead duplicate `_is_nested_checkout` in `redact.py` (unused since #54) was removed. Zero behaviour change; the public `graphlm` import surface (`generate_graph`, `GraphResult`, `WriteResult`) is unchanged.
|
|
25
|
+
|
|
26
|
+
## [0.5.0] - 2026-09-22
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
- **Module importance ranking (`GRAPH.md` Importance column, TypeSafe/Jev).** The map listed modules but never said which were load-bearing — and raw import degree can't tell "imported everywhere" (a constants file) from "central to the architecture" (the orchestrator). Each module now carries a semantic **role** score (Jev: leaf → orchestrator) alongside its structural **degree** (parser ground truth); `GRAPH.md`'s Modules table gains an Importance column that fuses the two and sorts load-bearing first. The two components are stored raw in `GRAPH.json` (not a pre-blended number) so the display weighting can change without rewriting the map, and the CLI prints the top load-bearing modules. On a real project this correctly demoted a constants module from degree-#1 to importance-#5 and promoted a low-degree entry point. On **large repos** where the model describes modules at *directory* granularity (`src/pkg/sub`), importance is scored over the file-level `file_summaries` instead and rendered as a separate `## File Importance` section in `GRAPH.md` (stamped into `meta.file_importance`), and the CLI prints the top load-bearing files — a pre-registered evaluation measured the ranking gap over raw degree jump from +0.01 to +0.11 when scoring files rather than packages. Best-effort and off (both fields null) without a `TYPESAFE_API_KEY` or the `graphlm[typesafe]` extra; unlike summary scoring it is **not** disabled by `--no-redact` (it sends descriptions and a degree count, never source). When off, the Modules table is unchanged. Opt out with `--no-importance`.
|
|
31
|
+
- **Summary evidence-support scoring (`meta.evidence_support`, TypeSafe/Jev).** graphlm could vouch for its import *edges* (the LLM's edge list vs. the parser's ground truth) but nothing checked whether the model's *prose* — the per-file summaries — was actually backed by the source it read. Each summary is now scored against the exact fragment the model saw (redacted/skeletonised text, not the file on disk) as a calibrated 0–1 support probability, and the mean plus the weakest files are stamped into `GRAPH.json` and shown on the CLI. Like edge-faithfulness it is a *trust weight*, not a hallucination verdict — a skeletonised or truncated fragment honestly scores lower. Best-effort and off by default unless the `graphlm[typesafe]` extra is installed, a `TYPESAFE_API_KEY` is set, and redaction is on (the source must not reach a third party unredacted); it never runs on a dry run and never blocks or discards a graph. Near-empty files (a bare-docstring `__init__.py`, a thin entry point that defines nothing) are skipped rather than scored — there is nothing to verify a claim against, so scoring them produced a meaningless ~0.2 that falsely flagged correct minimal summaries as weak (#168). Opt out with `--no-evidence`.
|
|
32
|
+
- **First-run setup wizard (`graphlm --setup`, and an automatic first-use prompt).** graphlm's optional capabilities — the language-grammar packs, the `mcp` server, and the new `typesafe` prose-scoring SDK — were undiscoverable: a user never learned their JS/TS files produced zero edges because the `[js]` wheel wasn't installed. The wizard lists the not-yet-installed packs, installs the chosen ones with the **same installer that put graphlm on PATH** (uv tool / uv pip / pipx / pip, keeping any packs already present), and — for TypeSafe — tells you to add `TYPESAFE_API_KEY` to `~/.config/graphlm/.env`. It runs automatically the first time graphlm is used interactively (a `~/.config/graphlm/.setup-done` marker stops it firing again); a non-interactive/CI run prints a one-line hint and proceeds without blocking, and a source checkout is refused. No optional pack becomes a base dependency.
|
|
33
|
+
- **New optional extra `graphlm[typesafe]`** (the TypeSafe/Jev SDK), offered by the setup wizard and consumed by the evidence-support scoring above. It is opt-in — never a base dependency and not part of `graphlm[all]` — because it calls a commercial third-party API and needs a key.
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- **Empty-user connection URIs (`redis://:secret@host`) and escaped quotes inside quoted passwords are redacted.** The URI regex required a username; the quoted-password matcher stopped at the next raw `"`.
|
|
38
|
+
- **Truncated PEM bodies are redacted after a leftover BEGIN header.** Head-truncation can cut before `END`; the full-block regex then misses and only the BEGIN line was replaced, leaving `MIIE…` in the fragment.
|
|
39
|
+
- **In-project symlinks into a `.graphlmignore` / `--exclude` tree are not scanned.** `config.yaml → secrets/prod.yaml` used to be read because the symlink guard only screened never-read names and `_ALWAYS_EXCLUDE`, not the user's exclude set.
|
|
40
|
+
- **In-project symlinks into `.git/` (and other always-excluded dirs) are not scanned.** `utils.py → .git/config` used to be read because the never-read check only screened secret *filenames*, while the walk already refuses `.git`.
|
|
41
|
+
- **`tests/src/` is not treated as a Python/Java/PHP source root.** #19 rejected `tests/stub/requests` but any nested `src`/`lib`/`python` still became a root, so `import requests` resolved onto `tests/src/requests` (#161).
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
- **`graphlm /symlink/to/project` writes GRAPH.* into the real checkout.** The ancestor-symlink write refusal treated the symlink project path as a planted decoy and exited 2 after the paid LLM calls. The default destination now `resolve()`s the project; `-o` stays literal (#154).
|
|
47
|
+
|
|
48
|
+
- **Quoted passwords that contain spaces are redacted.** The value class was `[^\s…]`, so `"password": "hello world secret"` in JSON and `password = "hello world"` survived.
|
|
49
|
+
- **Rust `mod foo;` is no longer dropped when a preceding attribute merely contains the word `path`.** `#[cfg(feature = "path")]` was treated as `#[path = "..."]` because the detector was `b"path" in node.text`. Only a real `#[path = "..."]` is skipped now (#153).
|
|
50
|
+
|
|
51
|
+
- **TLS/SRV connection-string passwords are redacted.** The URI regex required `mongodb://` / `redis://` / `amqp://` with no suffix, so `mongodb+srv://`, `rediss://`, and `amqps://` (Atlas / Redis TLS / AMQP TLS) kept the password.
|
|
52
|
+
|
|
53
|
+
- **`.npmrc` / `.yarnrc` / `.pypirc` are never read.** `_auth=base64(user:pass)` and `https://user:pass@` in `.npmrc` are not `password=` assignments, so redaction left short logins intact and pass 2 could send them.
|
|
54
|
+
- **`.keystore` and backups of secret extensions (`app.jks.bak`, `server.key~`) are never read.** Android `debug.keystore` missed the `.jks` list, and backup matching only covered exact names, so binary keystore bytes were scanned.
|
|
55
|
+
|
|
56
|
+
- **`BEGIN ENCRYPTED PRIVATE KEY` PEM bodies are redacted.** The PKCS#8 encrypted label was not in `(RSA |EC |DSA |OPENSSH )?`, so JSON keystores sent the ciphertext body.
|
|
57
|
+
|
|
58
|
+
- **PHP interpolated double-quoted `require "config.php$id"` is not a static include.** The extractor took the first `string_content` chunk and emitted `a.php → config.php`. Interpolation is now a policy drop (same as concat) and marks known-partial (#147).
|
|
59
|
+
|
|
60
|
+
- **`.htpasswd`, singular `secret.yaml`, and `*.env` / `foo.env.local` are never read.** `*secrets*` missed `secret.yaml`; `.htpasswd` is not `*password*`; `config.env` is not a leading `.env`. Those files were scanned with hashes and keys intact.
|
|
61
|
+
|
|
62
|
+
- **JSON `"secret"` / `"token"` / `"auth"` colon assignments and PEM bodies are redacted.** PR 139 covered `"password"` / `"api_key"`; the generic secret regex still required `=`, and private-key redaction only rewrote BEGIN/END, so `client_secret.json` and a PEM body in JSON survived.
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
- **`write_outputs` refuses to write through a symlink, including ancestor directory links.** `GRAPH.json` (or `.graphlm` itself) as a symlink used to be followed, and a parent `decoy → victim` plus `-o decoy/out` still wrote GRAPH.* into `victim`. Same contract as skill install (#33): remove the symlink and re-run.
|
|
66
|
+
|
|
67
|
+
- **GRAPH.html no longer lets `{_PALETTE}` in graph data steal the template placeholder.** Palette substitution ran after JSON embed, so a node path or description containing `{_PALETTE}` spliced the color array into `graphData` and left `const _PALETTE = {_PALETTE}`. Palette is substituted first (#141).
|
|
68
|
+
|
|
69
|
+
- **`--serve` path resolution no longer maps `a.py` onto `data.py`.** After exact/suffix/prefix matching, `resolve_path` used unanchored `query in path`, so a unique `'a.py' in 'data.py'` returned the wrong module as `found: True`. File-like queries (basename containing `.`) skip that fallback; extensionless unique names like `core` still match (#140).
|
|
70
|
+
|
|
71
|
+
- **JSON `"password"` / `"api_key"` assignments are redacted.** The assignment regexes required the keyword to sit immediately before `=`/`:`, so `"password": "…"` in `appsettings.json` survived. Optional quotes around the key are now accepted.
|
|
72
|
+
|
|
73
|
+
- **Backups of `.netrc` / `_netrc` / `.pgpass` / `.flaskenv` are never read.** Exact-name matching skipped `.netrc.bak` / `.pgpass~` / `.flaskenv.bak`; netrc and pgpass secrets are not `password=` assignments, so redaction left them intact.
|
|
74
|
+
|
|
75
|
+
- **PHP `require 'x.php' or die()` is extracted.** The quoted path is a string literal; tree-sitter wraps it in a logical `binary_expression`. The unwraper treated every binary as concat (`__DIR__ . "/x.php"`), so a common include form produced no edge. Logical `or` / `||` are unwrapped; concat still drops (#135).
|
|
76
|
+
|
|
77
|
+
- **C# namespace alias `using Models = MyApp.Models;` no longer resolves onto a parent `MyApp.cs`.** #126 stopped the nested-type parent probe for a plain namespace using; aliases still ran it first, so a namespace alias preferred `MyApp.cs` over unique-dir `Models/User.cs`. Aliases now unique-dir first and only parent-probe when that misses (#134).
|
|
78
|
+
|
|
79
|
+
- **Dotenv editor backups and non-dot suffixes (`.env~`, `.env-local`) are never read.** Never-read required `.env` or `.env.<suffix>`, so vim `.env~` and `.env-local` / `.env_backup` were scanned; assignment redaction cannot catch arbitrary `VAR=secret` lines.
|
|
80
|
+
|
|
81
|
+
- **PHP class `use App\Models\User` no longer resolves onto `Models.php`.** The parent-file probe (last-segment strip) ran for every FQN, so a missing `User.php` became a false edge to the parent type. That probe now runs only for `use function` / `use const` (ADR-011) (#129).
|
|
82
|
+
|
|
83
|
+
- **C++ `#include "foo.h"` no longer resolves onto a sibling `foo.c`.** The extension probe stripped `.h` and retried `.c`/`.hpp`/…, so a missing local header became a false include of the implementation file (and a self-edge from `foo.c`). The probe now runs only for extensionless `#include "foo"` (ADR-008) (#128).
|
|
84
|
+
|
|
85
|
+
- **`.envrc` and `.flaskenv` are never read.** They are dotenv-class secret stores that are not `.env.<suffix>`, so they were scanned; assignment redaction cannot catch arbitrary `VAR=secret` lines.
|
|
86
|
+
- **GitHub fine-grained PATs (`github_pat_`) are redacted.** The dedicated GitHub regex only matched classic `ghp_` / `gho_` / … prefixes, so a bare `github_pat_…` in a comment survived.
|
|
87
|
+
|
|
88
|
+
- **Go raw-string import literals are extracted.** `import \`./rel\`` is valid Go; the extractor only accepted interpreted `"..."` strings, so those edges were missing (#122).
|
|
89
|
+
|
|
90
|
+
- **PHP `require("x.php")` and grouped `use A\{B, C}` are extracted.** Parenthesized require wrapped the string in `parenthesized_expression` and was treated as a policy drop (#120). Grouped PSR-12 `use` nested clauses under `namespace_use_group` and produced no edges (#121).
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
- **In-project symlinks to never-read files are not scanned.** `crypto.py → .env` (or `id_rsa`) used to be read because the never-read check used the *link name* while `read_text` followed the target. The resolved target is now screened too.
|
|
94
|
+
|
|
95
|
+
- **PHP quoted `require`/`include` inside `if` or a function is extracted.** Only root `expression_statement` nodes were visited, so `if (true) { require "b.php"; }` produced no include edge and did not mark known-partial (#114).
|
|
96
|
+
|
|
97
|
+
- **C# `using` inside `namespace { }` is extracted.** StyleCop SA1200 puts usings in the block; the walker only looked at root / file-scoped namespace children, so those edges were missing (#113).
|
|
98
|
+
|
|
99
|
+
- **Pass 1 `requested_files: null` no longer aborts after a paid LLM call.** Free-form JSON with `null` or a string used to `TypeError` in `filter_requested_files` (or silently match zero files). Non-list / non-string entries are now treated as “request nothing” and pass 2 still runs (#115).
|
|
100
|
+
|
|
101
|
+
- **`write_outputs` refuses to write through a symlink.** `GRAPH.json` (or `.graphlm` itself) as a symlink used to be followed, so a cloned repo could clobber a file outside the output dir. Same contract as skill install (#33): remove the symlink and re-run.
|
|
102
|
+
|
|
103
|
+
- **`latest.py` is ranked as source, not as a test.** After #94, `_rank_file` still used `"test" in stem`, so `latest.py` (rank 10) lost to markdown (rank 8) under a tight `max_files` cap and never reached pass 2 / AST (#109).
|
|
104
|
+
|
|
105
|
+
- **`.netrc` / `_netrc` / `.pgpass` are never read.** They hold passwords in layouts the assignment regex does not match (`machine host login user password SECRET`, `host:port:db:user:SECRET`), so they were scanned verbatim.
|
|
106
|
+
- **OpenSSH vim/emacs private-key backups (`id_rsa~`, `#id_rsa#`) are never read.** The `.bak` / `.old` prefix rule missed editor backup names, and redaction still only strips BEGIN/END, so the key body was scanned.
|
|
107
|
+
- **OpenSSH private-key *backups* are never read.** Exact-name matching skipped `id_rsa.bak` / `id_ed25519.old`, and redaction only strips BEGIN/END, so the key body was still sent. Names that start with `id_rsa.` / `id_rsa-` (except `.pub`) are now never-read too.
|
|
108
|
+
|
|
109
|
+
- **In-project directory symlinks no longer explode or ghost the pass-1 tree.** `_walk_dir` followed `Path.is_dir()` into a `sub/loop → root` cycle (165 lines of `loop/sub/loop/...`) and listed `alias/mod.py` for a `alias → pkg` link that `os.walk` never reads. Directory symlinks are skipped in the tree, matching `followlinks=False` (#97).
|
|
110
|
+
|
|
111
|
+
- **C/C++ quoted `#include` inside `#ifdef` is extracted.** Only root-child `preproc_include` nodes were visited, so a guarded `#include "bar.h"` never became an AST edge. The walker now visits nested preprocessor nodes (byte offsets only, never `start_point`) (#99).
|
|
112
|
+
|
|
113
|
+
- **Pass-2's file cap keeps the files pass 1 asked for first.** `filter_requested_files` sorted by path then sliced, so `--max-pass2-files` dropped `z.py` in favour of `a.py`. The cap now follows request order; the kept set is still sorted for deterministic output (#98).
|
|
114
|
+
|
|
115
|
+
- **GRAPH.html and the Mermaid module graph honour `./`-prefixed LLM paths.** Cycle nodes from `detect_cycles` are normalised (#84) but renderers still compared raw `./a.py`, so `--no-ast` cycles got no red ring and collapsed to a bogus `.` node. Node ids, link pairs, and directory collapse now strip `./` (#96).
|
|
116
|
+
|
|
117
|
+
- **Go stdlib imports no longer resolve onto a unique local package directory.** `import "fmt"` with a scanned `fmt/fmt.go` (or `import "encoding/json"` with `json/json.go`) emitted a do-not-contradict AST edge. Specifiers with no `.` are treated as stdlib and dropped; dotted module paths still suffix-strip per ADR-010 (#95).
|
|
118
|
+
|
|
119
|
+
- **`--no-tests` no longer drops modules whose names merely contain `test`.** `latest.py`, `contest.py`, and `testing.py` were skipped because the scanner used `"test" in stem`. It now matches real test conventions (`test_*`, `*_test`, `*.test.*`, `tests/` / `test/` / `__tests__/`) and the tree walk uses the same predicate (#94).
|
|
120
|
+
|
|
121
|
+
- **`GRAPHLM_TIMEOUT` is honoured when the LLM endpoint is passed on the CLI.** `-b/-k/-m` (or `generate_graph(base_url=..., api_key=..., model=...)`) used to build a `Settings` with the dataclass default 300s and skip the env, so a raised timeout never reached pass 2. Timeout now resolves like `--max-context`: flag > env > 300 (#92).
|
|
122
|
+
|
|
123
|
+
- **OpenSSH private-key filenames are never read.** `id_rsa` / `id_ed25519` / `id_ecdsa` (and the `_sk` variants) have no extension, so they missed both the `.key`/`.pem` list and the `*private*` name glob. The key body was scanned (only the BEGIN/END headers were redacted). Those names are now on the never-read list; `id_rsa.pub` stays scannable.
|
|
124
|
+
|
|
125
|
+
- **GRAPH.html no longer lets a `</script>` in graph data close the inline script tag.** Node paths and descriptions are hostile input (scanned files / LLM text). They are now JSON-embedded with `<`/`>`/`&` and U+2028/U+2029 escaped so the D3 payload cannot break out of `<script>`.
|
|
126
|
+
|
|
127
|
+
- **Cycle risk scores no longer collapse to 0 on `./`-prefixed edge paths.** `--no-ast` runs Tarjan on the LLM's `import_edges`, which often carry a `./` prefix; SLOC lookup is keyed by scanner paths without it, so every `sloc_map.get` missed and `log10(total_lines) * length` became 0. Paths are now normalised the same way as faithfulness before scoring (#84).
|
|
128
|
+
|
|
129
|
+
- **Pass-1 token estimate is now of the prompt actually sent.** `pass1_tokens()` used to score a two-sentence stub plus the raw tree, so `--dry-run`'s `Pass 1 context` line and `meta.usage.pass1.estimated_prompt_tokens` under-counted by ~7x and could not audit the `estimate_tokens` heuristic. It now uses `assemble_pass1_prompt` plus the same message-overhead reserve as pass 2 (#86).
|
|
130
|
+
|
|
131
|
+
- **Pass-2 file selection no longer substring-matches the wrong files.** A pass-1 request for `a.py` could pack `data.py` into the prompt (`"a.py" in "data.py"`), and two requests could duplicate the same fragment. Matching is now exact path, then `/`-suffix (so `cli.py` finds `app/cli.py` and not `tests/test_cli.py`), then a repo-prefixed request — unique by canonical path (#85).
|
|
132
|
+
|
|
133
|
+
- **C# namespace `using MyApp.Models;` no longer resolves onto a parent `MyApp.cs`.** The nested-type parent-file probe (`Ns.Type` → `Ns.cs`) ran for every using, so a namespace import preferred `src/MyApp.cs` over the unique-dir `src/MyApp/Models/User.cs`. That probe now runs only for `using static` and `using Alias = …` (ADR-007) (#126).
|
|
134
|
+
|
|
135
|
+
- **C# `using System;` no longer resolves onto a unique scanned file in `System/`.** The unique-namespace-directory fallback treated a lone `System/Console.cs` as the BCL. `System` / `Microsoft` / `Windows` roots are now dropped as third-party, matching the pack docstring (#100).
|
|
136
|
+
|
|
137
|
+
### Infrastructure
|
|
138
|
+
|
|
139
|
+
- **CI and release workflows now use current Node.js 24-based actions.** GitHub was forcibly running the older checkout, artifact, uv setup, coverage, and release-publishing actions under a compatibility runtime and warning that their Node.js 20 runtime was deprecated (#80).
|
|
140
|
+
- **Parallel CI jobs now use distinct, reusable uv cache keys.** Matrix and specialist jobs previously raced to reserve the same cold-cache entry, producing failed-save annotations and duplicate upload work (#82).
|
|
141
|
+
|
|
10
142
|
## [0.4.2] - 2026-09-05
|
|
11
143
|
|
|
12
144
|
### Fixed
|
|
@@ -229,7 +361,9 @@ First public release. graphlm is installable from PyPI (`uv tool install graphlm
|
|
|
229
361
|
- mypy type checking in CI
|
|
230
362
|
- Removed stale generated artifacts (`graphs.md`, `graphs.json`, `graph.html`) left over from before the `GRAPH.*` output rename, and the committed `.coverage` database; the repo no longer ships tool output. Added `.coverage`, `coverage.xml`, and the `GRAPH.*` output files to `.gitignore` so generated artifacts stay out of version control
|
|
231
363
|
|
|
232
|
-
[Unreleased]: https://github.com/ggrace519/graphLM/compare/v0.
|
|
364
|
+
[Unreleased]: https://github.com/ggrace519/graphLM/compare/v0.6.0...HEAD
|
|
365
|
+
[0.6.0]: https://github.com/ggrace519/graphLM/compare/v0.5.0...v0.6.0
|
|
366
|
+
[0.5.0]: https://github.com/ggrace519/graphLM/compare/v0.4.2...v0.5.0
|
|
233
367
|
[0.4.2]: https://github.com/ggrace519/graphLM/compare/v0.4.1...v0.4.2
|
|
234
368
|
[0.4.1]: https://github.com/ggrace519/graphLM/compare/v0.4.0...v0.4.1
|
|
235
369
|
[0.4.0]: https://github.com/ggrace519/graphLM/compare/v0.3.1...v0.4.0
|
graphlm-0.6.0/CLAUDE.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
## What this is
|
|
6
|
+
|
|
7
|
+
`graphlm` is a CLI + library that generates a codebase graph (Markdown + JSON + interactive HTML) from any project directory, using an OpenAI-compatible LLM plus deterministic Tree-sitter AST parsing. Python 3.11+, `uv`-managed, Pydantic v2, Typer CLI, `httpx` for the LLM call. No async — the LLM client is synchronous.
|
|
8
|
+
|
|
9
|
+
## Commands
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv sync --group dev # install (incl. pytest, pytest-cov, pytest-httpx, mypy)
|
|
13
|
+
uv sync --group dev --extra mcp # + the optional MCP extra (needed for tests/test_mcp_server.py; skipped otherwise)
|
|
14
|
+
uv sync --group dev --extra js # + JS/TS grammars (needed for tests/test_parser_javascript.py enabled-path tests; skipped otherwise)
|
|
15
|
+
uv sync --group dev --extra java # + Java grammar (needed for tests/test_parser_java.py enabled-path tests; skipped otherwise)
|
|
16
|
+
uv sync --group dev --extra rust # + Rust grammar (needed for tests/test_parser_rust.py enabled-path tests; skipped otherwise)
|
|
17
|
+
uv sync --group dev --extra csharp # + C# grammar (needed for tests/test_parser_csharp.py enabled-path tests; skipped otherwise)
|
|
18
|
+
uv sync --group dev --extra cpp # + C/C++ grammars (needed for tests/test_parser_cpp.py enabled-path tests; skipped otherwise)
|
|
19
|
+
uv sync --group dev --extra go # + Go grammar (needed for tests/test_parser_go.py enabled-path tests; skipped otherwise)
|
|
20
|
+
uv sync --group dev --extra php # + PHP grammar (needed for tests/test_parser_php.py enabled-path tests; skipped otherwise)
|
|
21
|
+
uv sync --group dev --extra typesafe # + TypeSafe/Jev SDK (needed for tests/test_evidence.py — real Noul types; skipped otherwise)
|
|
22
|
+
uv sync --group dev --extra all # every language pack (does NOT include mcp or typesafe)
|
|
23
|
+
uv run pytest -q # full suite (~1030 tests, ~6s, no network — LLM is mocked via pytest-httpx; language-pack + typesafe enabled-path tests skip without their extra)
|
|
24
|
+
uv run pytest tests/test_parser.py -q # one file
|
|
25
|
+
uv run pytest tests/test_parser.py::test_name -q # one test
|
|
26
|
+
uv run pytest --cov=graphlm --cov-report=term-missing # coverage (CI reports it; ~90%, but NOT gated — no --cov-fail-under)
|
|
27
|
+
uv run mypy graphlm --ignore-missing-imports # type check (separate CI job; keep it clean)
|
|
28
|
+
graphlm /path/to/project --dry-run # exercise scan + AST + context packing without any LLM call
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
CI (`.github/workflows/ci.yml`) runs pytest+coverage on Python 3.11/3.12/3.13 (base + `mcp` extra — language-pack enabled-path tests skip), a separate `test-packs` job with `graphlm[all]` on 3.12 (the enabled path), and mypy on 3.12. There is no linter/formatter configured — match surrounding style.
|
|
32
|
+
|
|
33
|
+
## Architecture — the big picture
|
|
34
|
+
|
|
35
|
+
The *analysis* pipeline lives in `graphlm/__init__.py::generate_graph()` — read that function first; it orchestrates everything below in order. (Output is separate: the library only writes when `output_dir` is set; the CLI leaves it `None` and writes itself — see below.)
|
|
36
|
+
|
|
37
|
+
**Two-pass LLM strategy** (the core design, to stay inside context windows):
|
|
38
|
+
1. **Pass 1** — `context.assemble_pass1_prompt(tree)` sends *only* the directory tree. The LLM returns `{"requested_files": [...]}` — the files it wants to read. The tree is size-bounded by **two** caps in `scan_project` so this prompt stays within context on a huge repo: (a) a *per-directory* cap of `max_tree_entries_per_dir` listed children (default 200 via `_MAX_TREE_ENTRIES_PER_DIR`), emitting a "… N more entries not shown" marker past that — per-directory rather than global so deeply nested source stays visible instead of being crowded out by an early cache dir; and (b) an absolute *total-lines* ceiling of `200 × _TREE_TOTAL_LINE_MULTIPLIER` (= 5000 lines) that stops the whole walk (the per-dir cap alone is only `per_dir × num_dirs`, so a repo with thousands of dirs still needs the total backstop). Each tree line is `indent + basename` (directories end with `/`); restating the full relative path on every line made the 5000-line cap still overflow `max_context` on deep monorepos (n8n's tree was ~151k tokens and zeroed the pass-2 edge budget, #69). Pass 1 is told to reconstruct full relative paths from the indent when requesting files. Both caps bound tree text only, not which files are read (`max_files`). Unlike pass 2, pass 1 has **no token-budget enforcement** — these caps plus `_ALWAYS_EXCLUDE` are what keep it in bounds. `_ALWAYS_EXCLUDE` also blocks graphlm's *own* output so a re-run over an already-mapped project never ingests its own map/diff as source: the CLI default output dir **`.graphlm/`** is excluded as a whole directory (`_should_exclude` matches any path component), and — for the case where output is redirected into the scanned tree with `-o` — the artifact *filenames* (`GRAPH.md`/`.json`/`.html`, `GRAPH_DIFF.md`/`.json`) are also excluded by exact name, not a `GRAPH*` glob, so a user's `GRAPHICS.md` survives (#28).
|
|
39
|
+
2. **Pass 2** — `context.filter_requested_files()` maps those back to scanned fragments (exact path after `./` normalisation, then `/`-suffix so `cli.py` finds `app/cli.py` and not `tests/test_cli.py`, then a repo-prefixed request — never substring containment, so `a.py` cannot select `data.py`, #85; `max_files` keeps pass-1 request order then sorts the kept set, #98), then `assemble_pass2_prompt()` assembles tree + file contents + the AST-edge table + the instruction block, and asks for the full `CodebaseGraph` JSON. The *input* token budget is enforced: the tree, edge table, instruction block, and a small message-overhead reserve (`MESSAGE_OVERHEAD_TOKENS`, for the system prompt + framing) are counted up front, and files are admitted only until the running total would exceed `max_context` (over-budget files land in `truncated_paths`). So the assembled prompt stays within `max_context`. If the tree already fills that budget, the edge table is omitted from the prompt and the warning names the tree overflow (parser edges still reach the graph and cycle detection — never "header does not fit the 0-token edge budget", #69). The **output** budget (`max_tokens`) is *not* reserved out of `max_context` — input and output ceilings are independent on the target endpoint (#25). **The model is told to return an empty `directory_tree`** — `generate_graph` fills `graph.directory_tree = scan.tree` locally afterward (alongside the `deterministic_edges` fill), because echoing a large tree back as output alone can blow the output-token ceiling and truncate the graph (#18). So don't reintroduce a "include the tree" instruction.
|
|
40
|
+
|
|
41
|
+
`--dry-run` skips both LLM calls. It does *not* model "all scanned files" — it selects `scan.file_fragments[:max_pass2_files]` (default cap 80), builds a `CodebaseGraph` carrying the AST edges + cycles + a dry-run note, and the CLI prints token estimates (`pass1_tokens` is `estimate_tokens(assemble_pass1_prompt(tree)) + MESSAGE_OVERHEAD_TOKENS`, the same accounting as pass 2 — not a stub of the instructions plus the raw tree, #86), the **AST import-edge count** (`AST import edges: N`, or `AST off` — read from `deterministic_edges`, *not* the LLM's `import_edges`, which a dry run never fills and so always read `0`), and graph-section counts. Tokens are estimated by a crude heuristic — `estimate_tokens` = `UTF-8 bytes * 2 // 5` (≈2.5 bytes/token). It is defined once in `scanner.py` and re-exported by `context.py`. The ratio is calibrated to over-estimate: real content measured ~2.83 bytes/token against the served model, so the old `// 4` (4 bytes/token) *under*-counted by ~28% and let graphlm pack prompts the model then rejected or timed out on — the `* 2 // 5` divisor sits safely above the real count (#17).
|
|
42
|
+
|
|
43
|
+
**AST parser is ground truth, not a replacement for the LLM** (the `graphlm/parsers/` package — `base.py` is the registry-driven Tree-sitter backend + language-agnostic dispatch, `python.py` is the Python resolver; `graphlm/parser.py` is a thin backwards-compat shim re-exporting the public contract, incl. `_source_roots`; on by default, `--no-ast` disables). `build_dependency_graph()` extracts Python import edges with Tree-sitter and resolves them *only against files that exist in the scan* (stdlib/third-party/missing modules are dropped — resolution is against the `known_files` set, independent of `project_dir`). Because edges resolve only between *scanned* files, the scanner's `_rank_file` ranks source code (`_SOURCE_EXTS`) above non-source text so a doc-heavy repo can't crowd source out of the `max_files` cap and starve the graph (#19). Resolution handles **src-layout** projects: `_source_roots()` accepts a source-root prefix only when its final segment is a conventional root name (`_SOURCE_ROOT_NAMES` = `src`/`lib`/`python`) that directly contains a package, and each import candidate is tried under every accepted root (root `""` first, so root-layout projects are unchanged) — without this, a `from mypkg.x import Y` in a `src/mypkg/` project resolved to nothing and the whole AST graph came back empty (#19). The allowlist is deliberate: deriving a root from *any* directory containing an `__init__.py` let a `tests/stub/requests/__init__.py` shadow make third-party `import requests` resolve to a project-internal file — a false edge in the "do-not-contradict" ground-truth table, worse than a missing one. A conventional `src`/`lib`/`python` nested under `tests/`/`vendor`/`stubs` is also rejected (#161). `project_dir` is *optional*: given, `_source_bytes` reads the untruncated/unredacted file off disk; omitted, it falls back to the (truncated) `frag.content`. Those `deterministic_edges` are (a) injected into the pass-2 prompt as a "do not contradict" table, and (b) used for cycle detection instead of the LLM's edges. The two uses diverge under a tight `max_context`: the **prompt** copy of the table is capped at a share of the budget (`EDGE_SHARE`, `context.py`) and, when capped, its framing flips to "not exhaustive — infer the rest" so a partial list isn't presented as complete; the **full** list always reaches `graph.deterministic_edges` and cycle detection. So the LLM's `import_edges` and the AST's `deterministic_edges` are separate fields on `CodebaseGraph` and can differ. **Python is the only core language** (the sole grammar in the base install). JS/TS import edges are extracted by `parsers/javascript.py` when the optional `graphlm[js]` extra is installed (`tree-sitter-javascript` + `tree-sitter-typescript`); without it, JS/TS files contribute zero edges and one log line per language, never a crash, and Python edges stay intact (`deterministic_edges` stays a list — a missing pack must never look like `ast=False`). Resolution is relative specifiers only (`./foo`, `../bar`) with extension-probe `<spec>`, `<spec>.{ext}`, `<spec>/index.{ext}` — `.js` importers prefer `.js/.jsx/.mjs/.cjs` then `.ts/.tsx`, `.ts` importers the reverse; bare specifiers (`react`) are dropped like Python stdlib. A dropped bare specifier marks the language known-partial so the pass-2 edge table flips to the non-exhaustive framing even when it was not size-capped. `kind` is `import` for import/export-from/dynamic `import()`, `require` for `require()` and TS `import x = require(…)` — `(from,to,kind)` is the diff identity contract (ADR-004). `.tsx` uses `language_tsx()` (grammar selection is by file suffix, because `detect_language` maps both `.ts` and `.tsx` to `"typescript"`). JS/TS `source_roots()` is grammar-free and returns `("",)` — relative paths resolve from the importing file, not a source-root prefix. The JS/TS resolver must let `_GrammarUnavailable` propagate (re-raise before a generic `except Exception`) so the once-per-language warning fires; python.py does the same. Java (`parsers/java.py`, extra `graphlm[java]`) is FQN→file: `import com.acme.User` → `<root>/com/acme/User.java` under Maven roots `src/main/java` / `src/test/java` (and a bare `src/`), with the file's `package` declaration as a disambiguator. `kind` is `import` for a type import and `static` for `import static` (ADR-005). Package wildcards (`import pkg.*;`) are dropped — they would fan out to every `.java` in the package and churn GRAPH_DIFF when a file is added — and mark the language known-partial; `import static Type.*;` still resolves to `Type.java`. Nested types try `Foo/Bar.java` then `Foo.java`. `source_roots()` is grammar-free. Same re-raise / once-per-language degradation as JS/TS. Rust (`parsers/rust.py`, extra `graphlm[rust]`) is two-step: `mod foo;` is kind `include` to `foo.rs`/`foo/mod.rs`; `use crate::`/`super::`/`self::` resolve against a filesystem module tree from the scan (`lib.rs`/`main.rs` crate roots). External crates are dropped. Inline `mod { … }` and `#[path = "..."]` modules are skipped and mark the language known-partial (ADR-006); `#[cfg(feature = "path")]` is not a path attribute (#153). C# (`parsers/csharp.py`, extra `graphlm[csharp]`) maps `using static Ns.Type` / `using Alias = Ns.Type` to `Ns/Type.cs` (then `Ns.cs` for a nested type); a namespace `using Ns;` resolves only when exactly one scanned `.cs` lives in that namespace directory — two or more files are a policy drop (GRAPH_DIFF fan-out, ADR-007) and mark known-partial; the nested-type parent-file probe is not applied to namespace usings, so `using MyApp.Models` does not resolve onto `MyApp.cs` (#126); a `using Alias = MyApp.Models` namespace alias unique-dirs first and only parent-probes on a miss (#134); `using System;` / Microsoft / Windows BCL roots never unique-dir-resolve, even if a lone `System/Console.cs` is scanned (#100); other misses are third-party, not partial. C/C++ (`parsers/cpp.py`, extra `graphlm[cpp]`) maps quoted `#include "foo.h"` relative to the importer as that exact name (kind `include`), including includes nested under `#ifdef` (#99); an extension probe (`.h`/`.c`/`.hpp`/…) runs only for extensionless `#include "foo"`, so `"foo.h"` does not hit a sibling `foo.c` (#128); angle-bracket system headers are dropped; macro includes mark known-partial (ADR-008). `.c`/`.h` use the C grammar, `.cpp`/`.hpp`/`.cc`/… the C++ grammar. Go (`parsers/go.py`, extra `graphlm[go]`) maps `import "mod/pkg"` to a unique non-test `.go` in that package directory (suffix-stripped so a module prefix is optional); multi-file packages are a policy drop (ADR-010); `import "./rel"` is path-relative; specifiers with no `.` (`fmt`, `encoding/json`) are stdlib and never resolve, even onto a unique local `fmt/` directory (#95). PHP (`parsers/php.py`, extra `graphlm[php]`) maps `use App\Models\User` to `App/Models/User.php` and quoted `require`/`include` relative to the importer (kind `include`), including `require 'x.php' or die()` (#135); interpolated `"config.php$id"` is a policy drop (#147); the parent-file probe is only for `use function` / `use const`, so a class `use` does not resolve onto `Models.php` (#129); concatenated `__DIR__` paths mark known-partial (ADR-011). Grammar accessor is `language_php`.
|
|
44
|
+
|
|
45
|
+
**Oversized files are skeletonised, not head-truncated.** In `scan_project`'s read loop a file longer than `max_file_chars` (default 4000) is handed to `parsers.base.skeleton_for(path, bytes)`; for Python that returns `parsers.python.skeleton()` — the module docstring head, imports verbatim (incl. under a top-level `try:`/`if TYPE_CHECKING:`), every class/def header with decorators and multi-line signatures intact, each docstring's first line, class attributes and constants that fit in two lines (`NAME = {…} # N lines elided` otherwise), and `if __name__ == "__main__":` reduced to its header; bodies become `...` and the first line is `# [graphlm skeleton: bodies elided; N source lines]`, which `context._build_instruction_block` explains to the model ("signatures exact, don't invent behaviour for elided bodies"). Only if the skeleton is *still* over the cap, or `skeleton_for` returns `None` (no language / no resolver / `_Resolver.skeleton is None` / grammar pack missing / renderer exception — it never raises), does the old head slice apply. Order in the loop is load-bearing: read → `line_count` capture → skeleton-or-truncate → `_redact_secrets` — redaction must run on the *final* text because docstring first lines and short constants survive into the skeleton. `skeleton_for` is imported *inside* `scan_project` (function-local) because `parsers/base.py` imports `FileFragment` from `scanner.py` at module scope — a top-level import would be a cycle. `--no-skeleton` / `scan_project(skeleton=False)` / `generate_graph(skeleton=False)` restores head-truncation. Python only; other languages still head-truncate. **The renderer derives columns and row spans from byte offsets (`_col`/`_rows`), never from `Node.start_point`/`end_point`** — with py-tree-sitter 0.26.0 those corrupted the heap on a full-tree walk (ASLR-dependent segfault in `_PyObject_Malloc`, reproduced 12/12 by a deep `.children` walk that read points and 0/12 by the same walk on byte offsets); `tests/test_skeleton.py` guards the skeleton section against reintroducing them and skeletonises every module in the repo in-process.
|
|
46
|
+
|
|
47
|
+
**Cycle detection** (`cycles.py`) runs Tarjan SCC over the AST edges (falling back to LLM edges if AST is off), scoring each cycle `log10(total_lines) * cycle_length`. Edge paths and sloc-map keys are normalised (leading `./` stripped, backslashes folded) before lookup so an LLM `./a.py` still hits the scanned `a.py` — without that, `--no-ast` risk scores collapsed to 0 (#84). The SLOC term is `FileFragment.line_count` — the *on-disk* physical line count (newlines + 1, including blanks/comments), captured in `scan_project` **before** any truncation/skeletonisation, so a large file in a cycle is weighed by its real size, not by the `max_file_chars` slice (it previously counted the truncated content and under-weighted exactly the files that matter most). It is still not true source-lines-of-code. `FileFragment(..., line_count=None)` falls back to counting `content` for hand-built fragments. Also: `graphlm/parsers/base.py` *also* has its own `detect_import_cycles()` (returns bare node lists, no scores; re-exported via the `graphlm/parser.py` shim) — the live path uses `cycles.detect_cycles()`; don't confuse the two.
|
|
48
|
+
|
|
49
|
+
**Data models** (`models.py`) — `CodebaseGraph` is the Pydantic schema the LLM must emit and the single source of truth for output shape. `Cycle` is a frozen dataclass (not Pydantic). The pass-2 prompt in `context.py` hand-writes the JSON schema description for the LLM; **if you add/rename a field on `CodebaseGraph`, update that prompt text and `render.py` in the same change** — they are not auto-derived from the model. **Exception — `meta` (`GraphMeta`):** the provenance stamp is *not* LLM-emitted (like `directory_tree`/`deterministic_edges`, it's filled locally in `generate_graph`), so it is deliberately **not** in the pass-2 instruction block — don't add it. Its `schema_version` (`GRAPH_META_SCHEMA_VERSION`) is a versioned *input* contract: graphlm reads its own prior `GRAPH.json` for the fast-follow diff, so bump it if the meta shape changes (see the self-refreshing-graph ADR in `DECISIONS.md`).
|
|
50
|
+
|
|
51
|
+
**Output** (`render.py`) — writes `GRAPH.md` and (by default) `GRAPH.html` + `GRAPH_DIFF.md`, plus an always-written internal JSON working copy `.graph-state.json` (`freshness.STATE_FILENAME`, the diff baseline + `--serve` map). The user-facing `GRAPH.json` and `GRAPH_DIFF.json` are **opt-in** — `write_outputs(json=...)` / `GraphResult.write(include_json=...)`, default `True` for library callers, but the **CLI defaults it off** (`--json` to enable) since the `.md` is the agent-facing map. `render_markdown` opens with a `## Orientation` block (`orientation.py`, between the header and `## Directory Tree`) and groups test-only import cycles under `## Import Cycles` (`cycles_render.py`). **Fresh-run cleanup** (`freshness.py`): a re-run removes graphlm's *own* stale artifacts (exact names only, symlinks skipped, gated on `owns_dir` so a fresh user dir is never touched); a prior map from a different graphlm version yields a `VERSION_CHANGED` diff. The `*_suffix` params default to `"GRAPH"`. **`GRAPH.md` carries a Mermaid `## Module Graph`** (`mermaid.py::render_mermaid`, called from `render_markdown` right after the directory tree) — GitHub renders Mermaid natively, so the Markdown map has a picture with no CDN. It is a **directory-level** `flowchart LR` (files collapse to their parent dir via `_collapse_dir`; a root-level file stays its own node), deduped, self-edges dropped, capped at `max_nodes=40` by (in+out) degree with a "… N more directories not shown" note past the cap. Edge source is `deterministic_edges` when non-empty (note says "ground truth"), else the LLM `import_edges` ("inferred"); `[]` when neither. Cycle styling: paths are `./`-stripped before collapse/membership so LLM `./a.py` does not become a `.` node or miss the red ring (#96); a collapsed edge is a cycle edge when its *file-level* endpoints share an `import_cycles[].nodes` set — those are emitted **last** so their `linkStyle` indices are the tail of the link list (Mermaid styles links by emission index, nothing else) — and any directory containing a cycle member gets a `style … stroke` outline (red `#e11` for a production cycle, muted amber `#b8860b` `TEST_CYCLE_COLOR` when the dir's only cycle is test-only — production wins when a dir has both), because an intra-package cycle (the common case) collapses to a dropped self-edge and would otherwise leave no trace. A directory whose edges are *all* self-edges is still a node (single-package projects — the `cyclic_project` fixture — otherwise rendered an empty block). Ids are `n_` + `[^A-Za-z0-9_]→_` with a numeric suffix on collision; labels are quoted with `"`→`#quot;`. Everything is sorted for stable diffs. HTML (`html_render.py` + `_html_template.html`) is a single self-contained *file* (string-substituted, no build step) — but it loads D3 from a CDN (`_html_template.html` → `https://d3js.org/d3.v7.min.js`), so the graph won't render offline. HTML is on by default; `--no-html` / `include_html=False` skips it. **The HTML draws ground truth as layers:** `_build_links` emits `deterministic_edges` as `type: "ast"` links (solid `#7aa2f7`, one per `(from, to)` pair even if the parser produced several), drops any LLM `import_edges` entry with the same `(from, to)` and marks the AST link `corroborated: true` (one pair, one line), and keeps LLM-only imports as grey `type: "import"`; `_build_nodes` upserts AST endpoints too (D3 forceLink throws on a missing id) and sets `in_cycle` on every node from `import_cycles`. The embedded JSON is `{nodes, links, cycles, provenance}` (`cycles` = SCC count for the stats line; `provenance` = version/commit/date, machine-readable, not shown in the UI; each node also carries `is_test` and `in_cycle`), spliced via `_json_for_script` so a `</script>` in a path cannot close the inline `<script>` tag. The template rings `in_cycle` nodes red (`#e11`, 2.5px — via `nodeStroke*` helpers so the hover restore keeps the ring), has a Layers control (checkboxes `data-layer="ast|import|data_flow"`) that toggles links with CSS `display` only (never touches the simulation), and legend/stats entries for the new layer. `write_outputs` computes every path it will write and refuses a symlink at **all** of them (output dir, `GRAPH.md`, working copy, and whichever of `GRAPH.json`/`.html`/`GRAPH_DIFF.*` this run produces) **up front — before any cleanup deletes or any file is written** (same contract as skill install, #33), so a symlinked HTML can't let cleanup remove a stale JSON and leave a half-written dir. `Path.write_*` would otherwise follow the link and clobber a file graphlm did not create. **`write_outputs` returns a `WriteResult`** — a `tuple` subclass that *is* the `(md, json, html)` 3-tuple existing callers unpack (so `md, json_, html = write_outputs(...)` still works), with `.diff_md` / `.diff_json` attributes carrying the diff paths (`None` when `diff=False`). ADR-002 requires the arity stay 3 for the ~10 positional-unpack sites; don't turn `WriteResult` into a 4-/5-field tuple. `WriteResult.__new__` accepts *either* three positional path args *or* a single 3-sequence, and it defines `__getnewargs_ex__`, so `copy`/`deepcopy`/`pickle` round-trip it with `.diff_md`/`.diff_json` intact (a bare tuple subclass loses them). Note `==` still ignores the diff attrs (inherent to the tuple-subclass choice) — that's accepted.
|
|
52
|
+
|
|
53
|
+
**Graph-vs-graph diff** (`diff.py` + the `GRAPH_DIFF.*` outputs; on by default, `--no-diff` / `include_diff=False` disables). The diff runs **in `write_outputs`, not `generate_graph`** (ADR-002 decision 1) — it's the only place holding both the graph and the output dir (the CLI passes `output_dir=None` into `generate_graph`, the #8 split). Ordering is load-bearing: `freshness.prepare_baseline()` reads the *prior* graph **before** the working copy is overwritten, in **source order** — the internal working copy `.graph-state.json`, else (first post-upgrade run, no working copy yet) the prior `{json_suffix}.json` — via `load_baseline()`, which **never raises** (it runs on the write path *after* the paid LLM call, so an escaping exception would abort the run and discard the new graph). It classifies **four states** that must never collapse (decision 4, amended by ADR-016): `FIRST_RUN` (file genuinely absent — a *broken symlink* is `UNCOMPARABLE`, not first-run), `UNCOMPARABLE` (anything that can't be safely interpreted: corrupt/truncated JSON, bad encoding — `render_json` writes `ensure_ascii=False`, so a killed/disk-full prior run can leave a mid-codepoint file, and `UnicodeDecodeError` is a `ValueError` not `OSError` — *or* an unrecognized `meta.schema_version`, checked against `_KNOWN_META_SCHEMA_VERSIONS` *before* model validation, with a `bool`-and-`int` type guard so `schema_version: true` doesn't sneak through as `1`), `VERSION_CHANGED` (a NORMAL baseline whose `meta.graphlm_version` differs from this run's — regenerated fresh, not compared; names both versions), and `NORMAL`. The read+parse and the validate are each wrapped in a broad `except Exception` → `UNCOMPARABLE` (deliberately broad: the contract is "cannot read → uncomparable", not "cannot read in one of a few specific ways"). An old, meta-*less* `GRAPH.json` parses fine (`meta=None`) and compares as `NORMAL` with an `unknown` old SHA — only corrupt/unknown-version files are uncomparable. `compute_diff` is **added/removed only, no "changed" bucket** (decision 2): identity keys are structural (`modules`→`path`; edges→`(from,to,kind)`; `import_cycles`→`frozenset(nodes)`; `data_flow`→`(source,destination)`; `entry_points`→`(path,name)`; `file_summaries`→`path`), so a pure prose rewrite is invisible by design. Those keys **are the diff's contract** (decision 3) — changing one changes what counts as "the same entity". Renames are remove+add (no rename heuristics — locked). **`deterministic_edges` None-vs-`[]` is honored** (decision 5): if either side is `None` (AST off on one run) the AST dimension is `compared=False` ("not compared"), never a mass deletion. The "no structural changes" banner in the `.md` is gated on `GraphDiff.all_compared` — if a dimension was skipped it flips to "no changes *in the compared dimensions*", so a not-compared dimension is never read as unchanged (the same non-collapse rule as decisions 4/5, at the render layer). The `GRAPH_DIFF.json` carries its own `DIFF_SCHEMA_VERSION` (**2** — bumped for the `VERSION_CHANGED` state + `old_graphlm_version`/`new_graphlm_version` fields; independent of the graph's `GRAPH_META_SCHEMA_VERSION`), the state label, the old→new SHA range (a `null` side reads `unknown`), the two graphlm versions, and per-dimension added/removed lists. The diff *Markdown* rides `--no-diff`; the diff *JSON* also rides `--json` (it's a machine-readable deliverable). Output filenames follow the `*_suffix` convention: **`diff_suffix` defaults to `None` and resolves to `json_suffix`** (decision 6 — the diff tracks the graph's suffix, so `json_suffix="map"` → `map_DIFF.*`, read from and written beside `map.json`); pass `diff_suffix` to override. **`--dry-run` writes no diff** — the dry-run branch in `generate_graph` returns *before* any `write_outputs` call, and the CLI exits before `result.write` (both correct, intended; don't "fix"). No new network or LLM call — pure local computation. See ADR-002 in `DECISIONS.md`.
|
|
54
|
+
|
|
55
|
+
**Self-refreshing stamp** (`provenance.py` + the `meta` field). `provenance.py` is the *only* module that reads git / shells out — `git_commit_sha()` runs `git rev-parse HEAD` (argv list, no shell, `cwd=project`, failure-tolerant → `None`; a SHA is accepted only on exit 0 **and** a 40/64-hex match, which rejects the empty-repo literal `HEAD`). `generate_graph` fills `graph.meta = GraphMeta(...)` locally after pass 2 **and** in the `--dry-run` branch, overwriting any LLM-emitted `meta`. `render.py` then (a) renders a top-of-`GRAPH.md` **refresh directive** in two forms — *git form* (SHA present: "generated by graphlm `<version>` against commit `<sha8>`… compare `git rev-parse HEAD`… regenerate with `graphlm .`"; the "by graphlm X" prefix is dropped when `meta.graphlm_version` is `None`) and *non-git form* (SHA `None`: "regenerate when you believe the code changed") — and no directive at all when `meta is None` (old/library graphs); and (b) preserves `commit_sha: null` in `GRAPH.json` by re-splicing `meta` (the module-wide `exclude_none=True` would otherwise drop it, making non-git indistinguishable from old-format). Wording is "generated against", never "reflects" (dirty-tree honesty). See `docs/plans/self-refreshing-graph.md` and the ADR in `DECISIONS.md`. **`meta` also carries run telemetry** (innovation #6), filled locally in the same place after pass 2 and *not* on a dry run: `usage` (`RunUsage` → per-pass `PassUsage` with the endpoint's real `prompt_tokens`/`completion_tokens` — from the `on_usage` callback `call_llm` fires when the response carried a `usage` object — beside graphlm's own `estimated_prompt_tokens` for that prompt, so the `estimate_tokens` ratio is auditable from the stamp) and `faithfulness` (`faithfulness.py::score` — the LLM's `import_edges` vs the AST `deterministic_edges` on `(from,to)` pairs, kind ignored, LLM side restricted to kinds `import`/`from`/`require`/`static`/`include` and to extensions the AST actually emitted (`.py` always; `.js`/`.jsx`/`.ts`/`.tsx` when `[js]` produced those edges; `.java` when `[java]` did; `.rs` when `[rust]` did) — that's all the parser can confirm; `None` when AST is off — "not scored" must never read as "scored zero"). Both are **additive optional fields, so `GRAPH_META_SCHEMA_VERSION` stays 1** (ADR-001 bumps only on a meaning change; an old `GRAPH.json` without them loads as `NORMAL`). `telemetry_render.py` (`render_telemetry` + the per-metric `usage_summary`/`faithfulness_summary`/`evidence_summary`, split out of `render.py`) renders them as one `> **Run telemetry.**` line directly under the directive, called from `render_markdown`; the CLI reuses the same summaries for its `Usage:`/`Faithfulness:`/`Evidence:` lines so the wording is single-sourced; each part is omitted when unmeasured and the line is dropped when none is.
|
|
56
|
+
|
|
57
|
+
**`meta.evidence_support`** (`evidence.py` + the `typesafe` extra) is the third telemetry field, scoring the LLM's *prose* the way `faithfulness` scores its *edges* — and, like both above, it is additive-optional (schema stays 1), filled locally after pass 2, **never** on a dry run, and **never** in the pass-2 instruction block (it is not LLM-emitted). Each `file_summary` is scored by a TypeSafe/Jev **SOFT Noul** ("does the CLAIM correctly identify the file's role and the symbols it defines? minor unverifiable detail acceptable; a wrong role or invented symbol is not") against the **`pass2_files` `frag.content`** — the redacted/skeletonised/truncated text the model actually saw, **never** disk bytes or `parsers._source_bytes` (that would be an unredacted third-party leak, and would score the *file* rather than the *evidence the model had*). A summary is **skipped** (`EvidenceSupport.skipped`, not scored) when there is no evidence to compare against: its file was not in pass 2 (never scored against content the model never received), **or** its source is under `_MIN_EVIDENCE_CHARS` (64) stripped bytes — a near-empty `__init__.py` / thin entry point defines nothing, so the support Noul has no signal and returned a meaningless ~0.2 that falsely flagged correct minimal summaries as weak (#168; `tetris.py`'s 72-char import+guard still scores). Questions batch ~15/request (discriminator in the Noul `instructions` over a shared `state`). It is a **trust weight, not a hallucination accusation**: a skeletonised fragment legitimately lowers the score, and the field exposes per-file low outliers (`low: list[FileScore]`) plus `mean`/`scored`/`skipped`, mirroring how `Faithfulness` exposes `matched`/`llm_edges`/`ast_edges`. `evidence.score` **never raises** (best-effort, runs after the paid call), and `generate_graph` wraps the fill in a second `try/except` for defence in depth — a scorer failure leaves the field `None`, never discards the graph. It returns `None` (never scored) when **any** of: `--no-evidence`, `--no-redact` (redaction off → source must not reach a third party), no `TYPESAFE_API_KEY`, the `typesafe-sdk` extra absent (function-local import; nothing outside `evidence.py` imports it, the `mcp_server.py` rule), or a dry run. `telemetry_render.py::evidence_summary` renders it into the same `> **Run telemetry.**` line and the CLI's `Evidence:` line. See ADR-014.
|
|
58
|
+
|
|
59
|
+
**Module importance** (`evidence.score_importance` + `ModuleDescription.role`/`degree`, ADR-015) ranks modules by how load-bearing they are, and — unlike the telemetry fields above — enriches the **graph** itself, not `meta`. Each module carries **two raw components**, filled locally after pass 2 (never LLM-emitted, so NOT in the pass-2 instruction block): `role` (a TypeSafe/Jev **Score** over a leaf→orchestrator ladder, 0–3, the probability-weighted level — `criteria` is an ordered *list*, legend keys `[0,1,2,3]`) and `degree` (in+out import degree from `deterministic_edges` via `evidence.file_degree` — file-level, distinct from `mermaid`'s dir-collapsed degree). They are stored **separate, not pre-fused**: the blend (`_ROLE_WEIGHT 0.6` / `_DEGREE_WEIGHT 0.4` on normalised role + rank-normalised degree) lives in **`render.py::_fused_importance`** so the weighting can be retuned without rewriting `GRAPH.json`, and a reader can audit each signal (the `Faithfulness`/`EvidenceSupport` raw-components precedent). The `## Modules` table gains an **Importance** column and sorts load-bearing first *only* when some module scored; when none did (Jev off), it renders **byte-identical to before** (no column, path sort — pinned by a golden test). `render.py::importance_summary` reads the fused order off `graph.modules` (NOT `meta` — the plan said `meta`, but the data lives on the modules, so this is the better source) for the CLI `Importance:` line. **No `--no-redact` gate** (it sends descriptions + a degree count, never source — gating it would deny importance to `--no-redact` users for no security reason); gated on key + `typesafe` extra + `--no-importance`. `score_importance` **never raises** and `generate_graph` wraps the fill in a second guard — a Jev failure leaves `role`/`degree` `None` (never a fake zero), graph intact. The live divergence proves the fusion earns its place: on a real repo a constants module was import-degree #1 but Jev-role last (a leaf), and a low-degree entry point ranked high — degree alone would mis-rank both. **On a directory-granular graph** (the LLM described `modules` as packages on a large repo — `enrich.is_directory_granular`, most module paths extensionless), the module-level role/degree are too coarse, so importance is instead scored over the **file-level `file_summaries`** (`enrich.score_file_importance`) and stamped into **`meta.file_importance`** (a `list[FileImportance]`, additive-optional, schema stays 1) rather than onto `modules` — `modules` is a diff-compared field and at file granularity there is no graph object that carries importance without a new diff key, so `meta` (not diff-compared, the telemetry precedent) is the right home. `render.py` then emits a `## File Importance` section (absent, hence byte-identical, on file-granular repos), and `importance_summary` prefers `meta.file_importance` over the module fusion. A pre-registered eval measured the fused-vs-degree τ-b gap on argus jump +0.011→+0.105 at file granularity (INNOVATIONS #6, #173's importance counterpart). HTML node-sizing by importance is a deliberate follow-up, not yet built.
|
|
60
|
+
|
|
61
|
+
**Output destination is a `.graphlm/` subdir of the scanned project, not cwd.** The CLI passes `output_dir=None` into `generate_graph` (so the library doesn't write), then writes via `result.write(output_destination(...))`. `output_destination` (`cli.py`) defaults to `project_dir.resolve() / ".graphlm"` (constant `GRAPHLM_OUTPUT_DIRNAME`) unless `-o` is given — so a symlink checkout still writes after the paid calls (#154); `-o` is honored *literally* (no `.graphlm` appended). This CLI-only default keeps the map out of the project root and inside the scan-excluded `.graphlm/`; the **library** API (`generate_graph(output_dir=...)` / `result.write(dir)`) writes to the literal dir given and is unchanged. This split (fixed in #8) is deliberate — don't "simplify" it by having `generate_graph` write directly.
|
|
62
|
+
|
|
63
|
+
## Security invariants (don't weaken these)
|
|
64
|
+
|
|
65
|
+
The scanner treats scanned files as hostile input and has layered defenses — preserve them when editing `scanner.py`/`prompts.py`/`context.py` (and its split-out helpers: `exclusions.py` = `_ALWAYS_EXCLUDE` + `_should_exclude`; `scan_guards.py` = `_symlink_hides_sensitive`/`_is_nested_checkout`/`_path_is_inside`/`load_graphlmignore` — the symlink-escape and nested-checkout guards live there now, #184):
|
|
66
|
+
- **Sensitive files are never read** (`_is_sensitive_file`, defined in `redact.py` alongside the never-read extension/name lists and re-imported by `scanner.py`): TLS/key/cert extensions (`.pem/.key/.crt/…`); OpenSSH private-key filenames (`id_rsa`, `id_ed25519`, `id_ecdsa`, and the `_sk` variants — `id_rsa.pub` is not in that set) plus editor/backup names (`id_rsa.bak`, `id_rsa~`, `#id_rsa#`); credential files `.netrc` / `_netrc` / `.pgpass` / `.htpasswd` / `.npmrc` / `.yarnrc` / `.yarnrc.yml` / `.pypirc` and `.flaskenv`, plus their `.bak` / `~` / `#name#` backups; *any* dotenv file — `.env` or a name starting with `.env` (`.envrc`, `.env~`, `.env-local`), plus non-dot forms like `config.env` / `foo.env.local` — except the non-secret templates `.env.example/.sample/.template/.dist` (see `_ENV_SAFE_SUFFIXES`); and name globs (`_SECRET_NAME_PATTERNS`) like `*secret*`/`*secrets*`/`*credentials*`/`*private*`/`*password*`/`*token*`/`*api*key*`/`*auth*key*`. Source extensions (`.py`, `.ts`, …) are exempted from the name globs so `token.py` still gets analyzed.
|
|
67
|
+
- **Secret redaction** (`_redact_secrets`, defined in `redact.py` and re-imported by `scanner.py`) runs on every file's content by default (`--no-redact` disables) — regex passes for AWS keys, GitHub tokens, private-key headers, connection strings, JSON `"password"` / `"api_key"` assignments, etc. It runs on the *final* text of a fragment, i.e. **after** skeletonisation/truncation — keep that order (docstring first lines and short constants survive into a skeleton).
|
|
68
|
+
- **Nested checkouts are separate projects** (`scan_guards._is_nested_checkout`): any child directory holding a `.git` file (worktree/submodule pointer) or `.git` directory (vendored clone) is skipped in both the tree walk and `os.walk`, so a submodule or an agent worktree under `.claude/worktrees/` never duplicates the map under a second prefix. Only children are tested — the scan root may itself be a repo.
|
|
69
|
+
- **Symlink escape prevention** (`scan_guards._path_is_inside`): any symlink (file *or* directory) pointing outside the project is skipped — in the tree walk (so it never appears in the tree or consumes a `max_files` slot) and again before reading content in `os.walk`. In-project *directory* symlinks are also omitted from the tree (matching `os.walk(followlinks=False)`), so a `sub/loop → root` cycle cannot explode the listing and an `alias → pkg` link cannot advertise `alias/mod.py` (#97).
|
|
70
|
+
- **Prompt-injection guard**: `SYSTEM_PROMPT` (`prompts.py`) and the pass-2 prompt both instruct the model to treat all file content as data, never instructions. Keep that clause if you touch the prompts.
|
|
71
|
+
|
|
72
|
+
## Config
|
|
73
|
+
|
|
74
|
+
LLM settings come from `GRAPHLM_BASE_URL` / `GRAPHLM_API_KEY` / `GRAPHLM_MODEL`, loaded via `python-dotenv` in `config.py::_load_env_files()` (run once at import). **Resolution precedence, highest to lowest, first non-empty wins:** (1) the real shell environment (exported `GRAPHLM_*`); (2) the user-level `~/.config/graphlm/.env` (or `$XDG_CONFIG_HOME/graphlm/.env` when that var is set and non-empty); (3) the built-in defaults. A `.env` in the working directory, any ancestor, or the scanned project is **never** loaded (ADR-009) — those files belong to the target repo, not to graphlm. Precedence is enforced by loading the user file with `load_dotenv(override=False)` so it never clobbers a variable already in `os.environ`; the file is loaded only when it exists (`is_file()`), because `load_dotenv("")` would fall back to a frame-based search from `config.py`'s own directory. CLI flags `-b/-k/-m` override; if you pass any of the three to `generate_graph`, you must pass all three. The context budget resolves `--max-context` flag > `GRAPHLM_MAX_CONTEXT` env var > 120000, the request timeout resolves `--timeout` flag > `GRAPHLM_TIMEOUT` env var > 300s (independently of how the endpoint was configured — passing `-b/-k/-m` must not skip the env, #92), and the output-token budget resolves `--max-output-tokens` flag > `GRAPHLM_MAX_OUTPUT_TOKENS` env var > `LLM_MAX_OUTPUT_TOKENS` (128000, the model's practical max) (all flags and their `generate_graph(...)` params default to `None` so the env var can take effect). **`max_output_tokens` is the `max_tokens` sent in both pass-1 and pass-2 requests — a per-response ceiling, not a reservation.** It is *independent* of `max_context`: input and output ceilings do not share a window on the target endpoint (measured: 180k input + 200k `max_tokens` = 380k combined is accepted — #25), so it is NOT subtracted from the input budget. A high default is therefore free (the model stops when done) and prevents truncating either response; truncation past even it raises a clear `GraphLLErrorTruncated`. The default is sourced once from `llm.LLM_MAX_OUTPUT_TOKENS` (imported by `config.py`). NB: some other OpenAI-compatible servers (vLLM `max_model_len`, Anthropic) *do* bound prompt+generation together — lower the flag on such an endpoint. The 300s default is generous because **pass 2 is streamed** (`llm.py` sends `stream: true` plus `stream_options: {include_usage: true}` and reassembles SSE deltas; the usage option makes a compliant server append one final chunk with empty `choices` and the real token counts, which `_read_streamed_completion` reads *before* its empty-choices skip and returns in a `StreamResult` — an endpoint that ignores the option just yields `usage=None`) — a large project's full-graph generation can take minutes, and streaming keeps it alive past proxy read-timeouts (a non-streamed pass 2 hit a Cloudflare 524 at ~125s, #18). **Pass 2 also sends `response_format: {type: json_schema}`** (derived from `CodebaseGraph.model_json_schema()`, gated on `call_llm(response_format=...)` being set, so pass 1's free-form file-list request omits it) — prompt-only instruction was not enough for every served model, and `Qwen3.6-35B` returned a near-empty `{"database_schema": null}` and produced no graph without the constraint (#31). The endpoint treats the schema as a guided-JSON hint (not strict all-required enforcement), so the prompt's "return an empty `directory_tree`" and the locally-filled `meta`/`import_cycles`/`deterministic_edges` still come back empty — #18 is not reopened. An HTTP **400** (only) triggers a staged fallback: first `stream_options` is dropped (optional telemetry — a strict endpoint that rejects the newer parameter keeps the schema constraint), then, on a second 400, `response_format` is dropped and the request re-issued prompt-only; the two pops plus the final request fit the three attempts. A 401/403/404/429 is not a parameter rejection and still surfaces as an error. `.env.example` shows the shape (URL, key, and model are required placeholders — there are no built-in defaults for those three). `.env` is gitignored — never commit it.
|
|
75
|
+
|
|
76
|
+
## Tests
|
|
77
|
+
|
|
78
|
+
`tests/fixtures/{small,medium,large,cyclic,skeleton,ts,java,rust,csharp,ignore}_project/` are realistic sample trees the scanner/parser/cycle tests run against. `ts_project` is the JS/TS pack fixture (relative-import chain, `index.ts` barrel, `.tsx`, a bare `react` import that must be dropped, a 2-node cycle, and a `require()`/dynamic-`import()` file). `java_project` is the Java pack fixture (Maven layout, type import, static import, package wildcard that must be dropped, a 2-node cycle, and a `src/test/java` → `src/main/java` edge). `rust_project` is the Rust pack fixture (`mod` includes, `use crate`/`super`, an external crate that must be dropped, and a cycle). `csharp_project` is the C# pack fixture (unique-file namespace using, `using static`, a multi-file namespace that must be dropped, `using System;` dropped, and a 2-node cycle). `ignore_project` is the `.graphlmignore` fixture. `skeleton_project/big_module.py` is deliberately > 4000 chars with one of every construct the skeleton renderer handles; `tests/test_skeleton.py` pins its exact skeleton as an inline golden string — a renderer change must edit that string. `pyproject.toml` sets `norecursedirs = ["tests/fixtures"]` so pytest doesn't collect them as tests. `tests/test_integration.py` mocks the LLM HTTP call with `pytest-httpx` — no real network. When adding a scanner/parser feature, add or extend a fixture rather than mocking file I/O.
|
|
79
|
+
|
|
80
|
+
## CLI flags worth knowing
|
|
81
|
+
|
|
82
|
+
Beyond the config flags above: `--dry-run` (scan + AST, no LLM), `--json` (also write the machine-readable `GRAPH.json` / `GRAPH_DIFF.json`; **off by default** — the `.md` is the agent-facing map, and graphlm keeps an internal `.graph-state.json` working copy for diff/`--serve` either way), `--no-ast`, `--no-html`, `--no-diff` (skip the `GRAPH_DIFF.*` graph-vs-graph diff), `--no-tests` (real test conventions only — `test_*` / `*_test` / `tests/`; not `latest.py`, #94), `--no-redact`, `--no-skeleton` (send the head of an oversized file instead of its tree-sitter signature skeleton), `--exclude <pat>` (repeatable), `--no-graphlmignore` (skip the project-root `.graphlmignore`; the file is otherwise merged into the exclude set — gitignore-lite, union with `_ALWAYS_EXCLUDE` and `--exclude`; the file itself is always-excluded like `.gitignore`), and the cycle controls `--no-show-cycles` (skip the import-cycle section) / `--cycle-threshold <float>` (only report cycles with risk ≥ threshold). Sizing knobs: `--max-files` (scan cap, default 200), `--max-file-chars` (per-file, 4000 — a longer Python file is skeletonised, not cut), `--max-pass2-files` (files in pass-2 context, 80), `--max-context` (token budget), `--max-output-tokens` (per-pass output ceiling for both LLM calls, default 128000 — a request ceiling, NOT a reserve out of the input budget, see Config above), `--timeout` (LLM request seconds, default 300). Also `-V`/`--version` (eager) and `--upgrade` (short-circuits like `--install-skill`: detect uv-tool/pipx/pip, keep extras, refuse a source checkout; flag not a subcommand, ADR-012). See `graphlm --help` for the full list.
|
|
83
|
+
|
|
84
|
+
**`--serve`** (`query.py` + `mcp_server.py`) exposes an *existing* map to a coding agent over a stdio MCP server — eight zero-LLM tools (`overview`, `find`, `module`, `neighbors`, `dependents`, `cycles`, `entry_points`, `staleness`). **All logic lives in `query.py`** (pure functions over a `CodebaseGraph`; edges from `deterministic_edges` ∪ `import_edges` merged on `(from, to, kind)` and labelled `ast`/`llm`/`both`; neighbor lists sorted for determinism; `resolve_path` accepts an exact path, a unique `/`-suffix, or a unique extensionless substring (`core` → `app/core.py`) and otherwise returns candidates — a dotted query like `a.py` is not unanchored-substring-matched onto `data.py` (#140)) so it is tested without the SDK; `mcp_server.py` is a thin wrapper over the `mcp` package (**v2 API**: `mcp.server.MCPServer`, tools via `@server.tool()`, anticipated failures raised as `mcp.server.mcpserver.exceptions.ToolError` so the message reaches the model — any other exception is masked by the SDK as a bare "Error executing tool"). The `mcp` package is an **optional extra** (`graphlm[mcp]`, `pyproject.toml`); nothing outside `mcp_server.py` imports it, and CI installs the extra so `tests/test_mcp_server.py` (which drives the real server through the SDK's in-memory `mcp.client.Client`, no subprocess) runs — it `importorskip`s without it. `MapCache` re-reads `GRAPH.json` when its mtime changes, so a regen mid-session is picked up; a missing/corrupt map is a `MapUnavailable` → `ToolError`, never a server crash (`query.load_map` reuses `diff.load_baseline`, checking `UNCOMPARABLE` *before* `FIRST_RUN`). In the CLI, `--serve` short-circuits like `--install-skill` (single-command Typer app — no subcommands, ADR-003): `project_dir` defaults to `.`, the map path is `output_destination(project, -o) / STATE_FILENAME` (the internal working copy `.graph-state.json`, written on every run regardless of `--json`), and the map-exists check runs **before** the `mcp` import so a missing map reports "run `graphlm .`" rather than the install hint. **stdout is the protocol channel** — the server logs to stderr only.
|
|
85
|
+
|
|
86
|
+
**`--upgrade`** (`upgrade.py`) upgrades this graphlm install to the latest PyPI release and exits. **Same installer as install:** `uv-receipt.toml` → `uv tool upgrade graphlm`; dist-info `INSTALLER=uv` (no receipt) → `uv pip install --python <exe> --upgrade 'graphlm[…]'`; pipx metadata → `pipx upgrade graphlm`; else `python -m pip install --upgrade 'graphlm[…]'`. Extras from the uv receipt or pipx metadata (else probed). Argv list, no shell. A source checkout is refused (exit 2) with the pull/`uv sync` hint. **Do not `Path.resolve()` the interpreter** — uv-tool venvs symlink `bin/python` at a managed CPython *outside* the venv, so resolve walks out of `uv/tools/graphlm` and 0.4.0 then ran `-m pip` in a venv that has no pip (#71). Flag, not a subcommand (ADR-003/012); `project_dir` is unused. Tests inject the runner so CI never hits the network.
|
|
87
|
+
|
|
88
|
+
**`--setup`** (`setup.py`) is the first-run wizard: it lists the optional extras *not yet installed* (`available_extras` — the seven language packs, `mcp`, `typesafe`; `all` collapses a full language set), takes a numbers/names/`all`/blank selection, and installs the chosen packs with the **same installer** `upgrade.py` detected (`uv tool install --force 'graphlm[…]'` / `uv pip install --python <exe>` / `pipx install --force` / `python -m pip install`) — reusing `upgrade.detect_installer` / `installed_extras` / `_abs_no_follow` / `_spec` (**do not** reinvent them) and the don't-`resolve()`-the-interpreter rule (#71). The install spec is the **union** of already-installed + selected extras, so no existing pack is dropped by the forced reinstall; `_union_extras` collapses the language packs via `_collapse_extras` but **re-appends `typesafe`** because that helper only knows languages/`all`/`mcp` and would otherwise silently drop it. A `typesafe` selection prints the `TYPESAFE_API_KEY` → `~/.config/graphlm/.env` hint. A **source checkout is refused** (points at `uv sync --extra`). `run_setup` **never raises** past its boundary (installer failure → manual-command fallback; detection crash → falls back to `pip`) — a first-run helper must not block the tool. It **writes a completion marker** `~/.config/graphlm/.setup-done` (`marker_path`, XDG-aware like `config._user_config_path`, injectable `home` for tests, **refuses a symlinked marker** #33). The CLI short-circuits on `--setup` (flag, not subcommand, ADR-003) like `--serve`/`--upgrade`; and `_maybe_first_run_setup` auto-runs the wizard once before the first analysis **only when the marker is absent AND stdin is a TTY** — a non-TTY first run prints a one-line `--setup` hint and proceeds, never blocking piped/CI use. `runner`/`prompt`/`which`/`home` are all injectable, so `tests/test_setup.py` drives every installer branch with **no network** (this dev checkout detects as `source`, so a real install never runs in CI). ADR-013. The `typesafe` extra (`graphlm[typesafe]` → `typesafe-sdk`) is **opt-in, not in `[all]`** (commercial third-party API + key); nothing imports it yet — it lands ahead of the prose evidence-scoring feature, so the Commands block above has **no `--extra typesafe` dev-sync line** on purpose (there is no test that needs the SDK until that change adds one; `tests/test_setup.py` uses injected fakes). The auto-trigger writes the completion marker even on a non-TTY run, so a piped/CI first invocation consumes the one-shot hint (deliberate — ADR-013).
|
|
89
|
+
|
|
90
|
+
**`--install-skill <harness>`** (`skills.py`) installs an agent guide teaching a coding harness to read `.graphlm/GRAPH.md` when it opens a repo (and regenerate with `graphlm .` when missing/stale), then exits. It is **not** an eager callback — instead `project_dir` is an *optional* argument (default `None`) and the command body short-circuits to `_do_install_skill` when `--install-skill` is set, so `graphlm --install-skill claude` runs with no `project_dir`; the analyze path then guards `project_dir is None` with a clean exit-2 message. Harnesses: `claude` → `~/.claude/skills/graphlm/SKILL.md` (real skill frontmatter); `codex` → `~/.codex/graphlm.md` **plus a printed snippet** to paste into the user's own `AGENTS.md` (Codex has no arbitrary-file include — verified; and graphlm never edits a user-owned `AGENTS.md`/`CLAUDE.md`). User-global by default; `--skill-local` writes into the project, `--skill-force` overwrites. `install_skill(..., home=...)` takes an **injectable `home`** (defaults to `Path.home()`) so tests never touch the real `~`. Idempotent (skip-if-exists unless force). It **refuses to write through a symlink** at the target (`is_symlink()` check before write, catches broken links too) so a dotfiles-managed `~/.claude/skills/` isn't clobbered (#33) — the CLI turns that `ValueError` into a clean exit-2.
|