Skip to content

feat(5225): link YAML values to the scripts and local files they name - #5342

Open
Deepjyoti-Sarmah wants to merge 5 commits into
Graphify-Labs:v8from
Deepjyoti-Sarmah:feat/5225-yaml-value-refs
Open

Deepjyoti-Sarmah wants to merge 5 commits into
Graphify-Labs:v8from
Deepjyoti-Sarmah:feat/5225-yaml-value-refs

Conversation

@Deepjyoti-Sarmah

Copy link
Copy Markdown
Contributor

What does this PR do?

Closes #5225. A workflow's run: pnpm run check now links to the check script in package.json, and a compose bind mount ./settings.yaml:/etc/demo/settings.yaml links to settings.yaml. Before this, the YAML extractor kept keys only, so the issue's repro had no edge other than contains.

The extractor never looked at values:

extract_yaml
  walk(mapping)    key -> node, then recurse only into mappings and sequences
                   a scalar value (`command: --config ./settings.yaml`) is dropped
  walk(sequence)   recurse only into structured items
                   a scalar item (`- ./settings.yaml:/etc/...`) is dropped

Reading the value is not enough on its own. The extractor sees one file at a time, so it cannot know whether settings.yaml was scanned or whether package.json declares check. That is answered after every file is extracted, the way Markdown code-span mentions already are:

 extract_yaml(file)
   walk keys as before
+  value_refs(file, tree)       what a scalar names, as a path relative to the YAML file
+  -> raw_calls {language: "yaml", caller_nid: <key node>, ref_kind, target_path, callee}

 extract(all files)
   shared cross-file call pass
+    skip language == "yaml"     a script name is not a call
   language resolvers
+    yaml_value_refs             target scanned?  ->  key --references--> file / script key

What is read, and what is left alone

YAML Resolved against Edge
workflow run: npm|pnpm|yarn|bun run NAME package.json in the step's working directory run key → scripts.NAME
workflow run: ./x.sh, bash x.sh, python x.py, ... the step's working directory run key → file
compose volume ./host:/container[:mode] the compose file's folder volumes key → file
compose volume {type: bind, source: ./host} the compose file's folder source key → file

The working directory follows GitHub's precedence: step working-directory, then job defaults.run, then workflow defaults.run, then the repository root (the folder holding .github).

Nothing is guessed. These get no edge: ${{ }} expressions, $VAR, pipes, &&/; chains, named volumes, absolute host paths, URLs, a missing script, and a file that exists but was not scanned (ignored, excluded, or outside the root).

command: --config ./settings.yaml is not linked. It runs inside the container, against the container's working directory, so ./settings.yaml there is a container-side path, which the issue asks not to guess. In the repro it names the same file the bind mount does, and the mount already gives that edge. A test pins this.

Five commits

7a779fb0  test(5225): pin YAML value references to scripts and local files
9ab5447b  feat(5225): read literal script and path references from YAML values
17d58f63  feat(5225): record YAML value references as raw_calls
95acae48  feat(5225): link YAML value references to scanned scripts and files
8efe0ee8  perf(5225): index only file nodes and package scripts in the YAML resolver

The tests go in first and fail. 17d58f63 records the references and skips them in the call pass, but creates no edges, so reverting 95acae48 turns the feature off and leaves the graph as it is on v8.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Tests or CI
  • Refactor
  • Security fix

Verification & Invariants

Invariant: a references edge out of a YAML value exists only when the value spells the target literally and the target is a scanned node.

  • Read the CONTRIBUTING.md guide.
  • Reproduced the issue and identified the invariant.
  • Made the smallest fix necessary.
  • Added a regression test (if bug fix) or isolated boundary test.
  • Kept the PR description synchronized with the final implementation.
  • Documented any limitations / unsupported cases explicitly.

Merge Danger

Door: two-way. Reverting 95acae48 and 8efe0ee8 removes every new edge. The cache schema goes 48 → 49 so cached YAML extractions re-run and pick up the new raw_calls.

Blast Radius: small.

  • Only .github/workflows/* files and YAML with a top-level services: are read for values; other YAML gives the same output as v8.
  • Node ids do not change. The only additions are references edges with context: "yaml_value" and confidence: EXTRACTED.
  • The schema bump re-extracts cached YAML once. Any other open PR that bumps the schema to 49 will need to renumber.

Limitations

  • Step run keys share one node. The existing walk ids every step's run key the same way (<file>_steps_run), so all steps of a workflow hang their edges off one node. Twenty steps calling pnpm run check give one edge, not twenty.
  • package.json must be in the working directory itself. npm and pnpm search upwards for the nearest one; that search is not followed, so run: pnpm run check from a folder without its own package.json gets no edge.
  • Each run: line is read as one plain command. A line with shell syntax is skipped as a whole, including pnpm run check && pnpm run build.
  • Not covered: uses: ./.github/actions/x, compose env_file, build.context, GitLab CI and other CI formats. Each could follow the same path.

How was this tested?

The issue's script, before and after:

before  non-containment: []
after   non-containment: [('.github/workflows/check.yml', 'references', 'package.json'),
                          ('compose.yaml', 'references', 'settings.yaml')]

tests/test_yaml_value_refs.py, 23 cases, run end to end through extract():

links      pnpm/npm/yarn run check -> check;  step / job / workflow working-directory
           ./scripts/check.sh, bash scripts/check.sh -> check.sh
           compose short and long bind syntax;  ../settings.yaml from deploy/compose.yaml
no edge    ${{ matrix.task }}, | tee, &&, $TASK, missing script
           named volume, absolute path, ${PWD}, ../../../../etc/passwd
           compose command: --config ./settings.yaml
           target under node_modules (exists, not scanned)
cache      extract with the target missing, add it, re-extract with the YAML served from cache

YAML tests (test_yaml_value_refs.py + test_yaml_extraction.py) at each commit:

commit result
7a779fb0 tests 12 failed, 31 passed
9ab5447b collector 12 failed, 31 passed
17d58f63 raw_calls 12 failed, 31 passed
95acae48 resolver 43 passed
8efe0ee8 perf 43 passed

I measured three designs against the same tests, plus a 2,000-file corpus (500 × workflow, compose, settings, package.json), warm cache, min of 3:

design tests warm evidence
v8 n/a 11.95s
S1: check the disk inside extract_yaml, like bash source 22 / 23 11.98s fails the cache test: the cached YAML never learns the target appeared. Also emits edges to unscanned files and to files outside the root, with the host's absolute path in the target id (var_tmp_..._outside_yaml); build drops them, but the extraction JSON carries them
S2: raw_calls + resolver (this PR) 23 / 23 11.98s resolver 0.90s under cProfile, down from 1.18s after 8efe0ee8
S3: resolver re-parses each YAML file 23 / 23 28.36s cProfile: 68s in the resolver, 48s of it load_all + compose_all on the second parse

Related suites (-k "yaml or markdown or cache or registry or json or extract"): 1847 passed, 7 failed. All 7 also fail on v8 340268a7 in the same environment: test_hook_bash_read, test_hook_compact, test_markdown_sections CLI, and two test_skill_* cached-run tests, all subprocess based.

ruff check graphify/extractors/yaml_refs.py graphify/yaml_resolution.py \
           graphify/extractors/yaml_config.py tests/test_yaml_value_refs.py  -> All checks passed

Not tested: the full suite (only the related suites above), and Windows. Targets are joined and normalised with posixpath, and file-node paths have \ turned into / first.

@github-actions github-actions Bot added the contributor Pull request from a returning community contributor label Nov 19, 2026
@github-actions

Copy link
Copy Markdown

Thanks for the pull request, @Deepjyoti-Sarmah. 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.11 and 3.13, and that the change keeps extraction deterministic.

@Deepjyoti-Sarmah
Deepjyoti-Sarmah marked this pull request as ready for review November 19, 2026 16:42

@graphify-labs graphify-labs Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify code review View in Graphify

Review completed · 8efe0ee85551

Warning

Merge confidence: 3/5 · Review before merging · 🟠 High impact
1 P2 bug checked against the code

The change extracts literal script and local-file references from selected YAML workflows and Compose volume declarations.

Full summary

The change extracts literal script and local-file references from selected YAML workflows and Compose volume declarations. A resolver later links those references to matching files or package script keys in the scanned corpus.

Bugs (1)

P2 · Update workflow detection in value_refs to recognize relative .github/workflows/ paths: otherwise, eligible run references in workflow YAML files are omitted. Inspect source

Detailed review · checked against the code

Relative scans skip workflow value references

When a repository is scanned using relative paths, workflow YAML files may not be recognized, so their script and file references are not extracted.

Expected: Workflow detection selects _workflow_refs, which extracts eligible script or file references for later resolution.
Actually: The path check misses the relative workflow path, so value_refs returns no workflow references unless the document also has a top-level services key.

For a relative workflow path such as .github/workflows/check.yml, Path.as_posix() does not contain the substring /.github/workflows/. The workflow branch therefore does not call _workflow_refs; unless the YAML also has a top-level services key, value_refs returns an empty mapping. extract_yaml calls value_refs for each document and records only the returned entries, so workflow run values do not yield references on this path.

  • Independent source review: Inspected the YAML extraction caller and the value-reference resolver. The caller records references only from value_refs results; the resolver can link references only after they have been recorded. The inspected tests cover YAML structure and workflow key spelling, but do not test workflow value-reference extraction.

  • Some lookups asked for files or lines that do not exist; the review was told and carried on.

What this review covered
  • Some lookups asked for files or lines that do not exist; the review was told and carried on.
  • One review pass used all of its turns for reading code, so it reported from what it had already read.
  • 6 of 6 changed files inspected. This is scope, not a correctness guarantee.
Code graph and static checks · 5389 functions depend on this change

Impact & health

Impact — 5389 functions depend on the 558 functions this change touches.

Health — this change adds coupling hotspots:

  • worse: extract() — 1284 callers, 78 callees
  • worse: extract_yaml() — 20 callers, 11 callees
  • worse: collect_files() — 24 callers, 7 callees
  • new: _refs() — 11 callers, 3 callees
  • worse: walk() — 1 callers, 6 callees

Formal checks — 5389 functions this change can affect weren't formally checked in this review. Formal checks are informational only.

Gate & verification

✅ PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

  • verification_scope: 4682 function(s) in the blast radius were not formally verified this run

Test selection

594 of 594 test file(s) selected (100%) via static blast radius.

Escalated to a full run for safety (uncovered-code) — the selection is not trustworthy on its own (see below). CI should run the whole suite.

  • tests/pi.test.ts — full-run-safety
  • tests/test_4874_jvm_resolution.py — impact, full-run-safety
  • tests/test_4909_reference_binding_scale.py — full-run-safety
  • tests/test_4978_reconcile_cost.py — impact, full-run-safety
  • tests/test_4992_ts_import_types.py — impact, full-run-safety
  • tests/test_5072_splittable_under_cap_retry.py — full-run-safety
  • tests/test_affected_cli.py — full-run-safety
  • tests/test_affected_defines.py — full-run-safety
  • tests/test_affected_member_seed.py — full-run-safety
  • tests/test_affected_overrides.py — impact, full-run-safety
  • tests/test_affected_path_file_node.py — full-run-safety
  • tests/test_affected_seed_reference_forms.py — full-run-safety
  • tests/test_agents_platform.py — full-run-safety
  • tests/test_alias_folding.py — impact, full-run-safety
  • tests/test_analyze.py — impact, full-run-safety
  • tests/test_anthropic_custom_endpoint.py — full-run-safety
  • tests/test_antigravity_install.py — full-run-safety
  • tests/test_apm_fallback_version.py — full-run-safety
  • tests/test_architecture_doc.py — full-run-safety
  • tests/test_astro_extraction.py — impact, full-run-safety
  • tests/test_astro_import_ids.py — impact, full-run-safety
  • tests/test_atomic_canvas_export.py — full-run-safety
  • tests/test_atomic_version_stamp.py — full-run-safety
  • tests/test_atomic_writes.py — full-run-safety
  • tests/test_backend_env_isolation.py — full-run-safety
  • tests/test_backend_extras.py — full-run-safety
  • tests/test_backend_opt_in.py — full-run-safety
  • tests/test_benchmark.py — full-run-safety
  • tests/test_benchmark_raw_graph.py — full-run-safety
  • tests/test_benchmark_real_query.py — full-run-safety
  • tests/test_binary_media_words.py — impact, full-run-safety
  • tests/test_blade_extractor.py — impact, full-run-safety
  • tests/test_build.py — impact, full-run-safety
  • tests/test_build_located_semantic_identity.py — impact, full-run-safety
  • tests/test_build_merge_dedup_scope.py — impact, full-run-safety
  • tests/test_build_merge_ghost_fold_4955.py — impact, full-run-safety
  • tests/test_build_merge_hyperedges_and_prune.py — impact, full-run-safety
  • tests/test_build_merge_shrink_guard.py — impact, full-run-safety
  • tests/test_builtin_global_type_refs.py — impact, full-run-safety
  • tests/test_c_include_resolution.py — impact, full-run-safety
  • tests/test_cache.py — impact, full-run-safety
  • tests/test_cache_long_paths.py — impact, full-run-safety
  • tests/test_cache_stale_import_target.py — impact, full-run-safety
  • tests/test_cache_windows_case_4925.py — impact, full-run-safety
  • tests/test_callflow_html.py — full-run-safety
  • tests/test_cargo_introspect.py — full-run-safety
  • tests/test_cargo_missing_manifest.py — full-run-safety
  • tests/test_carried_hyperedge_remap.py — impact, full-run-safety
  • tests/test_case_only_decl_ids_4904.py — impact, full-run-safety
  • tests/test_case_sensitive_resolution.py — impact, full-run-safety
  • … and 544 more

⚠️ changed code file(s) with no mapped test (graphify/yaml_resolution.py) — 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.

Docs that may be stale (advisory)

Every flagged function

  • extract() in graphify/extract.py:11750 · 1284 callers, 78 callees: fans out to 78 callees (efferent coupling); 1284 callers depend on it (afferent coupling)
  • collect_files() in graphify/extract.py:13904 · 24 callers, 7 callees: fans out to 7 callees (efferent coupling); 24 callers depend on it (afferent coupling)
  • extract_yaml() in graphify/extractors/yaml_config.py:185 · 20 callers, 11 callees: fans out to 11 callees (efferent coupling); 20 callers depend on it (afferent coupling)
  • _refs() in tests/test_yaml_value_refs.py:20 · 11 callers, 3 callees: 11 callers depend on it (afferent coupling)
  • walk() in graphify/extractors/yaml_config.py:272 · 1 callers, 6 callees: fans out to 6 callees (efferent coupling)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contributor Pull request from a returning community contributor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Resolve literal workflow script and local config path references in YAML

1 participant