Skip to content

Commit 7215b37

Browse files
authored
🛡️ Take the review component graph out of the checkout (#83) (#817)
* 🛡️ Install the review component graph from the package (#83) The review and repository-analysis components lived in `.reviews/` and every entrypoint reached them with `--include`, which made the component graph a property of the checkout being reviewed: a pull request could add its own `Finding.md` and the review would run the branch's copy while reporting on it. `@executablemd/code-review-agent` now owns the graph and declares it to the `run` profile. Thirty-five packaged Markdown components — twenty-eight review components, five policies, and review-owned copies of `Sample.md` and `Instruction.md` — cross as `Markdown()` declarations carrying the packaged bytes, a package-and-asset origin, and the digest this build ships. The six TypeScript components cross as reserved registrations. Both tiers mean the host claims the name, so a same-named checkout file is not chosen, and a second claim on one name is refused at admission rather than ordered. `src/review-components.ts` is the only assembly boundary, and the CLI attaches it through one helper wherever the `run` profile is built: ordinary execution, a nested `<Execution host="run">`, the syntax/validation registry, `<Plan>`'s admission validator, and `xmd plan`'s candidate validation. `xmd test` at its root claims none of it; its run child claims all of it. Ordinary inclusion and repository discovery are untouched — only these forty-one names are spoken for. This commit establishes the boundary only. The `.reviews` definitions and every task and workflow `--include` argument stay in place, and the trusted tier now wins over them, so the existing entrypoints remain runnable while this is reviewed. * 🔥 Retire the checkout-relative review components (#83) Every supported review and repository-analysis entrypoint now takes its component graph from the installed code-review package. The five `deno.json` tasks and the two Actions workflows pass no component `--include`, and the executable definitions under `.reviews/components/` and the five `.reviews/policies/*.md` are deleted. While a command still passed `--include .reviews/components`, the retired directory was a live dependency of that command: restoring a file under it put a checkout-supplied component back in front of a review. Removing the argument is what makes the boundary from the previous commit load-bearing. What stays in `.reviews/` is this repository's own review programs, the sensor profile, and the journals and provisioned binaries a run reads and writes — inputs and outputs, not component definitions. Tool scopes and behavioral fixtures follow the files: `check`, `lint` and `fmt` drop the deleted directory, the two lint-scope tests drop it from `LINTED`, and the review, Oxlint-policy, schema-conformance and UnusedInDiff suites read the package assets. A new case parses the five tasks and both workflows and refuses any of the three retired paths, scoped by name so the unrelated core smoke includes in `ci.yml` stay valid. The unrelated `packages/core/components` includes in `ci.yml`, the general core `Sample`/`Instruction` tests, and the deliberate byte-equivalence assertion are unchanged. * 🔧 Regenerate the publish workflow for the new dependency edges (#83) `scripts/gen-publish-workflow.md` derives the publish job graph from the workspace manifests, and this stack changed two edges: the code-review package now depends on core and runtime for its declarations, and the CLI depends on the code-review package. So `code-review-agent` gains those `needs`, moves ahead of the CLI, and the CLI waits on it. Generated output — `deno task gen:publish-workflow`, which CI re-runs and diffs. No hand edits. * 📝 Document the review components the run profile now advertises (#83) Installing the graph put 35 names into the vocabulary `xmd syntax` and `<Syntax />` advertise, and none of them carried a description. SX2 in `packages/cli/tests/syntax-cli.test.ts` refuses an undocumented complete built-in, and it was right to: a reader cannot tell "nobody has written this yet" from "this component has nothing to say", and an agent handed the catalog got 35 names with no prose. A declared Markdown component documents itself from its own frontmatter, the way `Plan.md` does, so each now states a description — plus `as` and `context` where they apply — following `.agents/component-descriptions.md`. `Sample.md` and `Instruction.md` state theirs inside their `meta:` block rather than at the top level. `parseMeta()` treats an explicit `meta:` block as the whole of a definition's metadata and ignores top-level keys, so a top-level description on those two is read by nobody. Their `packages/core/components/` originals get the identical prose, which keeps the two copies byte-identical and is what the equivalence assertion is for. This is frontmatter metadata: it takes no part in expansion, resolution, validation, authority or the journal, so no schema, form, return or behavior moves. The declaration digests change with the bytes, as they should. * 🐛 Ship packaged documents that sit in subdirectories (#83) `packagedDocuments()` lists `src/documents/` recursively and every entry it returns becomes a `copyFile`. A recursive listing names the directories as well as the files inside them, so the first package whose documents are not flat fails the whole npm build with `EINVAL` — "the source path is neither a regular file nor a symlink to a regular file". Nothing had noticed because `packages/cli/src/documents/` is flat. The review graph keeps its documents under `components/` and `policies/`, so it is the first, and `packages/code-review-agent` became a CLI dependency in this stack — which is what put it in the CLI's npm build at all. Only Node and Bun would have seen it: Deno resolves the assets from the source tree and stays green, which is why `scripts/tests/cli-npm-bin.test.ts` is where it surfaced. Verified by building the package: 30 component documents, 5 policies and `components.md` land under `npm/esm/src/`. * 🔧 Read through the package filesystem and prove the graph ships (#83) Two corrections to `0f179628`. `stat` comes from `@effectionx/fs` and is yielded directly, so the packaged- document walk goes through the repository's filesystem like everything else on this path. `node:fs/promises` keeps only what the package does not provide — recursive copy, temp directories, and a recursive listing, since its own `readdir` takes no options — and the import comment now says so. The npm proof is the contract rather than the symptom. `cli-npm-bin.test.ts` compares every entry of `REVIEW_DOCUMENTS` against its emitted copy under `npm/esm/src/documents/`, byte for byte, plus `src/components.md`. Driven by the manifest rather than a count or a second list: a component added to the graph and not shipped is exactly what has to fail, and a hand-kept list is what would not notice. Presence and content are told apart so a missing asset reports as one instead of an unexplained ENOENT. Three mutations discriminate it: copying directories as files reproduces the original EINVAL; skipping nested documents builds a clean package the review cannot resolve a component from; and altering one emitted document's bytes, which loads and digests fine, is caught by the byte comparison alone and named. * 📝 State the review components' GitHub mutations accurately (#83) Five descriptions promised less than their components do, and three of them hid a mutation of the pull request entirely. `<SuggestRemoval>` does not simply replace the previous bot review: it deletes earlier ones only where GitHub permits deletion, so a submitted review can remain and the old wording's promise that reviews never stack was not one the component keeps. It now says what it does — delete where allowed, acknowledge declined suggestions and resolve their threads, then post pending findings as a new review. `<CommentReview>` reconciles inline removal suggestions when findings remain and the GitHub environment is present, and said nothing about it. `<SlopPolicy>` and `<PrPolicyReport>` compose it, so an author reading either of them was told they render a section and not that running one writes to the pull request. All three now disclose it. `<RepoPolicyReport>` stated the cleanup issues unconditionally, but `<CleanupIssues>` does nothing without `GITHUB_TOKEN` and `GITHUB_REPOSITORY`. `Sample.md` and `Instruction.md` each carried a second copy of one metadata key at the top level, left behind when the prose moved into their `meta:` blocks. `parseMeta()` treats an explicit `meta:` block as the complete metadata object, so those copies were read by nobody — `<Sample>` still reports its `as` and `context` and `<Instruction>` its `context` with them gone. Both pairs stay byte-equivalent. The `unused-in-diff` comment still named `.reviews` as the source it reads. Descriptive metadata and one comment only: no body, schema, form or return moves, and nothing asserts on this wording.
1 parent 142b29a commit 7215b37

77 files changed

Lines changed: 1853 additions & 173 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/publish-packages.yml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
- name: Validate the manifests declare this version
3131
run: |
3232
VERSION="${{ steps.resolve.outputs.value }}"
33-
for f in packages/durable-streams/deno.json packages/runtime/deno.json packages/core/deno.json packages/acp/deno.json packages/testing/deno.json packages/test-agent/deno.json packages/web/deno.json packages/workflow/deno.json packages/cli/deno.json packages/code-review-agent/deno.json; do
33+
for f in packages/durable-streams/deno.json packages/runtime/deno.json packages/core/deno.json packages/acp/deno.json packages/code-review-agent/deno.json packages/testing/deno.json packages/test-agent/deno.json packages/web/deno.json packages/workflow/deno.json packages/cli/deno.json; do
3434
declared="$(jq -r .version "$f")"
3535
if [ "$declared" != "$VERSION" ]; then
3636
echo "::error::$f declares $declared, not $VERSION — the tag does not match the manifests"
@@ -89,6 +89,13 @@ jobs:
8989
package: packages/acp
9090
version: ${{ needs.version.outputs.value }}
9191

92+
code-review-agent:
93+
needs: [version, core, runtime]
94+
uses: ./.github/workflows/publish-one.yml
95+
with:
96+
package: packages/code-review-agent
97+
version: ${{ needs.version.outputs.value }}
98+
9299
testing:
93100
needs: [version, core, durable-streams, runtime]
94101
uses: ./.github/workflows/publish-one.yml
@@ -118,19 +125,12 @@ jobs:
118125
version: ${{ needs.version.outputs.value }}
119126

120127
cli:
121-
needs: [version, acp, core, durable-streams, runtime, test-agent, testing, web, workflow]
128+
needs: [version, acp, code-review-agent, core, durable-streams, runtime, test-agent, testing, web, workflow]
122129
uses: ./.github/workflows/publish-one.yml
123130
with:
124131
package: packages/cli
125132
version: ${{ needs.version.outputs.value }}
126133

127-
code-review-agent:
128-
needs: [version]
129-
uses: ./.github/workflows/publish-one.yml
130-
with:
131-
package: packages/code-review-agent
132-
version: ${{ needs.version.outputs.value }}
133-
134134
jsr:
135135
needs: [version]
136136
runs-on: ubuntu-latest

‎.github/workflows/repo-analysis.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,6 @@ jobs:
4848
GITHUB_REPOSITORY: ${{ github.repository }}
4949
run: |
5050
./dist/xmd run .reviews/AnalyzeRepoCI.md \
51-
--include .reviews/components \
52-
--include .reviews/policies \
53-
--include packages/core/components \
5451
-j .reviews/journal.analyze.ci.jsonl > .reviews/analyze-report.md
5552
5653
- name: Write run metadata

‎.github/workflows/review.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,6 @@ jobs:
3838
DEEPINFRA_TOKEN: ${{ secrets.DEEPINFRA_TOKEN }}
3939
run: |
4040
./dist/xmd run .reviews/ReviewPR.md \
41-
--include .reviews/components \
42-
--include .reviews/policies \
43-
--include packages/core/components \
4441
-j .reviews/journal.jsonl \
4542
--verbose
4643

‎.reviews/components/ReviewSection.md‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎.reviews/policies/README.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,32 @@
11
# Review Policies
22

3-
This directory contains discrete, executable policy documents.
3+
The executable policy documents and the reusable review components they compose
4+
with are installed from `@executablemd/code-review-agent`, not from this
5+
directory. The package declares them to every `xmd` run, so a review resolves the
6+
same components whatever checkout it is reviewing and whatever directory it runs
7+
from — which is the point: a review must not be answerable by its subject.
8+
9+
The policies live at `packages/code-review-agent/src/documents/policies/`:
410

511
- `ScopePolicy.md` checks PR size and scoping hygiene.
612
- `BloatPolicy.md` surfaces structural bloat patterns.
713
- `SlopPolicy.md` surfaces verbosity/slop indicators.
814
- `ExtraneousCodePolicy.md` asks for semantic/correctness-focused review.
915
- `RepoCleanupPolicy.md` performs repo-wide cleanup policy analysis.
1016

11-
Policies are composed by report components:
17+
Policies are composed by report components, which the same package declares:
1218

1319
- `PrPolicyReport` composes PR policies.
1420
- `RepoPolicyReport` composes repo policies.
1521

16-
Reusable workflow steps and primitives remain in `.reviews/components/`.
22+
Reusable workflow steps and primitives are at
23+
`packages/code-review-agent/src/documents/components/`, and the six TypeScript
24+
components at `packages/code-review-agent/src/components/`.
25+
26+
What stays here is this repository's own review programs — `ReviewPR.md`,
27+
`ReviewPR.local.md`, `AnalyzeRepo.md`, `AnalyzeRepoCI.md` and
28+
`DispatchRepoAnalysis.md` — which compose the installed components, together
29+
with the sensor configuration and runtime state those runs read and write
30+
(`.oxlintrc.json`, `.oxlint/`, the generated `tsconfig.oxlint.json`, and the
31+
journals). None of the review and analysis commands passes a component
32+
`--include`.

‎architecture.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4536,6 +4536,69 @@ and a name is not a secret, so a component could build one, reach the record and
45364536
answer that everything is exact. It is reclaimed with its execution, reaches no
45374537
public entrypoint, and marks nothing on the segments themselves.
45384538

4539+
### The review graph is the mechanism's first whole consumer
4540+
4541+
`<Plan>` declares one component. The code-review agent declares thirty-five, and
4542+
reserves six registrations beside them, which is what the boundary looks like
4543+
when a complete program graph moves into an installation.
4544+
4545+
**Why it moved.** The review and repository-analysis components were Markdown
4546+
and TypeScript files in `.reviews/`, and every entrypoint reached them through
4547+
checkout-relative component includes. That made the component graph a property of
4548+
the checkout being reviewed: a pull request could add a file named `Finding.md`
4549+
and the review would run the branch's own copy while reporting on it. A review is
4550+
precisely the program that must not be answerable by its subject.
4551+
4552+
The five review and analysis tasks and the two Actions workflows now pass no
4553+
component include at all, and the retired definitions are gone. What stays in
4554+
`.reviews/` is this repository's own review programs and the sensor
4555+
configuration, journals and runtime state they read and write — inputs and
4556+
outputs, not component definitions.
4557+
4558+
**Who owns it.** `@executablemd/code-review-agent` does, and
4559+
`packages/code-review-agent/src/review-components.ts` is the only assembly
4560+
boundary. The Markdown lives at `src/documents/components/` and
4561+
`src/documents/policies/` and is read from that module's own URL, so one lookup
4562+
is correct in a source checkout, a published npm package and a compiled binary
4563+
with no checkout at all. The read goes to the Effection filesystem directly
4564+
rather than through `API.Fs` or the document-facing `Files` authority, both of
4565+
which are middleware a running document could compose around — a review whose
4566+
own components could be answered by the document under review would have moved
4567+
the problem rather than solved it.
4568+
4569+
**Two tiers, one meaning.** The thirty-five Markdown components cross as
4570+
declarations, carrying the packaged bytes, a stable origin naming the package and
4571+
the asset rather than a path, and the digest of what that build shipped. The six
4572+
TypeScript components — `CommentReviewData`, `CommentReviewState`, `Doctor`,
4573+
`OxlintDiagnostics`, `RepositoryInventory` and `ReviewContext` — cross as
4574+
reserved registrations. The mechanisms differ in what they carry and agree in
4575+
what they mean. Moving only the Markdown would have left shadowable exactly the
4576+
six components that run processes, read credentials and reach the network.
4577+
4578+
**Where it is installed.** Everywhere the production `run` profile is assembled,
4579+
from one helper rather than a list spelled at each site: ordinary non-testing
4580+
execution, a nested `<Execution host="run">`, the registry `xmd syntax` and
4581+
structural validation enter, `<Plan>`'s internal admission validator, and
4582+
`xmd plan`'s candidate validation. A Plan is therefore checked against the
4583+
vocabulary the later `xmd run` supplies, rather than a narrower one that would
4584+
refuse a program the run would have accepted. `xmd test` at its root is a
4585+
different profile and gains none of it; the run child it can launch gains all of
4586+
it.
4587+
4588+
**What it does not change.** Ordinary inclusion and repository discovery are
4589+
untouched. A caller's own component of an unclaimed name resolves as it always
4590+
did; only these forty-one names are spoken for. The claims do include generic
4591+
ones — `Format`, `Pattern`, `Threshold`, `Instruction`, `Sample` — which is the
4592+
intended consequence of the anti-shadowing contract rather than an oversight, and
4593+
a collision with another host claim is refused at assembly rather than settled by
4594+
order.
4595+
4596+
**One deliberate duplication.** The package ships its own copies of `Sample.md`
4597+
and `Instruction.md` rather than pointing at `packages/core/components/`, so the
4598+
graph a review runs is complete in one package. A regression holds the copies
4599+
byte-identical to core's, which makes a future divergence an explicit decision in
4600+
the code-review package instead of something that happens to one of them.
4601+
45394602
## The installed structural syntax boundary
45404603

45414604
A trusted host may declare a structural construct and the regions written

‎deno.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,12 +67,12 @@
6767
"test": "deno test --allow-all --frozen",
6868
"verify": "deno run --allow-all --node-modules-dir=none --cached-only --frozen scripts/preflight.ts scripts/verify.ts",
6969
"vendor:verify": "deno run --allow-read --allow-write=/tmp --allow-env --allow-run --cached-only --frozen scripts/verify-cloudflare-dofs.ts",
70-
"check": "deno check --frozen && deno check --frozen .reviews/components/*.ts",
70+
"check": "deno check --frozen",
7171
"check:jsr": "deno publish --dry-run --allow-dirty",
72-
"review": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.jsonl",
73-
"review:local": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.local.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.local.jsonl",
74-
"analyze": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepo.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.analyze.jsonl",
75-
"analyze:ci": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepoCI.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.analyze.ci.jsonl",
76-
"analyze:dispatch": "deno run --allow-all packages/cli/src/deno.ts run .reviews/DispatchRepoAnalysis.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.dispatch.jsonl"
72+
"review": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.md -j .reviews/journal.jsonl",
73+
"review:local": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.local.md -j .reviews/journal.local.jsonl",
74+
"analyze": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepo.md -j .reviews/journal.analyze.jsonl",
75+
"analyze:ci": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepoCI.md -j .reviews/journal.analyze.ci.jsonl",
76+
"analyze:dispatch": "deno run --allow-all packages/cli/src/deno.ts run .reviews/DispatchRepoAnalysis.md -j .reviews/journal.dispatch.jsonl"
7777
}
7878
}

‎deno.lock‎

Lines changed: 9 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,8 @@
7373
"test:node": "tsx scripts/runtime-tests.ts node",
7474
"test:bun": "bun scripts/runtime-tests.ts bun",
7575
"test:deno": "deno task test",
76-
"lint": "oxlint -c .oxlintrc.json --ignore-pattern 'scripts/tests/fixtures/**' --ignore-pattern '**/npm/**' --ignore-pattern 'packages/workflow/vendor/cloudflare-computer-dofs/**' --ignore-pattern 'packages/acp/vendor/acpx/**' packages scripts .reviews/components && oxfmt --check packages scripts .reviews/components/*.ts",
77-
"fmt": "oxfmt --write packages scripts .reviews/components/*.ts"
76+
"lint": "oxlint -c .oxlintrc.json --ignore-pattern 'scripts/tests/fixtures/**' --ignore-pattern '**/npm/**' --ignore-pattern 'packages/workflow/vendor/cloudflare-computer-dofs/**' --ignore-pattern 'packages/acp/vendor/acpx/**' packages scripts && oxfmt --check packages scripts",
77+
"fmt": "oxfmt --write packages scripts"
7878
},
7979
"workspaces": [
8080
"packages/*"

‎packages/cli/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
"dependencies": {
1414
"@effectionx/stream-helpers": "0.8.3",
1515
"@executablemd/acp": "workspace:*",
16+
"@executablemd/code-review-agent": "workspace:*",
1617
"@executablemd/core": "workspace:*",
1718
"@executablemd/durable-streams": "workspace:*",
1819
"@executablemd/runtime": "workspace:*",

0 commit comments

Comments
 (0)