Skip to content

Commit fc8bde1

Browse files
committed
📝 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.
1 parent cf6f41f commit fc8bde1

37 files changed

Lines changed: 199 additions & 0 deletions

‎packages/code-review-agent/src/documents/components/AbstractionNames.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ props:
1515
default: "New abstraction files: {names}. Verify 3+ consumers."
1616
required: [pr]
1717
additionalProperties: false
18+
description: >-
19+
Flag new files whose names suggest a speculative abstraction. `<AbstractionNames
20+
pr={pr} />` reports created TypeScript files named like factories, adapters or
21+
helpers, so a reviewer can ask what consumes them.
1822
---
1923

2024
```ts eval

‎packages/code-review-agent/src/documents/components/CleanupIssues.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ props:
88
type: object
99
required: [cleanupAnalysis, diagnostics]
1010
additionalProperties: false
11+
description: >-
12+
File and retire GitHub issues for the repository's worst cleanup clusters.
13+
`<CleanupIssues cleanupAnalysis={analysis} diagnostics={diagnostics} />` keeps one
14+
labelled issue per file in the top five and closes the ones that dropped out. It
15+
does nothing without `GITHUB_TOKEN` and `GITHUB_REPOSITORY`.
1116
---
1217

1318
```ts persist eval

‎packages/code-review-agent/src/documents/components/CommentReview.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ props:
66
type: object
77
required: [pr]
88
additionalProperties: false
9+
description: >-
10+
Review the pull request's code comments for ones that only restate the code.
11+
`<CommentReview pr={pr} />` asks the model in scope which are redundant, reads the
12+
replies to earlier suggestions to see which a person rejected, and renders what is
13+
still outstanding.
914
---
1015

1116
<CommentReviewData pr={props.pr} as="reviewData" />

‎packages/code-review-agent/src/documents/components/ConfigSourceMix.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ props:
1515
default: "PR mixes config and source changes."
1616
required: [pr]
1717
additionalProperties: false
18+
description: >-
19+
Flag a change that mixes configuration and source edits. `<ConfigSourceMix pr={pr}
20+
minFiles={5} />` reports when both appear in a pull request larger than `minFiles`.
1821
---
1922

2023
```ts eval

‎packages/code-review-agent/src/documents/components/DeepInfraProvider.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ props:
66
type: string
77
required: [model]
88
additionalProperties: false
9+
description: >-
10+
Answer this document's `<Sample>` calls from DeepInfra. `<DeepInfraProvider
11+
model="Qwen/Qwen3-235B">…</DeepInfraProvider>` handles samples that name that model
12+
and samples that name none, and passes the rest outward. It requires
13+
`DEEPINFRA_TOKEN`.
14+
context: >-
15+
The Markdown whose samples this provider answers.
916
---
1017

1118
```ts persist eval

‎packages/code-review-agent/src/documents/components/DescriptionCheck.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ props:
1515
default: "PR description must explain what and why."
1616
required: [pr]
1717
additionalProperties: false
18+
description: >-
19+
Require a pull-request description that explains the change. `<DescriptionCheck
20+
pr={pr} minLength={50} />` reports a body shorter than `minLength`.
1821
---
1922

2023
<Finding when={props.pr.meta.body.length < props.minLength}

‎packages/code-review-agent/src/documents/components/EnsureOxlint.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ props:
66
type: string
77
default: ".reviews/.oxlint"
88
additionalProperties: false
9+
description: >-
10+
Install the review's pinned Oxlint and tsgolint binaries. `<EnsureOxlint />`
11+
downloads them into the sensor directory and verifies each against a known checksum,
12+
so a review measures the version it expects. It fails on a platform it ships no
13+
build for.
914
---
1015

1116
```ts eval

‎packages/code-review-agent/src/documents/components/Finding.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ props:
1111
type: string
1212
required: [when, message]
1313
additionalProperties: false
14+
description: >-
15+
Report one review finding. `<Finding when={tooLarge} severity="error" message="Split
16+
this PR." />` renders a severity icon and the message when `when` holds, and nothing
17+
when it does not — so a rule can be written unconditionally and stay quiet.
1418
---
1519

1620
```ts eval

‎packages/code-review-agent/src/documents/components/Format.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@ props:
33
type: object
44
properties: {}
55
additionalProperties: false
6+
description: >-
7+
Reformat its content as Markdown. `<Format>…</Format>` renders the content,
8+
normalizes it through remark and trims the result.
9+
context: >-
10+
The Markdown to reformat.
611
---
712

813
```ts eval

‎packages/code-review-agent/src/documents/components/GitHubAuth.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@ props:
33
type: object
44
properties: {}
55
additionalProperties: false
6+
description: >-
7+
Authorize the GitHub requests made inside it. `<GitHubAuth>…</GitHubAuth>` adds a
8+
bearer token to requests to `api.github.com` over HTTPS and leaves every other host
9+
untouched. Without `GITHUB_TOKEN` it adds nothing and the requests still run.
10+
context: >-
11+
The Markdown whose GitHub requests are authorized.
612
---
713

814
```ts persist eval

0 commit comments

Comments
 (0)