Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(review): review:pre lists concrete findings in the change, each at its file and line (#9651)

Cindy Zhang692aa2647948
diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.md
index 0ac9d489f9..c7297d033e 100644
--- a/docs/contributing/pull-requests.md
+++ b/docs/contributing/pull-requests.md
@@ -116,9 +116,12 @@ pnpm review:pre # the working tree against origin/main
pnpm review:pre --base upstream/main # a fork whose main remote is upstream
pnpm review:pre --head HEAD # committed work only
pnpm review:pre --json # the same report as JSON
+pnpm review:pre --body-file body.md # also read the description for item h
+pnpm review:pre --pr 1234 # read the description with gh
```
-The report reads only the local repository. It prints:
+The report reads only the local repository, and the description when you pass
+one. It prints:
- each changed file and its class: record, owner-gated record, API report,
published package code, other package file, Lab, or repository;
@@ -126,9 +129,13 @@ The report reads only the local repository. It prints:
cite or that the added lines route;
- the global baseline claims that the linked components' review triggers route,
read at the merge base;
+- the authored line count, and whether the change merges into the base;
+- the findings for items h to l, each with its file and line, the rule, and
+ the fix;
- the checklist items that apply to this change, each with its reason.
-The report is a lookup. The records decide acceptance, not the report.
+The report is a lookup. The records decide acceptance, not the report. A
+finding is a lead to check, not a verdict.
### Find the governing records by hand
@@ -144,7 +151,8 @@ The report is a lookup. The records decide acceptance, not the report.
First apply the protocol above: one primary intent, no tagalongs, and
specifications last. Then check each item that the report lists. Item d applies
-to every pull request.
+to every pull request. The report checks items h to l automatically and lists
+each finding at its file and line.
- **a. API delta.** A current record decides each added or changed row of a
package's `api-report.md`. The record is current at the merge base or changes
@@ -199,6 +207,30 @@ to every pull request.
([`architecture:knowledge-contracts`](../architecture/knowledge-contracts.md#dec-14--one-owner-approval-binds-a-pull-requests-spec-content)
DEC-14). The description also reports `## Writing rubric results`
([Writing specification records](spec-writing.md)).
+- **h. Size (automatic).** More than 2,000 authored lines, without lockfiles,
+ snapshots, or generated files, is a finding. A description line that declares
+ a behavior-module pull request and names the module (`Behavior module: <name>`)
+ removes the limit. A `Batch:` row raises it to 8,000. For a stacked pull
+ request, pass `--base` the branch below it, so the count covers only its own
+ lines.
+- **i. Shared owners (automatic).** In Core source, an added resize observer,
+ document or window listener, module-level warn-once set, or parent walk
+ across shadow roots is a finding: call `observeResize`,
+ `subscribeInput`, `useDevWarning`, or `parentAcrossShadow`
+ ([`architecture:react-component-runtime`](../architecture/react-component-runtime.md#boundaries-and-invariants)
+ INV16).
+- **j. Effects (automatic).** An added Effect with no comment that names the
+ system it syncs, an Effect that only copies a value into a ref, and a DOM node
+ in React state are findings
+ ([`architecture:react-component-runtime`](../architecture/react-component-runtime.md#boundaries-and-invariants)
+ INV1 and INV3).
+- **k. Release notes and records (automatic).** A package that ships a change
+ with no Changeset, a `[fix]`, `[feat]`, or `[perf]` Changeset for a package
+ where nothing that ships changes, such as a change to tests or tooling only,
+ and a gap row left in a record for a claim this change builds are findings.
+- **l. Mergeable (automatic).** A conflict with the base branch is a finding.
+ For the working tree, the check merges the last commit. It writes nothing to
+ the repository.
### Use a fresh session for an agent's change
diff --git a/scripts/lib/pre-review-findings.mjs b/scripts/lib/pre-review-findings.mjs
new file mode 100644
index 0000000000..eced9ba573
--- /dev/null
+++ b/scripts/lib/pre-review-findings.mjs
@@ -0,0 +1,389 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Concrete findings in one change, each at a file and line.
+ * @input A unified diff, a reader for the head tree, the Changeset coverage
+ * result, and the pull request description when one is given.
+ * @output Findings for checklist items h to l: the item, the file and line,
+ * the rule, and the fix.
+ * @position Called by `scripts/pre-review.mjs`. SYNC: keep each rule in step
+ * with its item in `docs/contributing/pull-requests.md#pre-review-checklist`.
+ */
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import {parseFrontmatter} from '../check-changesets.mjs';
+
+const require = createRequire(import.meta.url);
+const {parseEntry} = require('../changeset-entry-format.cjs');
+
+export const SIZE_LIMIT = 2000;
+
+const LOCKFILE =
+ /(?:^|\/)(?:pnpm-lock\.yaml|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock)$/;
+const SNAPSHOT = /(?:^|\/)__snapshots__\/|\.snap$/;
+const COMMENT = /^\s*(?:\/\/|\/\*|\*)/;
+const DIRECTIVE = /eslint-|@ts-|prettier-ignore|@pr-a11y/;
+const RUNTIME = '`architecture:react-component-runtime`';
+
+/**
+ * Changed lines a person wrote: not lockfiles, snapshots, or generated files.
+ * `changedCountByFile` comes from `readDiff`.
+ */
+export function authoredLineCount(
+ changedCountByFile,
+ isGenerated = () => false,
+) {
+ let total = 0;
+ for (const [file, count] of Object.entries(changedCountByFile)) {
+ if (!LOCKFILE.test(file) && !SNAPSHOT.test(file) && !isGenerated(file)) {
+ total += count;
+ }
+ }
+ return total;
+}
+
+export const BATCH_SIZE_LIMIT = 8000;
+const BEHAVIOR_MODULE_DECLARATION =
+ /^[ \t]*(?:[-*][ \t]*)?(?:Behavior module:[ \t]*\S|This behavior-module (?:pull request|PR) (?:adds|changes|builds|extends) \S)/m;
+const BATCH_ROW = /^[ \t]*(?:[-*|][ \t]*)?Batch:[ \t]*\S/m;
+const STACK_LINE = /^[ \t]*(?:[-*|][ \t]*)?Stack:[ \t]*\S/m;
+
+/**
+ * Item h. `body` is the pull request description, or null when the report
+ * cannot read it.
+ */
+export function sizeFindings(authored, body) {
+ if (authored <= SIZE_LIMIT) return [];
+ if (body != null && BEHAVIOR_MODULE_DECLARATION.test(body)) return [];
+ const isBatch = body != null && BATCH_ROW.test(body);
+ if (isBatch && authored <= BATCH_SIZE_LIMIT) return [];
+ const limit = isBatch ? BATCH_SIZE_LIMIT : SIZE_LIMIT;
+ const split = `Split the change into pull requests of at most ${limit} authored lines.`;
+ let fix = split;
+ if (body == null) {
+ fix = `${split} A declared behavior-module pull request, or a \`Batch:\` row up to ${BATCH_SIZE_LIMIT} lines, is exempt; pass --body-file or --pr to read the description.`;
+ } else if (STACK_LINE.test(body)) {
+ fix = `${split} For a stacked pull request, pass --base the branch below it, so the count covers only its own lines.`;
+ }
+ return [
+ {
+ item: 'h',
+ file: null,
+ line: null,
+ rule: `${authored} authored lines, over ${limit}${isBatch ? ' for a batch' : ''}`,
+ fix,
+ },
+ ];
+}
+
+const DOCUMENT_RECEIVER =
+ /^(?:document|window|doc|win|view|defaultView|globalThis|self)$|(?:Document|Window)$/;
+
+/** True when the line adds a listener to a document or a window. */
+export function addsDocumentListener(text) {
+ for (const match of text.matchAll(
+ /([\w$]+)(\([^()]*\))?\s*\??\.addEventListener\s*\(/g,
+ )) {
+ const [, name, call] = match;
+ if (
+ call
+ ? /^get\w*(?:Window|Document)$/.test(name)
+ : DOCUMENT_RECEIVER.test(name)
+ ) {
+ return true;
+ }
+ }
+ return /\([^()]*\b(?:document|window|ownerDocument|defaultView)\b[^()]*\)\s*\??\.addEventListener\s*\(/.test(
+ text,
+ );
+}
+
+/**
+ * Concerns Core owns in one shared module (`architecture:react-component-runtime`
+ * INV16). `exempt` holds the files that implement the concern.
+ */
+export const SHARED_OWNERS = [
+ {
+ concern: 'A new ResizeObserver',
+ owner: 'observeResize',
+ path: 'packages/core/src/utils/sharedResizeObserver.ts',
+ exempt: ['packages/core/src/utils/sharedResizeObserver.ts'],
+ matches: text =>
+ /\bnew\s+(?:[\w$]+\.)*ResizeObserver\s*\(|\.ResizeObserver\b/.test(text),
+ },
+ {
+ concern: 'A new document or window listener',
+ owner: 'subscribeInput',
+ path: 'packages/core/src/utils/inputStream.ts',
+ exempt: ['packages/core/src/utils/inputStream.ts'],
+ matches: addsDocumentListener,
+ },
+ {
+ concern: 'A module-level warn-once set',
+ owner: 'useDevWarning',
+ path: 'packages/core/src/hooks/useDevWarning.ts',
+ alternative:
+ '`warnOnce` from `packages/core/src/utils/devWarning.ts` outside render',
+ exempt: ['packages/core/src/utils/devWarning.ts'],
+ matches: text =>
+ /^(?:export\s+)?(?:const|let)\s+[\w$]*(?:[wW]arn|[rR]eported|[lL]ogged)[\w$]*\s*(?::[^=]+)?=\s*new\s+(?:Weak)?Set\b/.test(
+ text,
+ ),
+ },
+ {
+ concern: 'A local parent walk across shadow roots',
+ owner: 'parentAcrossShadow',
+ path: 'packages/core/src/utils/flatTree.ts',
+ exempt: ['packages/core/src/utils/flatTree.ts'],
+ matches: text =>
+ /\.assignedSlot\b|\bas\s+ShadowRoot\s*\)\s*\.host\b|\binstanceof\s+ShadowRoot\b[^;]*\.host\b/.test(
+ text,
+ ),
+ },
+];
+
+/** Item i. `addedLines` are the shipped source lines the change adds. */
+export function sharedOwnerFindings(addedLines) {
+ const findings = [];
+ for (const {file, line, text} of addedLines) {
+ if (!file.startsWith('packages/core/src/') || COMMENT.test(text)) continue;
+ for (const owner of SHARED_OWNERS) {
+ if (owner.exempt.includes(file) || !owner.matches(text)) continue;
+ const alternative = owner.alternative ? `, or ${owner.alternative}` : '';
+ findings.push({
+ item: 'i',
+ file,
+ line,
+ rule: `${owner.concern}; Core owns this concern`,
+ fix: `Call \`${owner.owner}\` from \`${owner.path}\`${alternative}. Extend the owner when it lacks what you need (${RUNTIME} INV16).`,
+ });
+ }
+ }
+ return findings;
+}
+
+const EFFECT = /\b(?:React\.)?use(?:Isomorphic)?(?:Layout)?Effect\s*\(/;
+const DOM_STATE =
+ /\buseState\s*<[^>]*(?<![\w$.])(?:(?:HTML|SVG)\w*Element|Element|Node|NodeList|HTMLCollection)\b/;
+
+/**
+ * The body of the arrow function an Effect starts on line `index`, or null
+ * when the Effect takes a named function or an expression body.
+ */
+export function effectBody(lines, index) {
+ const source = lines.slice(index, index + 400).join('\n');
+ const start = source.search(EFFECT);
+ const arrow = source.indexOf('=>', start);
+ if (start === -1 || arrow === -1) return null;
+ const open = source.slice(arrow + 2).search(/\S/) + arrow + 2;
+ if (source[open] !== '{' || source.slice(start, arrow).includes(',')) {
+ return null;
+ }
+ let depth = 0;
+ for (let i = open; i < source.length; i += 1) {
+ if (source[i] === '{') depth += 1;
+ if (source[i] === '}') depth -= 1;
+ if (depth === 0) return source.slice(open + 1, i);
+ }
+ return null;
+}
+
+function isNote(text) {
+ const trimmed = text.trim();
+ return (
+ (COMMENT.test(trimmed) || trimmed.endsWith('*/')) &&
+ !DIRECTIVE.test(trimmed)
+ );
+}
+
+/** True when a comment sits just above the Effect or opens its body. */
+export function hasEffectNote(lines, index, body) {
+ for (let i = index - 1; i >= 0; i -= 1) {
+ const text = lines[i].trim();
+ if (text === '' || DIRECTIVE.test(text)) continue;
+ if (isNote(text)) return true;
+ break;
+ }
+ const first = (body ?? '').split('\n').find(text => text.trim() !== '');
+ return first != null && isNote(first);
+}
+
+/** True when every statement of the body assigns a ref's `current`. */
+export function copiesIntoRef(body) {
+ const statements = body
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/\/\/.*$/gm, '')
+ .split(/[;\n]/)
+ .map(text => text.trim())
+ .filter(Boolean);
+ return (
+ statements.length > 0 &&
+ statements.every(text => /^[\w$.]+\.current\s*=(?!=)/.test(text))
+ );
+}
+
+/** Item j. `readHead(file)` returns the file at the head, or null. */
+export function effectFindings(addedLines, readHead) {
+ const findings = [];
+ const sources = new Map();
+ const add = (file, line, rule, fix) =>
+ findings.push({item: 'j', file, line, rule, fix});
+ for (const {file, line, text} of addedLines) {
+ if (!file.startsWith('packages/') || COMMENT.test(text)) continue;
+ if (DOM_STATE.test(text)) {
+ add(
+ file,
+ line,
+ 'A DOM node is kept in React state',
+ `Own the node through a ref, or keep only the minimal key that render needs (${RUNTIME} INV1).`,
+ );
+ }
+ if (!EFFECT.test(text)) continue;
+ if (!sources.has(file)) sources.set(file, readHead(file)?.split('\n'));
+ const lines = sources.get(file);
+ if (lines == null) continue;
+ const body = effectBody(lines, line - 1);
+ if (body != null && copiesIntoRef(body)) {
+ add(
+ file,
+ line,
+ 'The Effect only copies a value into a ref',
+ `Read the value where it is used, or set the ref in the handler that changes it. An Effect syncs an external system (${RUNTIME} INV3).`,
+ );
+ } else if (!hasEffectNote(lines, line - 1, body)) {
+ add(
+ file,
+ line,
+ 'The new Effect has no note that names the system it syncs',
+ `Add a short comment above it that names the external system, or remove the Effect when no external system is involved (${RUNTIME} INV3).`,
+ );
+ }
+ }
+ return findings;
+}
+
+const NAMED_CATEGORIES = new Set(['fix', 'feat', 'perf']);
+
+/**
+ * Item k, Changesets. `coverage` is `checkCoverage` from
+ * `scripts/release/changeset-coverage.mjs`; `changesets` are the Changesets
+ * the change adds or edits, as `{file, text}`.
+ */
+export function changesetFindings({coverage, changesets}) {
+ const findings = [];
+ const shippedFiles = pkg =>
+ [...(coverage.required.get(pkg)?.values() ?? [])]
+ .flat()
+ .map(entry => entry.replace(/ \(.*\)$/, ''));
+ for (const pkg of [...coverage.required.keys()].sort()) {
+ if (coverage.covered.has(pkg)) continue;
+ findings.push({
+ item: 'k',
+ file: shippedFiles(pkg)[0],
+ line: null,
+ rule: `${pkg} ships a change, and no Changeset names it`,
+ fix: `Run \`pnpm changeset:new --packages ${pkg}\`. Use \`[chore] Internal:\` when a consumer sees no change.`,
+ });
+ }
+ for (const {file, text} of changesets) {
+ const frontmatter = parseFrontmatter(text);
+ if (!frontmatter) continue;
+ const {category} = parseEntry(frontmatter.summary);
+ if (!NAMED_CATEGORIES.has(category)) continue;
+ const line =
+ text.split('\n').findIndex(row => row.includes(`[${category}]`)) + 1 ||
+ null;
+ for (const [pkg, bump] of Object.entries(frontmatter.releases)) {
+ if (bump === 'none') continue;
+ if (shippedFiles(pkg).length > 0) continue;
+ findings.push({
+ item: 'k',
+ file,
+ line,
+ rule: `\`[${category}]\` names ${pkg}, but nothing ${pkg} ships changes`,
+ fix: 'Remove the Changeset. Tests, stories, fixtures, and tooling need none.',
+ });
+ }
+ }
+ return findings;
+}
+
+const GAP = /\b(implementation gap|gap until built)\b/i;
+const CLAIM_ID = /\b(?:FR|NFR|AR|VR|INV|DEC|DD)\d+\b/g;
+
+/**
+ * Item k, records. `records` are the paths of the records the change edits or
+ * that govern its files; `linkedRecords` are those that govern a changed
+ * package file. A gap is a finding when its own text names a file the change
+ * edits. An evidence gap ("gap until built") is also a finding when the change
+ * edits the record, edits a package file the record governs, and mentions a
+ * claim of the gap's row.
+ */
+export function recordGapFindings({
+ records,
+ changedFiles,
+ addedByFile,
+ linkedRecords,
+ readHead,
+}) {
+ const findings = [];
+ const changedNames = new Set(
+ [...changedFiles]
+ .filter(file => !records.includes(file))
+ .map(file => path.posix.basename(file)),
+ );
+ for (const record of records) {
+ const lines = readHead(record)?.split('\n') ?? [];
+ const editedClaims = new Set(
+ (addedByFile[record] ?? []).flatMap(text => text.match(CLAIM_ID) ?? []),
+ );
+ const builds = changedFiles.has(record) && linkedRecords.has(record);
+ lines.forEach((text, index) => {
+ const gap = GAP.exec(text);
+ if (gap == null) return;
+ const gapText = text.slice(gap.index).split('|')[0];
+ const named = [...gapText.matchAll(/`([^`\s]+\.\w+)`/g)]
+ .map(match => path.posix.basename(match[1]))
+ .find(name => changedNames.has(name));
+ const rowClaims =
+ (/^\s*\|([^|]*)\|/.exec(text)?.[1] ?? '').match(CLAIM_ID) ?? [];
+ const isEvidenceGap = /until built/i.test(gap[1]);
+ const claim =
+ builds && isEvidenceGap && rowClaims.find(id => editedClaims.has(id));
+ if (!named && !claim) return;
+ findings.push({
+ item: 'k',
+ file: record,
+ line: index + 1,
+ rule: named
+ ? `A gap row names \`${named}\`, which this change edits`
+ : `A gap row for ${claim} remains, and this change edits ${claim} and the code it governs`,
+ fix: 'When this change builds the claim, replace the gap with the evidence. Otherwise keep it.',
+ });
+ });
+ }
+ return findings;
+}
+
+const MAX_CONFLICTS = 10;
+
+/** Item l. `conflicts` lists the paths that do not merge cleanly. */
+export function mergeFindings(conflicts, base) {
+ const findings = conflicts.slice(0, MAX_CONFLICTS).map(file => ({
+ item: 'l',
+ file,
+ line: null,
+ rule: `Conflicts with ${base}`,
+ fix: `Merge or rebase onto ${base}, and resolve the conflict.`,
+ }));
+ if (conflicts.length > MAX_CONFLICTS) {
+ findings.push({
+ item: 'l',
+ file: null,
+ line: null,
+ rule: `${conflicts.length - MAX_CONFLICTS} more files conflict with ${base}`,
+ fix: `Merge or rebase onto ${base}, and resolve each conflict.`,
+ });
+ }
+ return findings;
+}
diff --git a/scripts/lib/pre-review-findings.test.mjs b/scripts/lib/pre-review-findings.test.mjs
new file mode 100644
index 0000000000..ba74beef4e
--- /dev/null
+++ b/scripts/lib/pre-review-findings.test.mjs
@@ -0,0 +1,418 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {
+ SHARED_OWNERS,
+ addsDocumentListener,
+ authoredLineCount,
+ changesetFindings,
+ effectFindings,
+ mergeFindings,
+ recordGapFindings,
+ sharedOwnerFindings,
+ sizeFindings,
+} from './pre-review-findings.mjs';
+import {readDiff} from './review-diff.mjs';
+
+const repoRoot = path.resolve(import.meta.dirname, '../..');
+
+/** A unified diff that adds `added` and removes `removed` lines in `file`. */
+function diffOf(file, added, removed = []) {
+ return [
+ `diff --git a/${file} b/${file}`,
+ `--- a/${file}`,
+ `+++ b/${file}`,
+ `@@ -1,${removed.length} +1,${added.length} @@`,
+ ...removed.map(line => `-${line}`),
+ ...added.map(line => `+${line}`),
+ ].join('\n');
+}
+
+const counted = diff => readDiff(diff).changedCountByFile;
+
+function addedLinesOf(file, lines) {
+ return readDiff(diffOf(file, lines)).addedLines;
+}
+
+const lines = count => Array.from({length: count}, (_, i) => `line ${i}`);
+
+describe('authoredLineCount', () => {
+ it('counts added and removed lines', () => {
+ expect(authoredLineCount(counted(diffOf('a.ts', lines(3), lines(2))))).toBe(
+ 5,
+ );
+ });
+
+ it('leaves out lockfiles, snapshots, and generated files', () => {
+ const diff = [
+ diffOf('pnpm-lock.yaml', lines(50)),
+ diffOf('packages/core/src/__snapshots__/A.test.tsx.snap', lines(40)),
+ diffOf('packages/core/api-report.md', lines(30)),
+ diffOf('packages/core/src/A/A.tsx', lines(7)),
+ ].join('\n');
+ expect(
+ authoredLineCount(counted(diff), file => file.endsWith('api-report.md')),
+ ).toBe(7);
+ });
+
+ it('counts a removed line that starts with dashes', () => {
+ expect(authoredLineCount(counted(diffOf('a.md', ['++ b'], ['-- a'])))).toBe(
+ 2,
+ );
+ });
+});
+
+describe('sizeFindings', () => {
+ it('passes at the limit', () => {
+ expect(sizeFindings(2000, null)).toEqual([]);
+ });
+
+ it('warns above the limit and asks for the description when it is not read', () => {
+ const [finding] = sizeFindings(2001, null);
+ expect(finding.item).toBe('h');
+ expect(finding.rule).toBe('2001 authored lines, over 2000');
+ expect(finding.fix).toContain('--body-file');
+ });
+
+ it('accepts a declared behavior module at any size', () => {
+ for (const body of [
+ 'Behavior module: the gesture host wheel module',
+ 'This behavior-module pull request adds the wheel module.',
+ ]) {
+ expect(sizeFindings(20000, body)).toEqual([]);
+ }
+ for (const body of [
+ "This isn't a behavior-module PR.",
+ 'This is not a behavior-module pull request.',
+ 'One fix.',
+ ]) {
+ expect(sizeFindings(5000, body)).toHaveLength(1);
+ }
+ });
+
+ it('raises the limit to 8,000 for a Batch row', () => {
+ const body = 'Batch: Slider · finger tracking';
+ expect(sizeFindings(8000, body)).toEqual([]);
+ const [finding] = sizeFindings(8001, body);
+ expect(finding.rule).toBe('8001 authored lines, over 8000 for a batch');
+ });
+
+ it('counts a stacked pull request, and names the base to count against', () => {
+ const [finding] = sizeFindings(5000, '- Stack: 2 of 3, above #123');
+ expect(finding.fix).toContain('pass --base the branch below it');
+ });
+});
+
+describe('sharedOwnerFindings', () => {
+ const file = 'packages/core/src/Slider/useThumb.ts';
+
+ it('flags each concern Core owns, with its owner', () => {
+ const findings = sharedOwnerFindings(
+ addedLinesOf(file, [
+ 'const observer = new ResizeObserver(measure);',
+ "doc?.addEventListener('selectstart', block, true);",
+ 'const Observer = node.ownerDocument.defaultView?.ResizeObserver;',
+ 'const warnedTriggers = new WeakSet<Element>();',
+ 'const host = (parent as ShadowRoot).host;',
+ ]),
+ );
+ expect(findings.map(f => [f.line, f.fix.split('`')[1]])).toEqual([
+ [1, 'observeResize'],
+ [2, 'subscribeInput'],
+ [3, 'observeResize'],
+ [4, 'useDevWarning'],
+ [5, 'parentAcrossShadow'],
+ ]);
+ expect(findings.every(f => f.item === 'i')).toBe(true);
+ });
+
+ it('skips element listeners, comments, owners, tests, and other packages', () => {
+ expect(
+ sharedOwnerFindings([
+ ...addedLinesOf(file, [
+ "element.addEventListener('pointerdown', onDown);",
+ '// A new ResizeObserver here would duplicate observeResize.',
+ 'const warned = useRef(false);',
+ 'const shadow = tree instanceof ShadowRoot ? tree : null;',
+ 'if (node.nodeType === 11) return host;',
+ ]),
+ ...addedLinesOf('packages/core/src/utils/sharedResizeObserver.ts', [
+ 'observer = new ResizeObserver(notify);',
+ ]),
+ ...addedLinesOf('packages/core/src/Slider/Slider.test.tsx', [
+ 'const observer = new ResizeObserver(measure);',
+ ]),
+ ...addedLinesOf('packages/lab/src/Thing/Thing.tsx', [
+ "window.addEventListener('resize', measure);",
+ ]),
+ ]),
+ ).toEqual([]);
+ });
+
+ it('reads a document or window receiver in its usual spellings', () => {
+ for (const text of [
+ "document.addEventListener('keydown', onKey);",
+ "node.ownerDocument.addEventListener('pointerup', onUp);",
+ "view?.addEventListener('blur', onBlur);",
+ "getWindow(node).addEventListener('scroll', onScroll);",
+ "(node.ownerDocument ?? document).addEventListener('click', onClick);",
+ ]) {
+ expect(addsDocumentListener(text)).toBe(true);
+ }
+ for (const text of [
+ "button.addEventListener('click', onClick);",
+ "window.visualViewport?.addEventListener('resize', onResize);",
+ ]) {
+ expect(addsDocumentListener(text)).toBe(false);
+ }
+ });
+
+ it('names owners that exist in Core', () => {
+ for (const {owner, path: ownerPath} of SHARED_OWNERS) {
+ const source = fs.readFileSync(path.join(repoRoot, ownerPath), 'utf8');
+ expect(source).toMatch(new RegExp(`export function ${owner}\\b`));
+ }
+ });
+});
+
+describe('effectFindings', () => {
+ const file = 'packages/core/src/Tooltip/useTooltip.ts';
+
+ function findingsFor(source) {
+ const sourceLines = source.split('\n');
+ return effectFindings(addedLinesOf(file, sourceLines), name =>
+ name === file ? source : null,
+ ).map(f => [f.line, f.rule]);
+ }
+
+ it('flags a new Effect with no note', () => {
+ expect(
+ findingsFor(
+ [
+ 'useEffect(() => {',
+ ' return subscribe(onChange);',
+ '}, [onChange]);',
+ ].join('\n'),
+ ),
+ ).toEqual([
+ [1, 'The new Effect has no note that names the system it syncs'],
+ ]);
+ });
+
+ it('accepts a note above the Effect or at the top of its body', () => {
+ expect(
+ findingsFor(
+ [
+ '// Syncs the open state to the browser popover.',
+ '// eslint-disable-next-line react-hooks/exhaustive-deps',
+ 'useLayoutEffect(() => {',
+ ' popover.togglePopover(isOpen);',
+ '}, [isOpen]);',
+ '',
+ 'useEffect(() => {',
+ ' // Subscribes to the document input stream.',
+ ' return subscribe(onChange);',
+ '}, [onChange]);',
+ ].join('\n'),
+ ),
+ ).toEqual([]);
+ });
+
+ it('flags an Effect that only copies a value into a ref', () => {
+ expect(
+ findingsFor(
+ [
+ '// Keeps the latest handler.',
+ 'useEffect(() => {',
+ ' onChangeRef.current = onChange;',
+ '});',
+ ].join('\n'),
+ ),
+ ).toEqual([[2, 'The Effect only copies a value into a ref']]);
+ expect(
+ findingsFor(
+ [
+ '// Keeps the getter current for gesture callbacks.',
+ 'useIsomorphicLayoutEffect(() => {',
+ ' getPartsRef.current = getParts;',
+ '});',
+ ].join('\n'),
+ ),
+ ).toEqual([[2, 'The Effect only copies a value into a ref']]);
+ expect(
+ findingsFor(
+ [
+ '// Syncs the handler to the native listener.',
+ 'useEffect(() => {',
+ ' onChangeRef.current = onChange;',
+ " node.addEventListener('input', onInput);",
+ '}, [onChange]);',
+ ].join('\n'),
+ ),
+ ).toEqual([]);
+ });
+
+ it('flags a DOM node in state, but not a React element', () => {
+ expect(
+ findingsFor(
+ [
+ 'const [trigger, setTrigger] = useState<HTMLElement | null>(null);',
+ 'const [icon, setIcon] = useState<ReactElement | null>(null);',
+ 'const [view, setView] = useState<JSX.Element>(fallback);',
+ ].join('\n'),
+ ),
+ ).toEqual([[1, 'A DOM node is kept in React state']]);
+ });
+});
+
+describe('changesetFindings', () => {
+ const core = '@astryxdesign/core';
+ const changeset = category => ({
+ file: '.changeset/a.md',
+ text: `---\n'${core}': patch\n---\n\n[${category}] A sentence.\n\n@someone\n`,
+ });
+
+ function findingsFor({shipped, changesets = [], covered = []}) {
+ return changesetFindings({
+ coverage: {
+ required: shipped.length
+ ? new Map([[core, new Map([['source', shipped]])]])
+ : new Map(),
+ covered: new Set(covered),
+ },
+ changesets,
+ }).map(f => [f.item, f.file, f.line, f.rule]);
+ }
+
+ it('flags a package that ships a change with no Changeset', () => {
+ expect(
+ findingsFor({shipped: ['packages/core/src/Button/Button.tsx']}),
+ ).toEqual([
+ [
+ 'k',
+ 'packages/core/src/Button/Button.tsx',
+ null,
+ `${core} ships a change, and no Changeset names it`,
+ ],
+ ]);
+ });
+
+ it('flags a [fix] when nothing the package ships changes', () => {
+ expect(findingsFor({shipped: [], changesets: [changeset('fix')]})).toEqual([
+ [
+ 'k',
+ '.changeset/a.md',
+ 5,
+ `\`[fix]\` names ${core}, but nothing ${core} ships changes`,
+ ],
+ ]);
+ });
+
+ it('accepts a covered change, and a [chore] with nothing shipped', () => {
+ expect(
+ findingsFor({
+ shipped: ['packages/core/src/utils/hold.ts'],
+ changesets: [changeset('fix')],
+ covered: [core],
+ }),
+ ).toEqual([]);
+ expect(
+ findingsFor({shipped: [], changesets: [changeset('chore')]}),
+ ).toEqual([]);
+ });
+});
+
+describe('recordGapFindings', () => {
+ const record = 'docs/specs/components/HoverCard/HoverCard.spec.md';
+ const text = [
+ '| FR9 | A press pins the card. | DEC-2 |',
+ '| FR9, AR3 | Evidence gap until built: a press suite in `HoverCard.test.tsx` | Click |',
+ '| FR12 | Evidence gap until built: a second-press case | Click |',
+ '| FR14 | Holds. Implementation gap: `useHold.ts` keeps the old timer. | DEC-4 |',
+ '| FR5 | `Tooltip.test.tsx` touch suite, with tap cases an evidence gap until built | Tap |',
+ '| FR15 | Implementation gap: not shipped yet (Current-state impact). | DEC-5 |',
+ ].join('\n');
+ const readHead = file => (file === record ? text : null);
+
+ function findingsFor({changed, added = [], linked = []}) {
+ return recordGapFindings({
+ records: [record],
+ changedFiles: new Set(changed),
+ addedByFile: {[record]: added},
+ linkedRecords: new Set(linked),
+ readHead,
+ }).map(f => [f.line, f.rule]);
+ }
+
+ it('flags a gap whose own text names a file the change edits', () => {
+ expect(
+ findingsFor({
+ changed: [
+ 'packages/core/src/HoverCard/HoverCard.test.tsx',
+ 'packages/core/src/HoverCard/useHold.ts',
+ 'packages/core/src/Tooltip/Tooltip.test.tsx',
+ ],
+ }),
+ ).toEqual([
+ [2, 'A gap row names `HoverCard.test.tsx`, which this change edits'],
+ [4, 'A gap row names `useHold.ts`, which this change edits'],
+ ]);
+ });
+
+ it('flags a gap row for a claim the change edits with its code', () => {
+ expect(
+ findingsFor({
+ changed: [record, 'packages/core/src/HoverCard/HoverCard.tsx'],
+ added: ['| FR12 | The card closes on a second press. | DEC-4 |'],
+ linked: [record],
+ }),
+ ).toEqual([
+ [
+ 3,
+ 'A gap row for FR12 remains, and this change edits FR12 and the code it governs',
+ ],
+ ]);
+ });
+
+ it('leaves a gap alone in a record-only change, and an implementation gap for an edited claim', () => {
+ expect(
+ findingsFor({
+ changed: [record],
+ added: [
+ '| FR12 | Evidence gap until built: a second-press case | Click |',
+ ],
+ }),
+ ).toEqual([]);
+ expect(
+ findingsFor({
+ changed: [record, 'packages/core/src/HoverCard/HoverCard.tsx'],
+ added: ['| FR15 | Implementation gap: not shipped yet. | DEC-5 |'],
+ linked: [record],
+ }),
+ ).toEqual([]);
+ });
+});
+
+describe('mergeFindings', () => {
+ it('lists ten conflicts, then a count of the rest', () => {
+ const files = Array.from({length: 12}, (_, i) => `f${i}.ts`);
+ const findings = mergeFindings(files, 'origin/main');
+ expect(findings).toHaveLength(11);
+ expect(findings.at(-1).rule).toBe('2 more files conflict with origin/main');
+ });
+
+ it('names each conflicting path', () => {
+ expect(mergeFindings(['a.ts'], 'origin/main')).toEqual([
+ {
+ item: 'l',
+ file: 'a.ts',
+ line: null,
+ rule: 'Conflicts with origin/main',
+ fix: 'Merge or rebase onto origin/main, and resolve the conflict.',
+ },
+ ]);
+ expect(mergeFindings([], 'origin/main')).toEqual([]);
+ });
+});
diff --git a/scripts/lib/review-diff.mjs b/scripts/lib/review-diff.mjs
index e2e8862e7b..d0d548d599 100644
--- a/scripts/lib/review-diff.mjs
+++ b/scripts/lib/review-diff.mjs
@@ -4,7 +4,8 @@
* @file Read the shipped source lines a change adds.
* @input A unified diff (`git diff` output).
* @output Each added line of shipped source with its file and new line number,
- * every changed path, and every added line of each path.
+ * every changed path, every added line of each path, and the count of added
+ * and removed lines of each path.
* @position Shared by `pnpm specs:for --diff` and
* `scripts/review-global-baselines.mjs`, which match these lines against the
* `concerns` the owning records declare (`architecture:knowledge-contracts/INV20`).
@@ -26,38 +27,48 @@ export function isShippedSource(file) {
/**
* Parse a unified diff into its changed paths and added lines. `addedLines`
- * keeps shipped source only; `addedByFile` keeps every added line of each path.
+ * keeps shipped source only; `addedByFile` keeps every added line of each path;
+ * `changedCountByFile` counts the added and removed lines of each path.
*/
export function readDiff(diffText) {
const files = [];
const addedLines = [];
const addedByFile = {};
+ const changedCountByFile = {};
let file = null;
let newLine = 0;
+ let inHunk = false;
for (const line of diffText.split('\n')) {
const header = /^diff --git a\/\S+ b\/(\S+)/.exec(line);
if (header) {
file = header[1];
files.push(file);
addedByFile[file] ??= [];
+ changedCountByFile[file] ??= 0;
+ inHunk = false;
continue;
}
- if (line.startsWith('+++ ') || line.startsWith('--- ')) continue;
const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
if (hunk) {
newLine = Number(hunk[1]);
+ inHunk = file != null;
continue;
}
- if (file == null) continue;
+ // Before the first hunk, `---` and `+++` lines are file headers. Inside a
+ // hunk, they are content.
+ if (!inHunk) continue;
if (line.startsWith('+')) {
addedByFile[file].push(line.slice(1));
+ changedCountByFile[file] += 1;
if (isShippedSource(file)) {
addedLines.push({file, line: newLine, text: line.slice(1)});
}
newLine += 1;
+ } else if (line.startsWith('-')) {
+ changedCountByFile[file] += 1;
} else if (line.startsWith(' ')) {
newLine += 1;
}
}
- return {files, addedLines, addedByFile};
+ return {files, addedLines, addedByFile, changedCountByFile};
}
diff --git a/scripts/lib/review-diff.test.mjs b/scripts/lib/review-diff.test.mjs
index 4d3125a989..a31200908d 100644
--- a/scripts/lib/review-diff.test.mjs
+++ b/scripts/lib/review-diff.test.mjs
@@ -25,6 +25,21 @@ const routed = name =>
);
describe('readDiff', () => {
+ it('reads a hunk line that starts with --- or +++ as content, and counts changed lines', () => {
+ const diff = [
+ 'diff --git a/docs/a.md b/docs/a.md',
+ '--- a/docs/a.md',
+ '+++ b/docs/a.md',
+ '@@ -1,2 +1,2 @@',
+ '---- a rule',
+ '+++ a heading',
+ ' context',
+ ].join('\n');
+ const {addedByFile, changedCountByFile} = readDiff(diff);
+ expect(addedByFile).toEqual({'docs/a.md': ['++ a heading']});
+ expect(changedCountByFile).toEqual({'docs/a.md': 2});
+ });
+
it('keeps every added line of each path in addedByFile', () => {
const diff = [
'diff --git a/docs/a.md b/docs/a.md',
diff --git a/scripts/pre-review.mjs b/scripts/pre-review.mjs
index 54d977bff9..84ea9bbfeb 100644
--- a/scripts/pre-review.mjs
+++ b/scripts/pre-review.mjs
@@ -4,9 +4,11 @@
/**
* @file Pre-review report: what a reviewer checks in a change, before review.
* @input `--base <ref>` (default `origin/main`), an optional `--head <ref>`
- * (default: the working tree, with uncommitted and untracked files), `--json`.
+ * (default: the working tree, with uncommitted and untracked files), `--json`,
+ * and the description through `--body-file <path>` or `--pr <number>`.
* @output The changed files and their class, the governing records and routed
- * claims, and the checklist items that apply to this change.
+ * claims, the findings at a file and line, and the checklist items that
+ * apply to this change.
* @position `pnpm review:pre`. The checklist it names is in
* `docs/contributing/pull-requests.md`. SYNC: keep `CHECKS` in step with it.
*/
@@ -14,9 +16,25 @@
import {execFileSync} from 'node:child_process';
import fs from 'node:fs';
import {createRequire} from 'node:module';
+import os from 'node:os';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
+import {
+ SIZE_LIMIT,
+ authoredLineCount,
+ changesetFindings,
+ effectFindings,
+ mergeFindings,
+ recordGapFindings,
+ sharedOwnerFindings,
+ sizeFindings,
+} from './lib/pre-review-findings.mjs';
import {isShippedSource, readDiff} from './lib/review-diff.mjs';
+import {
+ changedChangesets,
+ checkCoverage,
+ gitTree,
+} from './release/changeset-coverage.mjs';
import {
diffText,
loadKnowledgeIndex,
@@ -43,6 +61,11 @@ export const CHECKS = {
e: 'New public hook: a runnable example in a template block that names the hook in exampleFor or alsoExampleFor',
f: 'Comments: new or changed source comments explain only non-obvious work, in Simplified Technical English',
g: 'Records: a changed record needs a spec owner to approve its spec content',
+ h: `Size: at most ${SIZE_LIMIT.toLocaleString('en-US')} authored lines, unless the description declares a behavior-module pull request or a batch row`,
+ i: 'Shared owners: a concern Core owns in a shared module is called through that module',
+ j: 'Effects: a new Effect names the system it syncs and does more than copy into a ref; no DOM node in state',
+ k: 'Release notes and records: a Changeset names each package that ships a change, its category fits, and no gap row stays for a claim the change builds',
+ l: 'Mergeable: the change merges into the base without conflicts',
};
const API_REPORT = /(?:^|\/)api-report\.md$/;
@@ -153,6 +176,101 @@ function git(args) {
});
}
+/** The working tree, read through the same interface as `gitTree`. */
+function workingTree() {
+ return {
+ label: 'working tree',
+ read(file) {
+ try {
+ return fs.readFileSync(path.join(ROOT, file), 'utf8');
+ } catch {
+ return null;
+ }
+ },
+ };
+}
+
+/** Paths `.gitattributes` at `source` marks `linguist-generated`. */
+function generatedPaths(files, source) {
+ const output = execFileSync(
+ 'git',
+ [
+ '-C',
+ ROOT,
+ 'check-attr',
+ ...(source ? [`--source=${source}`] : []),
+ '--stdin',
+ 'linguist-generated',
+ ],
+ {encoding: 'utf8', input: files.join('\n') + '\n'},
+ );
+ const generated = new Set();
+ for (const line of output.split('\n')) {
+ const match = /^(.*): linguist-generated: (\S+)$/.exec(line);
+ if (match && match[2] !== 'unspecified' && match[2] !== 'unset') {
+ generated.add(match[1]);
+ }
+ }
+ return generated;
+}
+
+/**
+ * The paths that conflict when `head` merges into `base`, or `{error}`. The
+ * merge writes its objects to a temporary store, so the repository is not
+ * changed.
+ */
+export function mergeConflicts(base, head, root = ROOT) {
+ const store = fs.mkdtempSync(path.join(os.tmpdir(), 'review-pre-merge-'));
+ const objects = execFileSync(
+ 'git',
+ [
+ '-C',
+ root,
+ 'rev-parse',
+ '--path-format=absolute',
+ '--git-path',
+ 'objects',
+ ],
+ {encoding: 'utf8'},
+ ).trim();
+ try {
+ execFileSync(
+ 'git',
+ [
+ '-C',
+ root,
+ 'merge-tree',
+ '--write-tree',
+ '--name-only',
+ '--no-messages',
+ base,
+ head,
+ ],
+ {
+ encoding: 'utf8',
+ stdio: 'pipe',
+ env: {
+ ...process.env,
+ GIT_OBJECT_DIRECTORY: store,
+ GIT_ALTERNATE_OBJECT_DIRECTORIES: objects,
+ },
+ },
+ );
+ return {conflicts: []};
+ } catch (error) {
+ if (error.status === 1) {
+ return {conflicts: error.stdout.split('\n').slice(1).filter(Boolean)};
+ }
+ return {
+ error: String(error.stderr || error.message)
+ .trim()
+ .split('\n')[0],
+ };
+ } finally {
+ fs.rmSync(store, {recursive: true, force: true});
+ }
+}
+
function changedFiles(fork, head) {
const tracked = parseNameStatus(
git(['diff', '--name-status', '-M', fork, ...(head ? [head] : [])]),
@@ -194,7 +312,24 @@ function globalBaselines(fork, headSha, triggers) {
return {command, claims: [...new Set(claims)].sort()};
}
-export function buildReport({base = 'origin/main', head = null} = {}) {
+/** Each checklist item that has findings, with its count. */
+export function findingChecks(findings) {
+ const counts = new Map();
+ for (const {item} of findings) counts.set(item, (counts.get(item) ?? 0) + 1);
+ return [...counts]
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([id, count]) => ({
+ id,
+ check: CHECKS[id],
+ reason: `${count} finding${count === 1 ? '' : 's'} above`,
+ }));
+}
+
+export function buildReport({
+ base = 'origin/main',
+ head = null,
+ body = null,
+} = {}) {
const fork = git(['merge-base', base, head ?? 'HEAD']).trim();
const headSha = git(['rev-parse', head ?? 'HEAD']).trim();
const changes = changedFiles(fork, head);
@@ -203,15 +338,21 @@ export function buildReport({base = 'origin/main', head = null} = {}) {
const diff = diffText(ROOT, head ? `${base}...${head}` : base);
const classes = classifyPaths(files);
const index = loadKnowledgeIndex(ROOT);
- const {addedLines} = readDiff(diff);
+ const {addedLines, addedByFile, changedCountByFile} = readDiff(diff);
const records = new Map();
+ const linkedRecords = new Set();
const claims = new Set();
const triggers = new Set();
for (const file of files) {
const result = resolveSpecsForFile(index, path.join(ROOT, file), {
addedLines,
});
- for (const record of result.records) records.set(record.id, record.path);
+ for (const record of result.records) {
+ records.set(record.id, record.path);
+ if (file.startsWith('packages/') && !classes[file].specRecord) {
+ linkedRecords.add(record.path);
+ }
+ }
for (const decision of result.decisions) claims.add(decision.id);
for (const match of result.concernClaims)
claims.add(`${match.recordId} ${match.claimId}`);
@@ -219,16 +360,57 @@ export function buildReport({base = 'origin/main', head = null} = {}) {
for (const trigger of result.triggers) triggers.add(trigger);
}
}
+ const headTree = head ? gitTree(ROOT, headSha) : workingTree();
+ const readHead = file => headTree.read(file);
+ const present = new Set(
+ changes
+ .filter(change => change.status?.[0] !== 'D')
+ .map(change => change.filename),
+ );
+ const generated = generatedPaths(files, head ? headSha : null);
+ const authoredLines = authoredLineCount(changedCountByFile, file =>
+ generated.has(file),
+ );
+ const merge = mergeConflicts(base, head ?? 'HEAD');
+ const coverage = checkCoverage({
+ changes,
+ base: gitTree(ROOT, fork),
+ head: headTree,
+ });
+ const changesets = changedChangesets(changes, headTree);
+ const recordPaths = [
+ ...new Set([
+ ...records.values(),
+ ...files.filter(file => classes[file].specRecord && present.has(file)),
+ ]),
+ ];
+ const findings = [
+ ...sizeFindings(authoredLines, body),
+ ...sharedOwnerFindings(addedLines),
+ ...effectFindings(addedLines, readHead),
+ ...changesetFindings({coverage, changesets}),
+ ...recordGapFindings({
+ records: recordPaths,
+ changedFiles: present,
+ addedByFile,
+ linkedRecords,
+ readHead,
+ }),
+ ...mergeFindings(merge.conflicts ?? [], base),
+ ];
return {
base,
head: head ?? 'working tree',
mergeBase: fork,
scope: classifyChanges(changes).reason,
+ authoredLines,
+ merge,
+ findings,
files: files.map(file => ({file, class: fileClass(file, classes[file])})),
records: [...records].map(([id, recordPath]) => ({id, path: recordPath})),
claims: [...claims].sort(),
baselines: globalBaselines(fork, headSha, [...triggers].sort()),
- checks: applicableChecks(files, diff),
+ checks: [...applicableChecks(files, diff), ...findingChecks(findings)],
checklist: CHECKLIST_LINK,
};
}
@@ -266,6 +448,16 @@ export function formatReport(report) {
' none: no linked component or module record declares review triggers',
]),
'',
+ `Authored lines: ${report.authoredLines} (limit ${SIZE_LIMIT}; lockfiles, snapshots, and generated files excluded)`,
+ report.merge.error
+ ? `Merge into ${report.base}: not checked: ${report.merge.error}`
+ : `Merge into ${report.base}: ${report.merge.conflicts.length ? `${report.merge.conflicts.length} conflicting files` : 'clean'}`,
+ '',
+ `Findings in this change (${report.findings.length}):`,
+ ...(report.findings.length
+ ? report.findings.map(formatFinding)
+ : [' none']),
+ '',
'Checklist items that apply:',
...report.checks.map(
item => ` [${item.id}] ${item.check}\n because ${item.reason}`,
@@ -276,6 +468,35 @@ export function formatReport(report) {
return lines.join('\n');
}
+export function formatFinding({item, file, line, rule, fix}) {
+ const where = file ? `${file}${line ? `:${line}` : ''} ` : '';
+ return ` [${item}] ${where}${rule}\n fix: ${fix}`;
+}
+
+/** The pull request description from `--body-file`, or from `gh` for `--pr`. */
+function readBody(argv) {
+ const file = valueFor(argv, '--body-file');
+ if (file) return fs.readFileSync(file, 'utf8');
+ const pr = valueFor(argv, '--pr');
+ if (!pr) return null;
+ try {
+ return execFileSync(
+ 'gh',
+ ['pr', 'view', pr, '--json', 'body', '-q', '.body'],
+ {
+ cwd: ROOT,
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ },
+ );
+ } catch {
+ console.error(
+ `Could not read pull request ${pr} with gh; size declarations not checked.`,
+ );
+ return null;
+ }
+}
+
function valueFor(argv, flag) {
const index = argv.indexOf(flag);
if (index === -1) return null;
@@ -290,6 +511,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
const report = buildReport({
base: valueFor(argv, '--base') ?? 'origin/main',
head: valueFor(argv, '--head'),
+ body: readBody(argv),
});
console.log(
argv.includes('--json')
diff --git a/scripts/pre-review.test.mjs b/scripts/pre-review.test.mjs
index a44f2e7916..bd697de77b 100644
--- a/scripts/pre-review.test.mjs
+++ b/scripts/pre-review.test.mjs
@@ -1,13 +1,17 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {execFileSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
import path from 'node:path';
import {describe, expect, it} from 'vitest';
import {
CHECKS,
applicableChecks,
fileClass,
+ findingChecks,
formatReport,
+ mergeConflicts,
} from './pre-review.mjs';
const repoRoot = path.resolve(import.meta.dirname, '..');
@@ -139,7 +143,10 @@ describe('applicableChecks', () => {
});
it('gives every item a checklist entry', () => {
- expect(Object.keys(CHECKS)).toEqual(['a', 'b', 'c', 'd', 'e', 'f', 'g']);
+ expect(Object.keys(CHECKS)).toEqual([
+ ...['a', 'b', 'c', 'd', 'e', 'f', 'g'],
+ ...['h', 'i', 'j', 'k', 'l'],
+ ]);
});
});
@@ -161,7 +168,25 @@ describe('fileClass', () => {
});
});
+describe('findingChecks', () => {
+ it('lists each item that has findings once, with its count', () => {
+ expect(
+ findingChecks([{item: 'j'}, {item: 'i'}, {item: 'j'}]).map(
+ item => `${item.id}: ${item.reason}`,
+ ),
+ ).toEqual(['i: 1 finding above', 'j: 2 findings above']);
+ });
+});
+
describe('formatReport', () => {
+ const finding = {
+ item: 'i',
+ file: 'packages/core/src/A/A.tsx',
+ line: 12,
+ rule: 'A new ResizeObserver; Core owns this concern',
+ fix: 'Call `observeResize`.',
+ };
+
it('lists the applicable items and the checklist link', () => {
const text = formatReport({
base: 'origin/main',
@@ -174,11 +199,19 @@ describe('formatReport', () => {
records: [{id: 'component:A', path: 'docs/specs/components/A/A.spec.md'}],
claims: [],
baselines: {command: null, claims: []},
+ authoredLines: 12,
+ merge: {conflicts: []},
+ findings: [finding],
checks: [
{id: 'd', check: CHECKS.d, reason: 'every pull request is public'},
],
checklist: 'docs/contributing/pull-requests.md#pre-review-checklist',
});
+ expect(text).toContain('Authored lines: 12 (limit 2000;');
+ expect(text).toContain('Merge into origin/main: clean');
+ expect(text).toContain(
+ ' [i] packages/core/src/A/A.tsx:12 A new ResizeObserver; Core owns this concern\n fix: Call `observeResize`.',
+ );
expect(text).toContain('component:A docs/specs/components/A/A.spec.md');
expect(text).toContain('[d] ');
expect(text).toContain(
@@ -187,6 +220,44 @@ describe('formatReport', () => {
});
});
+describe('mergeConflicts', () => {
+ function repoWithBranches(theirs) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'review-pre-test-'));
+ const git = (...args) =>
+ execFileSync('git', ['-C', root, ...args], {encoding: 'utf8'});
+ git('init', '-q', '-b', 'main');
+ git('config', 'user.email', '[email protected]');
+ git('config', 'user.name', 'Test');
+ fs.writeFileSync(path.join(root, 'a.txt'), 'one\n');
+ git('add', '.');
+ git('commit', '-qm', 'base');
+ git('checkout', '-qb', 'topic');
+ fs.writeFileSync(path.join(root, 'a.txt'), 'topic\n');
+ git('commit', '-qam', 'topic');
+ git('checkout', '-q', 'main');
+ fs.writeFileSync(path.join(root, theirs.file), theirs.text);
+ git('add', '.');
+ git('commit', '-qm', 'main');
+ return {root, git};
+ }
+
+ it('names the conflicting paths and writes no objects', () => {
+ const {root, git} = repoWithBranches({file: 'a.txt', text: 'main\n'});
+ const before = git('count-objects', '-v');
+ expect(mergeConflicts('main', 'topic', root)).toEqual({
+ conflicts: ['a.txt'],
+ });
+ expect(git('count-objects', '-v')).toBe(before);
+ fs.rmSync(root, {recursive: true, force: true});
+ });
+
+ it('reports a clean merge', () => {
+ const {root} = repoWithBranches({file: 'b.txt', text: 'other\n'});
+ expect(mergeConflicts('main', 'topic', root)).toEqual({conflicts: []});
+ fs.rmSync(root, {recursive: true, force: true});
+ });
+});
+
describe('pnpm review:pre', () => {
it('reports no changes for an empty range', () => {
const output = execFileSync(
diff --git a/scripts/release/changeset-coverage.mjs b/scripts/release/changeset-coverage.mjs
index f33a643bd3..f4cc0d018a 100644
--- a/scripts/release/changeset-coverage.mjs
+++ b/scripts/release/changeset-coverage.mjs
@@ -364,7 +364,7 @@ function namedPackages(changesets) {
}
/** The Changesets a change adds or edits, read from its head. */
-function changedChangesets(changes, head) {
+export function changedChangesets(changes, head) {
return changes
.filter(
change =>