Repository navigation
docs(always-on): say large graph.json diffs in pull requests are expected - #4324
andrebrait wants to merge 1 commit into
Conversation
…cted A committed graphify-out/graph.json is rewritten whole on every build, so its pull-request diffs are large by design. Assistants reviewing such PRs flagged them as churn and proposed skipping the rebuild or its hooks. The Claude, AGENTS.md and Gemini blocks now say the diff is expected.
|
Thanks for the pull request, @andrebrait. A maintainer will review it soon. Want to talk it through while it is in review? Come join us on our Discord server. For longer-form discussion there is also GitHub Discussions. A couple of things that speed up review: make sure the test suite passes on Python 3.10 and 3.13, and that the change keeps extraction deterministic. |
… pull requests are expected Squashed from origin/docs/expected-graph-diffs (e6cf17c) onto upstream/v8.
![graphify-labs[bot]](https://avatars.githubusercontent.com/in/4356270?s=60&v=4){kind=small}
There was a problem hiding this comment.
Graphify reviewed this change.
No issues found by static checks — no coupling regressions or blocking issues in the code graph. That is not the same as safe to merge: see what was not checked.
Not checked: tests were not run; no formal proof of the changed code.
Graphify review — findings
Adds an always-on rule to the AGENTS, CLAUDE and GEMINI instruction blocks telling agents that a committed graphify-out/graph.json is rewritten whole on every build, so its large PR diffs are expected and shouldn't be flagged as churn or used to argue for skipping the rebuild or its hooks. The rule is registered as _GRAPH_DIFF_EDIT in ALWAYS_ON_SANCTIONED_EDITS (inserted right after the graphify update . rule) so the frozen-baseline byte check still accepts the new line while rejecting any other drift.
No blocking issues surfaced. 1 lower-confidence candidate did not survive cross-model review.
Analysis details — impact, health, verification
Impact & health
Graphify review
Impact — 278 functions depend on the 272 functions this change touches.
Health — grade A; 5 existing hotspot(s) in the area this change touches (pre-existing, not introduced here):
render()— 13 callers, 5 callees (high)audit_coverage()— 8 callers, 6 callees (high)main()— 3 callers, 11 callees (medium)monolith_roundtrip()— 3 callers, 5 callees (medium)test_audit_catches_a_dropped_non_allowlisted_heading()— 0 callers, 6 callees (medium)
Verification — 278 functions in the blast radius were not formally verified this run (proofs are advisory here).
Gate & verification
graphify gate
PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.
Advisory (not blocking):
- verification_scope: 278 function(s) in the blast radius were not formally verified this run
Test selection
Test selection
367 of 367 test file(s) selected (100%) via static blast radius.
Escalated to a full run for safety — the selection is not trustworthy on its own (see below). CI should run the whole suite.
tests/test_affected_cli.py— full-run-safetytests/test_affected_defines.py— full-run-safetytests/test_affected_member_seed.py— full-run-safetytests/test_agents_platform.py— full-run-safetytests/test_analyze.py— full-run-safetytests/test_anthropic_custom_endpoint.py— full-run-safetytests/test_antigravity_install.py— full-run-safetytests/test_apm_fallback_version.py— full-run-safetytests/test_architecture_doc.py— full-run-safetytests/test_astro_extraction.py— full-run-safetytests/test_astro_import_ids.py— full-run-safetytests/test_atomic_canvas_export.py— full-run-safetytests/test_atomic_version_stamp.py— full-run-safetytests/test_atomic_writes.py— full-run-safetytests/test_backend_env_isolation.py— full-run-safetytests/test_backend_extras.py— full-run-safetytests/test_benchmark.py— full-run-safetytests/test_benchmark_raw_graph.py— full-run-safetytests/test_blade_extractor.py— full-run-safetytests/test_build.py— full-run-safetytests/test_build_located_semantic_identity.py— full-run-safetytests/test_build_merge_dedup_scope.py— full-run-safetytests/test_build_merge_hyperedges_and_prune.py— full-run-safetytests/test_build_merge_shrink_guard.py— full-run-safetytests/test_builtin_global_type_refs.py— full-run-safetytests/test_cache.py— full-run-safetytests/test_cache_stale_import_target.py— full-run-safetytests/test_callflow_html.py— full-run-safetytests/test_cargo_introspect.py— full-run-safetytests/test_cargo_missing_manifest.py— full-run-safetytests/test_carried_hyperedge_remap.py— full-run-safetytests/test_case_sensitive_resolution.py— full-run-safetytests/test_charmap_encoding.py— full-run-safetytests/test_chunking.py— full-run-safetytests/test_cjs_module_extension.py— full-run-safetytests/test_claude_cli_backend.py— full-run-safetytests/test_claude_md.py— full-run-safetytests/test_cli_broken_pipe.py— full-run-safetytests/test_cli_export.py— full-run-safetytests/test_cli_help.py— full-run-safetytests/test_cloud_cta.py— full-run-safetytests/test_cluster.py— full-run-safetytests/test_cluster_ambiguous_scale.py— full-run-safetytests/test_cluster_exclude_hubs.py— full-run-safetytests/test_cobol_extractor.py— full-run-safetytests/test_codebuddy.py— full-run-safetytests/test_community_hub_labels.py— full-run-safetytests/test_community_labels_skill.py— full-run-safetytests/test_confidence.py— full-run-safetytests/test_corrupt_graph_json.py— full-run-safety- … and 317 more
non-code file(s) changed (
graphify/always_on/agents-md.md,graphify/always_on/claude-md.md,graphify/always_on/gemini-md.md,tools/skillgen/expected/graphify__always_on__agents-md.md,tools/skillgen/expected/graphify__always_on__claude-md.md…) → running the full suite for safety (a code graph can't see config/fixture/data deps)
changed code file(s) with no mapped test (
graphify/always_on/agents-md.md,graphify/always_on/claude-md.md,graphify/always_on/gemini-md.md,tools/skillgen/expected/graphify__always_on__agents-md.md,tools/skillgen/expected/graphify__always_on__claude-md.md…) — a coverage gap or a missing link — running the full suite rather than only the selected tests
Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.
|
Landed in 0.9.86 (now on PyPI) via an authorship-preserving cherry-pick, so your commit authorship is retained. Thank you, @andrebrait! |
2 participants
A committed
graphify-out/graph.jsonis rewritten whole on every build, so its pull-request diffs are large by design. Assistants reviewing such PRs flag the diff as churn and propose shrinking the graph or skipping the rebuild hooks, which defeats keeping the graph current.This adds one rule to the Claude, AGENTS.md and Gemini always-on blocks, after the
graphify updateline:The change is recorded as a sanctioned skillgen edit, and the regenerated
always_on/*.mdandexpected/files are included. All skillgen guards (--check,--always-on-roundtrip,--audit-coverage,--monolith-roundtrip) pass, as dotests/test_skillgen.pyandtests/test_install_strings.py. #4319 (compact one-linegraph.json) changes how these diffs look but not whether they happen.