Status: owner-authorized implementation plan; implemented locally, integration pending.
Requested after the frontend modeling review; the owner subsequently authorized implementation.
This document does not change the saved schedule. The first static
inspection slice was merged as PR #21, commit f70ebf4; the older preparation wording in the
checkpoint is historical and must not cause another merge attempt.
wsr inspect <file> reports static job dependencies and rejects invalid dependency graphs before
printing a successful summary. This delivers useful workflow understanding and establishes graph
validation for eventual planning, without pretending to implement scheduling or execution.
The accepted inspection milestone already includes this behavior. The modeling catalog supplies patterns; it does not require adopting every proposed type or upstream library in this iteration. Step identifiers, runner-label lists and broader frontend forms remain subsequent slices. No full GHA-schema rewrite or speculative universal IR is necessary to add this behavior.
Keep the existing CLI syntax, supported source subset, deterministic job sorting, step ordering, exit codes and no-execution behavior. Add these source forms to ordinary jobs:
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo build
test:
needs: build
runs-on: ubuntu-latest
steps:
- run: echo test
package:
needs: [build, test]
runs-on: ubuntu-latest
steps:
- run: echo package
For a job with dependencies, add a line after its runner line:
Job: package
Runner: ubuntu-latest
Needs: build, test
Jobs without dependencies retain their existing output. Preserve declared dependency order; do not present the lexicographic job summary as a topological execution order. Disconnected valid jobs remain valid. A successful graph check means only that the static relationships are valid.
Missing needs means no edges. Accept a literal identifier or a sequence of literal identifiers;
an empty sequence means no edges. Reject null, scalar numbers/booleans, mappings, empty identifiers,
non-string list entries and expressions explicitly. Match identifier/reference behavior against
the pinned official reference before implementation; do not silently case-fold or normalize IDs.
Retain repeated references in the source summary; graph validation must not count duplicate edges
as separate unfinished dependencies. This is not permission to change unrelated identifier rules.
Failure leaves stdout empty, uses exit 1, and identifies the file and structural source location.
Use a route such as jobs.test.needs[1] for the first list entry and jobs.test.needs for scalar
form. Source line/column support is not expanded by this slice. Messages must distinguish:
Validate the entire graph before rendering any workflow output. Diagnose unknown endpoints before cycle analysis so malformed references are not misreported as cycles. Do not infer skipped-job, condition, matrix, failure, cancellation or reusable-workflow semantics from static edges.
| Owner | Proposed change |
|---|---|
wsr-gha source model |
Add strict scalar-or-list decoding for job needs; retain enough source-form information to locate diagnostics. |
wsr-gha semantic validation |
Resolve references within this source workflow and validate the directed graph without IO. Use a simple bounded traversal; no scheduler or new crate. |
wsr-types::inspection::JobSummary |
Add static dependency identifiers as source-summary data. This remains a pre-alpha inspection result, not executable IR or a stable serialized format. |
wsr inspect handler |
Render dependencies after complete validation; no GHA-specific graph logic in the host. |
Do not mutate/drop source edges merely to make an invalid graph pass. Share an immutable validated graph/result with future planning only when that feature needs an API; avoid a generic graph framework now. Respect the current no-dependency-adoption approach: upstream source guides the implementation, and official behavior guides fixtures. No zizmor dependency or TypeScript runtime is added here.
needs field, not a build/setup failure.
Implement decoding, summary data and rendering; verify scalar/list forms and unchanged no-edge
output. This intermediate green does not complete the feature until graph validation lands.needs cases and hostile-content/sentinel checks. Ensure scripts, hooks,
local action paths, repository configuration and network acquisition remain untouched.The feature is finished only after local acceptance/regressions, required hosted checks, review findings and merge are complete. The user has authorized the existing PR/merge workflow; this planning document does not expand it to releases, publication or changes outside WSR.
| Case | Observable expectation |
|---|---|
| No edges | Existing successful output remains byte-for-byte unchanged. |
| Scalar/list/empty list | Correct static edges; source list order retained; empty list renders no dependency line. |
| Forward reference, chain, diamond, disconnected nodes | Successful deterministic inspection regardless of declaration order. |
| Repeated reference | Source references retained; no false cycle or extra readiness count. |
| Unknown target | Exit 1, file/field diagnostic naming the missing target, empty stdout. |
| Self-cycle and longer cycle | Exit 1 with precise cycle evidence; blocked downstream nodes are not labelled cycle members. |
| Malformed types and expressions | Explicit structural/unsupported diagnostic; nothing silently coerced or evaluated. |
| Malicious scripts and references | Existing bytes/file inventory unchanged; no execution or acquisition. |
| Regression | Existing parser/help/remaining-placeholder contracts and current inspection fixtures still pass. |
Use Rust integration tests against the real binary, with focused compiler tests only where needed for a meaningful graph boundary. Put new committed inspection fixtures under the existing shared test-data conventions, not a parallel test framework. Import selected official fixtures only with pinned provenance and required notices. Reference comparison here covers static graph behavior; it does not claim equivalence of all GHA parsing, normalization or execution.
Commands supported by the current checkout:
cargo test -p wsr --test cli --test inspection --locked
cargo test -p wsr --test inspection --locked inspect_static_dependencies
cargo xtask ci
git diff --check
The named inspect_static_dependencies test is planned and must first be added; do not count a
zero-match filtered run as a passing acceptance test. Additional behavioral test names should
describe their individual negative/graph cases. cargo xtask ci includes the earlier standard
checks, so do not redundantly run xtask check and xtask test immediately before it.
If exact reference behavior conflicts with a proposed contract here, report the fixture and amend the plan before coding that conflict. Do not add a development TS sidecar merely to make this one iteration run; a reusable official-oracle harness is a separately bounded supporting feature.
Continue toward richer static inspection through named slices: step identities, runner selector forms, trigger/input preservation, source spans, and parsed unevaluated expressions. Order those by actual prerequisites and user-visible value. Canonical shell/Python examples require several of those features and must not be called supported by ignoring their additional fields.
A full GHA frontend remains a sequence of verified behaviors, not an 8–15k LOC target to fill. The execution engine, runtime selection, permission enforcement, provider distribution and beta features beyond inspection remain outside this iteration.