[codex] Merge development branch to main#2
Merged
Merged
Conversation
- Deleted `ladybug.py`, `markdown.py`, `ontology.py`, `production.py`, `production_queries.py`, `question_query_registry.py`, `verification.py`, and their corresponding test files. - Cleaned up unused imports and code related to the removed modules. - Ensured that the codebase is streamlined by eliminating obsolete functionalities.
- Added `GraphBuilder`, `CaptureRecord`, `GraphBuildResult`, and `ParseBundle` classes to facilitate the construction of an ontology graph from parsed code entities. - Implemented methods for building graphs from both AST-shaped trees and capture records. - Enhanced the ontology schema by including new relation types for imports and exports. - Created unit tests for `GraphBuilder` to ensure correct mapping of Python AST to ontology nodes and relationships. - Updated ontology tests to verify JSON serializability of the schema payload.
- Added LadybugCodeGraphStore for managing graph data with LadybugDB. - Implemented methods for schema management, partition replacement, and manifest handling. - Introduced MaterializationManifest and ManifestEntry for tracking materialization state. - Created GraphMaterializer for materializing code graphs from source files. - Developed TreeSitterPythonParser for parsing Python files into graph structures. - Added tests for materialization, schema validation, and graph parsing.
- Introduced tests for the MaterializationManifest and GraphMaterializer to validate file changes and materialization processes. - Implemented tests for ontology structure and relationships, ensuring all required node types and relation endpoints are declared. - Created tests for schema generation, verifying that all ontology nodes and edge nodes are correctly declared and that FTS indexes are created as expected. - Developed search functionality tests to ensure ranking and context retrieval work as intended, including handling of malicious queries. - Added setup workflow tests to validate CLI behavior, configuration creation, and error handling during setup.
- Added runtime configuration management in `runtime.py` to handle repository and database paths. - Implemented tool handling and execution logic in `tools.py`, supporting various graph-related operations. - Created transport mechanisms for HTTP and standard input/output in `transports/http.py` and `transports/stdio.py`. - Developed client adapters for different configurations in `clients` directory, including Codex, Hermes, and JSON-based clients. - Established a server descriptor to manage server configurations and command execution in `descriptor.py`. - Added comprehensive tests for MCP portability and functionality in `test_mcp_portability.py`.
- Implement atomic rebuild for materialization when changes are detected, preventing in-place deletions. - Update Hermes client configuration path to use a more standard location. - Modify setup instructions to reflect changes in MCP client usage. - Introduce a new installer module to manage MCP client installations, including native command generation and error handling. - Add tests for the new installer functionality and ensure compatibility with existing setup configurations. - Improve error handling and reporting for MCP installations, including partial failures.
The latest GitHub Actions CI run failed on Python 3.10 because materializer imported datetime.UTC, which is only available on Python 3.11+, while the package declares support for Python 3.10. Windows pytest jobs also failed because the Hermes default-path test patched HOME even though pathlib resolves the platform profile path on Windows. This keeps runtime behavior unchanged by using timezone.utc for aware timestamps and makes the test patch the home resolver directly instead of relying on platform-specific environment handling. Constraint: pyproject.toml advertises Python >=3.10 and the CI matrix runs Windows, macOS, and Ubuntu. Rejected: Drop Python 3.10 from the CI matrix | advertised package support still includes Python 3.10. Rejected: Change Hermes production path resolution to read HOME first | Path.home() is the production behavior; the test fixture was the portability problem. Confidence: high Scope-risk: narrow Reversibility: clean Directive: Do not reintroduce stdlib APIs newer than the declared minimum Python without raising requires-python and CI together. Tested: ./.venv/bin/python -m pytest -q; ./.venv/bin/ruff check .; git diff --check; ./.venv/bin/codebase-graph setup --repo-root . --mcp-client none Not-tested: Local Python 3.10 runtime unavailable; GitHub Actions rerun pending
Add shared detail and context fanout controls across CLI and MCP retrieval paths while switching CLI JSON output to compact defaults. The standard detail mode preserves existing payload shape, and slim mode is opt-in for lower-token agent workflows. Constraint: Existing standard retrieval payloads must remain backward compatible Constraint: CLI and MCP graph retrieval outputs must stay aligned Rejected: Make slim the default | too risky for existing consumers that inspect score diagnostics Confidence: high Scope-risk: moderate Directive: Do not remove standard detail fields without adding a compatibility path Tested: .venv/bin/ruff check . Tested: .venv/bin/pytest tests/test_search.py tests/test_mcp_portability.py tests/test_setup_workflow.py Tested: .venv/bin/pytest Not-tested: Downstream third-party MCP clients beyond local protocol tests
Bound graph_query responses at the cursor boundary, return JSON-RPC parse errors for malformed stdio frames, enforce local-only HTTP binding by default, and add a single-writer lock around on-disk graph materialization. Strengthen health checks and release gates so packaged artifacts exercise setup, graph search, and MCP handshake behavior before publishing. Constraint: MCP remains a local-first CLI/server surface, so remote HTTP binding is explicit and still unauthenticated Rejected: Keep graph_query get_all with response slicing | it still permits unbounded memory pressure Rejected: Treat malformed stdio frames as process-fatal | MCP clients need protocol errors instead of server exits Confidence: high Scope-risk: moderate Directive: Do not relax graph_query or HTTP bounds without replacing them with equivalent resource controls Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/smoke_built_wheel.py ./.venv/bin/codebase-graph Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-review-staged Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-review-staged/* Tested: runtime checks for graph-health, bounded graph-query, malformed stdio, YAML syntax, pip check, and graph refresh Not-tested: GitHub-hosted CI matrix and PyPI Trusted Publishing execution
The runtime now emits structured operational diagnostics for setup, MCP transport failures, and materialization lock conflicts. CI and release workflows also validate dependency integrity, build an SBOM, and attach that artifact to releases so package consumers have a clearer audit trail. Constraint: Real vulnerability advisory queries send dependency inventory externally, so local verification uses dry-run dependency collection and SBOM generation. Rejected: Run pip-audit advisory queries implicitly during local setup | external dependency inventory disclosure requires explicit authorization. Confidence: high Scope-risk: moderate Directive: Keep external advisory scans explicit; do not make local setup call advisory APIs silently. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-review-2 Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-review-2/* Tested: ./.venv/bin/python scripts/smoke_built_wheel.py ./.venv/bin/codebase-graph Tested: pip check, pip-audit dry-run, CycloneDX SBOM generation, workflow YAML parse, diagnostics smoke, graph refresh. Not-tested: Hosted GitHub CI execution and external vulnerability advisory scan.
Setup now has stricter repository-root invariants, honest dry-run behavior, and rollback for published control files when materialization fails. The graph query surface blocks procedure calls, HTTP no longer shares one mutable MCP session across handlers, materialization skips more generated directories and avoids hashing unsupported files, and release workflows now use immutable Action pins, real hosted advisory scans, and wheel plus sdist smoke coverage. Constraint: SPDX license selection and PyPI/GitHub environment setup are owner-controlled release decisions and cannot be invented in code. Constraint: Local advisory scans disclose dependency inventory externally, so local verification used pip-audit dry-run while hosted workflows run real scans. Rejected: Keep pip-audit dry-run in hosted CI | it cannot fail releases on known vulnerable dependencies. Rejected: Preserve setup --dry-run side effects | dry-run should not publish repository or client state. Rejected: Hash unsupported files before skipping them | large binary/vendor trees make that unsuitable for production repositories. Confidence: high Scope-risk: moderate Directive: Do not relax graph_query CALL blocking without a parser-level read-only proof or an explicit safe-procedure allowlist. Directive: Keep GitHub Actions pinned to immutable commits and let review policy decide update cadence. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ruby YAML parse for CI, release, and Dependabot workflows Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-prod-ready-4 Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-prod-ready-4/* Tested: wheel and source-distribution smoke tests using scripts/smoke_built_wheel.py against built artifacts Tested: ./.venv/bin/python -m pip check Tested: pip-audit dry-run, CycloneDX SBOM generation, codebase-graph setup refresh, graph-query count Not-tested: Hosted GitHub CI execution, real external vulnerability advisory query from local machine, PyPI Trusted Publisher setup, project license selection.
The repository now has a security reporting policy, release-gate documentation references it, CI and release jobs have explicit timeouts, and tests enforce workflow timeout, advisory-scan, action-pin, wheel/sdist smoke, and security-policy expectations. The sdist manifest explicitly includes SECURITY.md so published source artifacts carry the reporting policy. Constraint: SPDX license selection, PyPI Trusted Publisher settings, and conda-forge scope remain owner-controlled production gates. Rejected: Rely on setuptools-scm file discovery for the new security policy | the staged build omitted SECURITY.md from the source distribution until MANIFEST.in made it explicit. Rejected: Add PyYAML just to inspect workflow tests | a dependency-free text guard covers the workflow timeout invariant. Confidence: high Scope-risk: narrow Directive: Keep SECURITY.md in the source distribution whenever package artifact contents change. Directive: Do not remove workflow timeouts without replacing them with an equivalent CI hang guard. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ruby YAML parse for CI and release workflows Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-prod-ready-security-2 Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-prod-ready-security-2/* Tested: tar listing confirms SECURITY.md and MANIFEST.in are included in the sdist Tested: ./.venv/bin/python -m pip check Tested: codebase-graph setup refresh and graph-query count Not-tested: Hosted GitHub CI execution, GitHub private vulnerability reporting settings, SPDX license metadata, PyPI Trusted Publisher setup.
Adds a stdlib release gate checker that passes local repository gates and reports owner/external production blockers explicitly. Documentation now shows local and production modes, and MANIFEST.in packages the checker with SECURITY.md. Constraint: SPDX license selection, PyPI Trusted Publisher setup, hosted CI status, private vulnerability reporting settings, and conda release scope are owner/external production gates. Rejected: Treat documentation alone as the release gate | it cannot be executed or checked before publishing. Rejected: Add PyYAML for workflow inspection | the checker keeps release-gate validation stdlib-only. Confidence: high Scope-risk: narrow Directive: Keep local release-gate mode passing and production mode explicit about unresolved owner/external gates. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python scripts/check_release_gate.py --production --require-conda Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-release-gate Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-release-gate/* Tested: sdist tar listing confirms SECURITY.md, MANIFEST.in, and scripts/check_release_gate.py are packaged Tested: ./.venv/bin/python -m pip check Tested: codebase-graph setup refresh and graph-query count Not-tested: Hosted GitHub CI execution, PyPI Trusted Publisher settings, GitHub private vulnerability reporting settings, project license selection, conda-forge submission.
Blocks release distribution builds behind the repository production gate and makes remote MCP HTTP opt-in defensible by requiring a bearer token. The release gate now also catches bare external GitHub Action references instead of only mutable refs with an @ref. Constraint: License selection, PyPI Trusted Publisher setup, hosted CI status, private vulnerability reporting, and conda release scope remain owner/external production gates. Constraint: Local HTTP stays unauthenticated for local MCP clients; remote HTTP must not expose graph tools without an explicit bearer token. Rejected: Keep production release checks only in documentation | the workflow could still publish without running the executable gate. Rejected: Treat Origin checks as remote HTTP authentication | non-browser clients can omit Origin and still exfiltrate graph data. Rejected: Add a full auth framework | bearer-token enforcement closes the remote exposure without new dependencies or a wider protocol change. Confidence: high Scope-risk: moderate Directive: Do not re-enable --allow-remote without an auth boundary and do not let release builds bypass scripts/check_release_gate.py --production. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python scripts/check_release_gate.py --production --require-conda Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-release-http-gates Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-release-http-gates/* Tested: ./.venv/bin/python -m pip check Tested: sdist tar listing confirms release workflow, README, SECURITY.md, and scripts/check_release_gate.py are packaged Tested: codebase-graph setup refresh and graph-query count Not-tested: Hosted GitHub Actions execution, PyPI Trusted Publisher settings, GitHub private vulnerability reporting settings, project license selection, conda-forge submission, remote 0.0.0.0 socket acceptance in this sandbox.
Automatically removes materialization lock files only when they contain a valid dead writer PID. Active or malformed locks still fail closed, so concurrent writers remain protected while stale crash leftovers no longer require routine manual cleanup. Constraint: Lock files are the existing cross-process writer guard for on-disk materialization. Rejected: Always delete existing lock files | that would allow concurrent writers to corrupt or race graph rebuilds. Rejected: Keep manual stale-lock deletion as the primary recovery path | production setup should recover from dead writer PIDs automatically. Confidence: high Scope-risk: narrow Directive: Treat malformed or live-PID lock files as active until inspected; only auto-remove locks with a valid non-running PID. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-stale-lock Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-stale-lock/* Tested: ./.venv/bin/python -m pip check Tested: sdist tar listing confirms README, materializer, and materializer tests are packaged Tested: codebase-graph setup refresh and graph-query count Not-tested: Hosted CI execution, Windows-specific process liveness semantics beyond local unit coverage.
Rejects MCP tool listing and tool calls until the session has negotiated a protocol version through initialize. The HTTP transport now reuses one McpGraphServer per HTTP server so initialize state survives across requests instead of being discarded per POST. Constraint: Existing smoke clients initialize before tools but do not consistently send notifications/initialized. Rejected: Enforce notifications/initialized before every tool call | that would break current packaged smoke coverage and some clients while solving a narrower risk than pre-initialize tool access. Rejected: Keep a fresh MCP server per HTTP POST | it makes protocol session state impossible to honor over HTTP. Confidence: high Scope-risk: narrow Directive: If stricter MCP session semantics are added later, update packaged smoke clients and HTTP tests together. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-mcp-session Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-mcp-session/* Tested: ./.venv/bin/python -m pip check Tested: sdist tar listing confirms MCP protocol, HTTP transport, and MCP portability tests are packaged Tested: codebase-graph setup refresh and graph-query count Not-tested: Hosted CI execution; enforcement of notifications/initialized is intentionally deferred.
Pins runtime dependencies to the tested compatible release families so production installs do not silently float onto unverified LadyBugDB or tree-sitter APIs. Packaging tests now assert those bounds are present in project metadata. Constraint: Verification in this workspace used real_ladybug 0.15.3, tree-sitter 0.25.2, tree-sitter-python 0.25.0, and tomli 2.4.1. Rejected: Leave runtime dependencies unbounded | upstream API drift could break production installs despite local tests passing today. Rejected: Pin exact versions | that would unnecessarily block patch-level compatible fixes. Confidence: medium Scope-risk: moderate Directive: Revisit these compatible-series bounds when intentionally validating newer LadyBugDB or tree-sitter minor versions. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-dependency-bounds Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-dependency-bounds/* Tested: ./.venv/bin/python -m pip check Tested: built PKG-INFO includes bounded Requires-Dist entries Tested: codebase-graph setup refresh and graph-query count Not-tested: Fresh dependency resolution from PyPI in a networked clean environment.
Makes the conda-forge recipe version release-specific instead of leaving a stale fixed version, extends the production release gate to catch that placeholder, and aligns recipe runtime dependency bounds with the tested package metadata ranges. Constraint: Conda-forge submission remains a post-PyPI or explicitly scoped release activity because the source distribution SHA256 is release-specific. Rejected: Keep version 0.1.0 in the staged recipe | it can become silently stale while SHA and license placeholders are replaced. Rejected: Leave conda runtime dependencies unbounded | that would diverge from the verified package metadata dependency policy. Confidence: high Scope-risk: narrow Directive: When conda-forge is in scope, replace version, sdist SHA256, and SPDX license together before running the gate with --require-conda. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python scripts/check_release_gate.py --production --require-conda Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-conda-gate Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-conda-gate/* Tested: ./.venv/bin/python -m pip check Tested: sdist tar listing confirms conda recipe, release gate checker, and release workflow tests are packaged Tested: codebase-graph setup refresh and graph-query count Not-tested: Actual conda-forge staged-recipes CI; release-specific version/SHA/license values are still owner/release inputs.
Adds PyPI project URLs for homepage, repository, issues, and changelog so production package consumers can find source, support, and release history directly from distribution metadata. Constraint: License metadata is still intentionally owner-selected and not inferred by this change. Rejected: Leave project links only in README | package indexes and installers surface Project-URL metadata directly. Confidence: high Scope-risk: narrow Directive: Keep project URLs aligned with repository ownership if the package is transferred. Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-project-urls Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-project-urls/* Tested: ./.venv/bin/python -m pip check Tested: built PKG-INFO includes Homepage, Repository, Issues, and Changelog Project-URL entries Tested: codebase-graph setup refresh and graph-query count Not-tested: Rendering on PyPI production project page.
Keep the production release checker on the structured GateIssue path when required release files are absent. Missing release workflows and conda recipes now fail as actionable gate issues instead of escaping as FileNotFoundError tracebacks. Constraint: The production gate must still leave license, PyPI, hosted CI, vulnerability-reporting, and release-specific conda values owner-controlled. Rejected: Let missing files fail through Python exceptions | production operators need stable gate codes and messages. Confidence: high Scope-risk: narrow Directive: Keep release readiness failures structured so CI and operators can distinguish local gate defects from owner-controlled release blockers. Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python scripts/check_release_gate.py --production --require-conda Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-release-gate-hardening Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-release-gate-hardening/* Tested: ./.venv/bin/python -m pip check Tested: codebase-graph setup refresh and graph-query count Not-tested: External GitHub/PyPI production settings, which require owner account access.
Tightens production boundaries around runtime identity, HTTP MCP sessions, raw graph queries, and release smoke coverage. Setup configs now validate their rooted path invariants, explicit configs drive the reported runtime repo identity, HTTP requests carry session ids instead of sharing a listener-wide MCP session, and packaged smoke tests exercise mcp install --verify through an isolated client config path. Constraint: License selection, PyPI/GitHub confirmations, hosted CI status, private vulnerability reporting, and release-specific conda metadata remain owner-controlled production gates. Rejected: Keep HTTP compatibility through a listener-global session | one initialize request must not unlock tool calls for unrelated HTTP clients. Rejected: Isolate packaged installer smoke by changing HOME | that perturbs LadyBugDB extension resolution and hides the actual installer contract. Confidence: high Scope-risk: moderate Directive: Keep setup config paths rooted under the configured repo .codebaseGraph directory unless a future explicit unsafe override includes dedicated tests and docs. Directive: Keep HTTP MCP clients carrying Mcp-Session-Id after initialize; do not reintroduce listener-global session unlocks. Tested: ./.venv/bin/ruff check . Tested: ./.venv/bin/python -m pytest Tested: ./.venv/bin/python scripts/check_release_gate.py Tested: ./.venv/bin/python scripts/check_release_gate.py --production --require-conda Tested: ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-prod-hardening Tested: ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-prod-hardening/* Tested: ./.venv/bin/python -m pip check Tested: ./.venv/bin/python scripts/smoke_built_wheel.py ./.venv/bin/codebase-graph Tested: codebase-graph setup refresh and graph-query count Not-tested: Hosted GitHub Actions matrix, PyPI Trusted Publisher settings, private vulnerability reporting settings, and conda-forge staged-recipes CI.
Record the selected MIT license in package metadata and the conda recipe. The release-gate tests now assert that license metadata is resolved while leaving only owner confirmations and release-specific conda version/hash placeholders outside this task. Constraint: Existing tracked LICENSE declares MIT, so package and conda metadata now use that selected SPDX identifier. Rejected: Leave conda license placeholder unresolved | the SPDX license is known even though version and sdist SHA are release-specific. Confidence: high Scope-risk: narrow Directive: Do not change the SPDX license without updating LICENSE, pyproject metadata, conda recipe metadata, and release-gate tests together. Tested: ./.venv/bin/ruff check ., ./.venv/bin/python -m pytest -q, ./.venv/bin/python scripts/check_release_gate.py --production --confirm trusted-publisher --confirm pypi-environment --confirm hosted-ci-green --confirm private-vulnerability-reporting, ./.venv/bin/python -m build --no-isolation --outdir /private/tmp/codebasegraph-dist-license.K6QKsh, ./.venv/bin/python -m twine check /private/tmp/codebasegraph-dist-license.K6QKsh/* Not-tested: PyPI production publishing and conda-forge staged-recipes CI.
The failed Actions run exposed two release-surface mismatches: strict pip-audit was auditing an editable or unpublished local distribution, and package metadata still used the old codebase-graph PyPI name. Align the distribution name with the published cbasegraph project and audit dependency declarations with project-path pip-audit in CI and release workflows. Constraint: PyPI project name is cbasegraph while CLI entry points remain codebase-graph and codebase-graph-mcp Rejected: Keep environment-level pip-audit on the local package | dev and pre-publish versions are not necessarily present on PyPI Confidence: high Scope-risk: moderate Directive: Do not reintroduce strict environment auditing of the local distribution before publish; audit project dependencies and keep pip check for installed wheel consistency Tested: .venv/bin/python -m pytest -q Tested: .venv/bin/ruff check . Tested: .venv/bin/python -m pip_audit --strict . --progress-spinner off --cache-dir /private/tmp/codebase-graph-audit-pip-cache Tested: .venv/bin/python -m build --outdir /private/tmp/codebase-graph-dist Tested: .venv/bin/python -m twine check /private/tmp/codebase-graph-dist/* Not-tested: Hosted GitHub Actions rerun after push
GitHub started annotating the workflow because the pinned JavaScript actions still default to Node.js 20, and the parallel Ubuntu 3.12 CI jobs were racing to save the same setup-python pip cache key. The workflows now opt JavaScript actions into Node.js 24 explicitly and only keep pip caching on the matrix test job where cache keys are naturally separated by OS and Python version. Constraint: GitHub Actions Node.js 20 deprecation begins forcing Node.js 24 by default on June 2, 2026. Rejected: Unpin action refs to version tags | repository release gate requires immutable action pins. Rejected: Keep pip caching on all Ubuntu 3.12 jobs | setup-python emits cache reservation noise when parallel jobs share the key. Confidence: high Scope-risk: narrow Directive: Keep GitHub-hosted workflows warning-free; do not reintroduce shared setup-python cache keys across parallel jobs without checking hosted logs. Tested: .venv/bin/python -m pytest tests/test_release_workflows.py -q Tested: .venv/bin/ruff check . Tested: .venv/bin/python -m pytest -q Not-tested: Hosted GitHub Actions warning annotations before push.
The forced Node 24 environment still produced hosted warning annotations because some pinned actions continued to advertise node20 in their metadata. CI now pins checkout v5 and setup-python v6 by immutable SHA, and release-please is pinned to its Node 24 major. The artifact upload/download actions still target node20 at their latest major, so the workflows avoid them and hand release distributions to PyPI through the existing GitHub release assets instead. Constraint: Workflow action refs must remain immutable commit SHAs. Constraint: actions/upload-artifact v5 and actions/download-artifact v5 still declare runs.using node20. Rejected: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 | GitHub still emits a warning when forced Node 24 runs node20-targeted action metadata. Rejected: Keep release artifacts as Actions artifacts | the artifact actions are themselves the remaining Node 20 warning source. Confidence: high Scope-risk: moderate Directive: Keep first-party GitHub actions pinned to commits whose action.yml declares node24, and avoid artifact actions until they publish a node24-compatible major. Tested: .venv/bin/python -m pytest tests/test_release_workflows.py -q Tested: .venv/bin/ruff check . Tested: .venv/bin/python -m pytest -q Not-tested: End-to-end production release because it requires an actual release-created run and PyPI environment approval.
The Node 20 action warning was fixed, but hosted checks still emitted annotations from windows-latest runner migration notices and setup-python cache deserialization. CI now uses an explicit Windows runner label and workflows no longer request pip caching, removing those hosted warning sources rather than relying on cache rollover. Constraint: The warnings are emitted by GitHub-hosted runner infrastructure, so local tests can only guard workflow shape. Rejected: Wait for stale setup-python caches to expire | the warning would continue until cache eviction and could reappear. Rejected: Keep windows-latest | GitHub currently annotates that label with a migration notice. Confidence: high Scope-risk: narrow Directive: Reintroduce setup-python caching only with hosted evidence that it does not emit cache warning annotations. Tested: .venv/bin/python -m pytest tests/test_release_workflows.py -q Tested: .venv/bin/ruff check . Tested: .venv/bin/python -m pytest -q Not-tested: Hosted Actions after this commit before push.
Hosted macOS Python 3.10 setup was emitting pip cache deserialization warnings while installing certificates, even after Actions cache usage was removed. Disabling pip's on-runner cache at workflow scope keeps setup and install steps from reading the stale hosted cache while preserving the existing package/test matrix. Constraint: GitHub-hosted macOS image can contain stale pip cache entries before repository steps run. Rejected: Drop macOS Python 3.10 coverage | would hide the warning by reducing platform coverage. Confidence: medium Scope-risk: narrow Directive: Keep workflow-level pip cache disabled unless hosted runner cache annotations are explicitly rechecked. Tested: .venv/bin/python -m pytest tests/test_release_workflows.py -q Tested: .venv/bin/ruff check tests/test_release_workflows.py Tested: .venv/bin/ruff check . Tested: .venv/bin/python -m pytest -q
Add an ontology-preserving block serializer, a tiktoken benchmark CLI, a SearchService fixture, focused serializer/token tests, and the generated token comparison report. Retrieval semantics and ontology definitions are left unchanged. Constraint: Do not change graph ontology or retrieval semantics Rejected: Index tables, numeric lookup dictionaries, relation abbreviations, and type abbreviations | violates the readable ontology-preserving format requirement Confidence: high Scope-risk: moderate Directive: Keep block output directly readable and preserve literal ontology terms when changing the serializer Tested: ./.venv/bin/ruff check .; ./.venv/bin/pytest -q; ./.venv/bin/python scripts/compare_graph_output_tokens.py --fixture tests/fixtures/search_service_graph_search.json --encoding o200k_base --output docs/graph_output_token_comparison.md Not-tested: Large multi-query production corpus beyond the committed SearchService fixture
Add a display-only agent block serializer and a benchmark flag so token comparisons can measure the aggressive format separately from the exact ontology-preserving block. Constraint: Preserve the original ontology-preserving serializer for exact semantic-equivalence use cases Rejected: Replacing the ontology-preserving block outright | stable IDs and exact scores are still needed for machine-facing graph workflows Confidence: high Scope-risk: narrow Directive: Use --block-format ontology when canonical equivalence matters; --block-format agent is intentionally lossy Tested: ./.venv/bin/ruff check .; ./.venv/bin/pytest -q; ./.venv/bin/python scripts/compare_graph_output_tokens.py --queries SearchService --queries CompactContextBuilder --queries GraphMaterializer --queries handle_tool_call --queries schema_payload --queries GraphRuntimeConfig --queries ContextNode --queries SearchRequest --queries LadybugCodeGraphStore --queries graph_query_adapter --encoding o200k_base --limit 3 --profile brief --budget 600 --context-limit 2 --block-format agent --output /tmp/graph_output_token_comparison_10_examples_agent_reduced.md Not-tested: Agent reduced-mode parser or canonical equality, because this mode intentionally omits fields
Restore stable result IDs to the reduced agent-facing block serializer so follow-up graph calls can still target exact nodes while keeping the other display-only reductions. Constraint: Keep the reduced block readable and preserve the exact ontology-preserving serializer unchanged Rejected: Leaving IDs omitted | saves tokens but weakens follow-up graph lookup workflows Confidence: high Scope-risk: narrow Directive: Result IDs are intentionally retained in both ontology and agent block formats Tested: ./.venv/bin/ruff check .; ./.venv/bin/pytest -q; ./.venv/bin/python scripts/compare_graph_output_tokens.py --queries SearchService --queries CompactContextBuilder --queries GraphMaterializer --queries handle_tool_call --queries schema_payload --queries GraphRuntimeConfig --queries ContextNode --queries SearchRequest --queries LadybugCodeGraphStore --queries graph_query_adapter --encoding o200k_base --limit 3 --profile brief --budget 600 --context-limit 2 --block-format agent --output /tmp/graph_output_token_comparison_10_examples_agent_ids.md Not-tested: No additional corpus beyond the 10 live benchmark queries
The release workflow could only exercise the pypi environment during a real release, which made Trusted Publishing setup hard to validate without uploading an immutable package version. Add a workflow_dispatch smoke path that enters the same pypi environment and validates GitHub OIDC claims for release.yml while skipping release-please and all publish steps. Constraint: PyPI uploads are immutable and should not be used as environment smoke tests. Rejected: Publish a throwaway production version | would permanently consume a real PyPI version. Rejected: Separate smoke workflow | would not validate the release.yml workflow identity PyPI is configured to trust. Confidence: medium Scope-risk: narrow Directive: Keep this smoke path non-publishing; use the real release path for upload validation. Tested: .venv/bin/python -m pytest tests/test_release_workflows.py -q Tested: .venv/bin/python scripts/check_release_gate.py --production --confirm trusted-publisher --confirm pypi-environment --confirm hosted-ci-green --confirm private-vulnerability-reporting Tested: .venv/bin/ruff check tests/test_release_workflows.py Tested: .venv/bin/ruff check . Tested: .venv/bin/python -m pytest -q
* feat: expose block graph output to agents Add block output selection to graph CLI and MCP search/context presentation while keeping JSON as the default structured payload. Update generated and root agent instructions so agent exploration uses block format instead of JSON. Constraint: JSON must remain available for strict structured APIs and tests Rejected: Replacing JSON output globally | graph schema/query/API consumers still need strict structured payloads Rejected: Creating root CLAUDE.md | user requested generator support without adding the file now Confidence: high Scope-risk: moderate Directive: Treat block output as presentation-only; retrieval payloads and MCP structuredContent should stay JSON Tested: ./.venv/bin/ruff check .; ./.venv/bin/pytest -q; ./.venv/bin/codebase-graph graph-search SearchService --repo-root . --no-refresh --detail slim --context-limit 1 --format block; ./.venv/bin/codebase-graph setup --repo-root . --mcp-client none Not-tested: External MCP clients beyond the stdio protocol test * chore: target file access restriction * refactor(cli): prevent graph command contract drift Centralize graph CLI and MCP tool metadata behind shared command specs, and move MCP installer client behavior into a single strategy registry. Keep legacy search/context commands and runtime block output compatible while reducing duplicate payload and serialization shaping. Constraint: Public CLI flags and JSON/block output shapes must remain compatible Rejected: Remove legacy search/context commands | existing tests and callers still cover them as supported compatibility surfaces Rejected: Delete parseable block format | retained as debug/test support while runtime keeps compact agent blocks Confidence: high Scope-risk: moderate Directive: Add future graph tools or MCP install clients through the shared registries rather than branching in CLI/MCP dispatch Tested: ./.venv/bin/pytest -q Tested: ./.venv/bin/ruff check Tested: ./.venv/bin/codebase-graph setup --repo-root . --mcp-client none Not-tested: Static type checking; no mypy or pyright executable is installed in the project venv * fix(setup): align generated agent instructions The generated codebaseGraph instruction block now matches the current AGENTS.md wording and the refactored CLI guidance. The stale extra prohibition sentence caused setup regeneration churn without reflecting a CLI requirement. Constraint: Generated instructions must stay stable when codebase-graph setup is rerun after CLI refactors Rejected: Update AGENTS.md directly | regeneration already reports the current file as unchanged once the template is fixed Confidence: high Scope-risk: narrow Directive: Keep instruction text limited to durable CLI workflow guidance, not extra behavioral rules outside the CLI contract Tested: ./.venv/bin/pytest -q tests/test_setup_workflow.py Tested: ./.venv/bin/ruff check src/codebase_graph/setup/instructions.py tests/test_setup_workflow.py Tested: ./.venv/bin/codebase-graph setup --repo-root . --mcp-client none Not-tested: Full test suite; change is limited to setup instruction text and its regression assertion * fix(setup): preserve graph-first instruction Restore the user-authored graph-first reading rule in both the generated instruction block and the checked-in AGENTS.md block, using the requested plural target-files wording. Constraint: Generated AGENTS.md guidance must preserve user-authored workflow policy, not just CLI flag guidance Rejected: Keep the previous generator cleanup | it removed an intentional instruction from the generated block Confidence: high Scope-risk: narrow Directive: Do not remove the graph-first source-reading sentence from setup instructions without explicit user approval Tested: ./.venv/bin/pytest -q tests/test_setup_workflow.py Tested: ./.venv/bin/ruff check src/codebase_graph/setup/instructions.py tests/test_setup_workflow.py Not-tested: Full test suite; change is limited to generated instruction text and its setup regression assertion * docs: reduce README duplication for clearer onboarding The README had grown into a mixed quick start, MCP reference, release note, and troubleshooting index. This keeps the public landing page focused on installation, MCP use, CLI workflow, development, and links to deeper release/security docs. Constraint: README should align with current setup and standalone MCP install naming behavior Rejected: Keep full client config examples in README | dry-run output is the source of truth and avoids duplicating adapter-specific formats Confidence: high Scope-risk: narrow Directive: Keep README focused on user onboarding; put detailed release and client-format procedures in dedicated docs or generated dry-run output Tested: ./.venv/bin/python -m pytest; ./.venv/bin/ruff check .; codebase-graph setup --repo-root . --mcp-client none --instructions-target skip
The README opener now stays short and follows with a capabilities paragraph that names the graph workflows agents can use before opening source files. Constraint: Keep the addition focused on README introduction only Rejected: Expand the install section again | the request was for capability framing, not setup detail Confidence: high Scope-risk: narrow Directive: Keep capability claims aligned with graph-search, graph-context, architecture-query, and read-only graph-query surfaces Tested: ./.venv/bin/ruff check .; ./.venv/bin/python -m pytest; codebase-graph setup --repo-root . --mcp-client none --instructions-target skip
Refreshes the README opening to keep the user-provided advantages wording around faster orientation, reduced guesswork, impact-aware changes, and lower token/tool overhead. Constraint: User requested preserving their latest README wording without restoring the previous intro paragraph. Confidence: high Scope-risk: narrow Tested: .venv/bin/python -m pytest Tested: .venv/bin/ruff check . Tested: git diff --check Tested: codebase-graph setup --repo-root . --mcp-client none Not-tested: Rendered Markdown preview
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
codex/devdevelopment branch intomain.Impact
This promotes the current development line to
main, including the repository restructure and project automation needed for packaging, release, and agent graph workflows.Validation
codex/devagainstmain: 53 commits ahead, 0 behind.codex/dev.Not run in this session: full local test suite.