docs(agents): simplify testing and pull-request guidance wording - #1997
Merged
Conversation
The surviving half of `contracts-entry-closure.test.ts` walked ~490 candidate files and parsed each one to assert that nothing value-imports the two wide contracts facades. `eslint/no-restricted-imports` already states exactly that, and `allowTypeImports` already draws the one distinction that made the walker seem necessary: `import type` is erased, so it stays legal. Verified rather than assumed, because the override semantics are not additive: a same-rule override REPLACES the parent, so a top-level rule would have been silently dropped for `src/**`, and the existing `"off"` entry for `exec.ts` and the test tree would have exempted the files that carried most of the cost #1959 removed. So the paths are added per zone, and the blanket `"off"` becomes a facade-only config that keeps the `node:child_process` exemption it existed for. Planted red in all three zones — `src/core/capabilities.ts`, a `src/__tests__` file, and `packages/capture-kit/src` — each flagged, while a type-only import in the same probe file was not. A first probe read as a pass because the sed that built it produced a type-only import; the zone was re-probed with a real value import rather than trusting the green. Misconfiguration fails loudly, which is why this is safe to rely on: a typo'd rule name makes oxlint exit 1 with "Rule not found in plugin", not pass silently (the failure mode #1976 records for the `rg` assertions). What a linter cannot replace, and stays: the eager-closure budgets. Those are a transitive-weight property — a module already imported grows an import, and the cost arrives without any single file's import list changing. Per-file rules cannot see that, and `no-restricted-imports` can only ban specifiers named in advance, which is precisely what #1950/#1956/#1959 could not have named.
testing.md sat 15 bytes under the 10k per-doc check:agent-guidance cap. Rewrite both docs in shorter, plainer sentences without dropping any fact, threshold, or identifier (backtick-identifier sets verified unchanged against the previous revision). Also fix testing.md's gate catalog sentence being separated from its code block and the missing blank line before pull-requests.md's Reviewing section.
Size Report
npm unpacked components
Startup median (7 runs, lower is better):
Top changed chunks: no changes in the largest emitted chunks. Top changed packed filesNo changed packed files. |
thymikee
added
the
ready-for-human
Member
Author
|
Review of exact head The extra |
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites
docs/agents/testing.mdanddocs/agents/pull-requests.mdin shorter, plainer sentences so the always-loadable agent guidance costs less context. No fact, threshold, command, or identifier was dropped — this is a wording-only pass.testing.md: 9,985 → 9,540 bytes. The file sat 15 bytes under the 10k per-doccheck:agent-guidancecap; it now has headroom again. Also reunites the gate-catalog sentence with its code block (a paragraph had been interposed between them) and unwraps a code span that broke across a line.pull-requests.md: 6,868 → 6,639 bytes. Tightens the wordiest readiness and size-scrutiny passages and adds the missing blank line before## Reviewing.Deliberately untouched:
adr-0019-unit.md(active-migration checklist whose wording carries incident context),device-verification.md,cli-flags.md, and the small docs (already dense, marginal wins).Validation
Docs-only; no runtime behavior, so no runtime tests apply.
pnpm check:agent-guidanceis green after the edits. Fidelity was verified the way the PR #1888 restructure prescribed: diffed the backtick-identifier sets of each file old vs new — both sets are unchanged (the only diff noise was a line-wrap artifact of per-line backtick pairing, resolved by unwrapping the span). Markdown is excluded from oxfmt, so no formatting gate applies.Two files touched; scope stayed within the requested doc simplification.