Skip to content

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

TypeScript

ci(spec-owner): match spec content by blob before reading it (#9266)

Cindy Zhang9d2de2d003e7
diff --git a/.github/scripts/spec-owner-reconcile.cjs b/.github/scripts/spec-owner-reconcile.cjs
index 47cc437dde..54196acaa1 100644
--- a/.github/scripts/spec-owner-reconcile.cjs
+++ b/.github/scripts/spec-owner-reconcile.cjs
@@ -747,6 +747,37 @@ async function reconcileSpecOwnerGate({
),
].sort();
const textCache = new Map();
+ // The snapshot already read every changed Markdown record at the head; the
+ // same text is the spec content there, so the fingerprint reuses it. A
+ // renamed record's old path is absent at the head.
+ // Only a rename leaves its old path absent at the head: a copy's source
+ // stays, and a path another change re-adds is present.
+ const presentAtHead = new Set(
+ snapshot.files
+ .filter(file => file.status !== 'removed')
+ .map(file => file.filename),
+ );
+ const renamedAway = new Set(
+ snapshot.files
+ .filter(file => file.status === 'renamed' && file.previous_filename)
+ .map(file => file.previous_filename),
+ );
+ for (const record of records) {
+ if (!record.path.endsWith('.md') || record.headContent == null) continue;
+ textCache.set(
+ `${initialHead.toLowerCase()}\0${record.path}`,
+ Promise.resolve(record.headContent),
+ );
+ if (
+ renamedAway.has(record.previousPath) &&
+ !presentAtHead.has(record.previousPath)
+ ) {
+ textCache.set(
+ `${initialHead.toLowerCase()}\0${record.previousPath}`,
+ Promise.resolve(null),
+ );
+ }
+ }
function specText(sha, filePath) {
const key = `${sha.toLowerCase()}\0${filePath}`;
if (!textCache.has(key)) {
@@ -766,30 +797,68 @@ async function reconcileSpecOwnerGate({
);
return fingerprintSpecContent(entries);
}
+ // Each changed spec path's git blob at a commit, from a file list GitHub
+ // already returned: 'absent' for a removed file or a renamed file's old
+ // path. Equal blobs are equal bytes, so such a path's normalized text needs
+ // no read; a path the list does not name stays unknown and is read.
+ function specBlobs(changedFiles) {
+ const blobs = new Map();
+ // Only a rename leaves its old path absent; a copy's source stays and is
+ // unknown here. A path one change renames away and another re-adds is
+ // present: the file's own entry decides, so old paths are marked first.
+ // A path with no blob of its own stays unknown.
+ for (const file of changedFiles) {
+ if (
+ file.status === 'renamed' &&
+ file.previous_filename &&
+ isSpecPath(file.previous_filename)
+ ) {
+ blobs.set(file.previous_filename, 'absent');
+ }
+ }
+ for (const file of changedFiles) {
+ if (!isSpecPath(file.filename)) continue;
+ if (file.status === 'removed') blobs.set(file.filename, 'absent');
+ else if (file.sha) blobs.set(file.filename, file.sha);
+ else blobs.delete(file.filename);
+ }
+ return blobs;
+ }
+ const headBlobs = specBlobs(snapshot.files);
// An approved commit's spec paths join the head's, so dropping an approved
// change no longer matches. A failed comparison matches nothing.
- async function specPathsAt(sha) {
+ async function specChangesAt(sha) {
const {data} = await github.rest.repos.compareCommitsWithBasehead({
owner,
repo,
basehead: `${pr.base.sha}...${sha}`,
});
- return (data.files ?? []).flatMap(file =>
- [file.filename, file.previous_filename].filter(
- filePath => filePath && isSpecPath(filePath),
+ const changedFiles = data.files ?? [];
+ return {
+ paths: changedFiles.flatMap(file =>
+ [file.filename, file.previous_filename].filter(
+ filePath => filePath && isSpecPath(filePath),
+ ),
),
- );
+ blobs: specBlobs(changedFiles),
+ };
}
async function hasCurrentContent(sha) {
try {
- const paths = [
- ...new Set([...specPaths, ...(await specPathsAt(sha))]),
- ].sort();
- const [atHead, atSha] = await Promise.all([
- fingerprintAt(initialHead, paths),
- fingerprintAt(sha, paths),
+ const atSha = await specChangesAt(sha);
+ const paths = [...new Set([...specPaths, ...atSha.paths])].sort();
+ // The fingerprints match exactly when every path's normalized text
+ // does, so only paths without a shared blob are read and compared.
+ const unsettled = paths.filter(filePath => {
+ const headBlob = headBlobs.get(filePath);
+ return headBlob === undefined || headBlob !== atSha.blobs.get(filePath);
+ });
+ if (unsettled.length === 0) return true;
+ const [atHead, atShaContent] = await Promise.all([
+ fingerprintAt(initialHead, unsettled),
+ fingerprintAt(sha, unsettled),
]);
- return atHead.fingerprint === atSha.fingerprint;
+ return atHead.fingerprint === atShaContent.fingerprint;
} catch (error) {
core.warning(`Could not compare ${sha.slice(0, 7)}: ${error.message}`);
return false;
diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjs
index 9b5d02e35d..ee1bfa63a0 100644
--- a/.github/scripts/spec-owner-reconcile.test.mjs
+++ b/.github/scripts/spec-owner-reconcile.test.mjs
@@ -241,19 +241,21 @@ function createHarness({
state.calls.push(`status:${input.context}:${input.state}`);
return {data: status};
},
- getContent: async ({ref, path: filePath}) => ({
- data: {
- content: Buffer.from(
- `${ref}:${filePath}` in contentAt
- ? contentAt[`${ref}:${filePath}`]
- : ref in contentAt
- ? contentAt[ref]
- : ref === state.pr.head.sha
- ? headContent
- : baseContent,
- ).toString('base64'),
- },
- }),
+ getContent: async ({ref, path: filePath}) => {
+ const text =
+ `${ref}:${filePath}` in contentAt
+ ? contentAt[`${ref}:${filePath}`]
+ : ref in contentAt
+ ? contentAt[ref]
+ : ref === state.pr.head.sha
+ ? headContent
+ : baseContent;
+ // null: the path is absent at that commit.
+ if (text === null) {
+ throw Object.assign(new Error('Not Found'), {status: 404});
+ }
+ return {data: {content: Buffer.from(text).toString('base64')}};
+ },
},
},
graphql: async query => {
@@ -1380,6 +1382,166 @@ describe('spec owner workflow reconciliation', () => {
});
});
+ describe('a large spec move', () => {
+ // Every component record moved, unchanged, from packages to docs.
+ const moved = Array.from({length: 300}, (_, i) => ({
+ filename: `docs/specs/components/C${i}/C${i}.spec.md`,
+ previous_filename: `packages/core/src/C${i}/C${i}.spec.md`,
+ status: 'renamed',
+ changes: 0,
+ sha: `blob-${i}`,
+ }));
+
+ function countContentReads(harness) {
+ const counter = {reads: 0};
+ const getContent = harness.github.rest.repos.getContent;
+ harness.github.rest.repos.getContent = async input => {
+ counter.reads += 1;
+ return getContent(input);
+ };
+ return counter;
+ }
+
+ it('keeps an approval without re-reading files whose blobs match', async () => {
+ const harness = createHarness({
+ changedFiles: moved,
+ headContent: currentRecord,
+ baseContent: currentRecord,
+ contentAt: {[oldHead]: currentRecord},
+ filesAt: {[oldHead]: moved},
+ comments: [ownerComment(`/approve-spec ${oldHead}`)],
+ });
+ const counter = countContentReads(harness);
+
+ await run(harness, context({runId: 100n}));
+
+ expect(latestReviewGate(harness.state).state).toBe('success');
+ // The snapshot's base and head text for each moved record, and
+ // nothing more: the fingerprint reuses the head text, and the
+ // approved commit's identical blobs need no read (was 1,800).
+ expect(counter.reads).toBe(600);
+ });
+
+ it('reads and normalizes only a path whose blob differs', async () => {
+ const target = moved[7];
+ const harness = createHarness({
+ changedFiles: moved,
+ headContent: currentRecord,
+ baseContent: currentRecord,
+ // A bookkeeping-only edit: normalization drops it, so the approval
+ // still counts.
+ contentAt: {
+ [`${oldHead}:${target.filename}`]: currentRecord.replace(
+ 'approved_at: 2026-10-28',
+ 'approved_at: 2026-10-27',
+ ),
+ },
+ filesAt: {
+ [oldHead]: moved.map(file =>
+ file === target ? {...file, sha: 'blob-earlier'} : file,
+ ),
+ },
+ comments: [ownerComment(`/approve-spec ${oldHead}`)],
+ });
+ const counter = countContentReads(harness);
+
+ await run(harness, context({runId: 100n}));
+
+ expect(latestReviewGate(harness.state).state).toBe('success');
+ expect(counter.reads).toBe(601);
+ });
+
+ it('resets when the head copies a record the approval renamed', async () => {
+ // The approved commit moved docs/specs/x to docs/specs/y; the head
+ // copies it instead, so docs/specs/x is still there.
+ const x = 'docs/specs/x/spec.md';
+ const moveOrCopy = status => [
+ {
+ filename: 'docs/specs/y/spec.md',
+ previous_filename: x,
+ status,
+ changes: 0,
+ sha: 'blob-y',
+ },
+ ];
+ const harness = createHarness({
+ changedFiles: moveOrCopy('copied'),
+ headContent: currentRecord,
+ baseContent: currentRecord,
+ contentAt: {[`${oldHead}:${x}`]: null},
+ filesAt: {[oldHead]: moveOrCopy('renamed')},
+ comments: [ownerComment(`/approve-spec ${oldHead}`)],
+ });
+
+ await run(harness, context({runId: 100n}));
+
+ expect(latestReviewGate(harness.state)).toMatchObject({
+ state: 'pending',
+ description: waiting,
+ });
+ });
+
+ it('resets when a path renamed away is re-added with other text', async () => {
+ // docs/specs/a moves to docs/specs/b, and docs/specs/c takes its
+ // place at docs/specs/a, with text that changed since the approval.
+ const a = 'docs/specs/a/spec.md';
+ const swap = sha => [
+ {
+ filename: a,
+ previous_filename: 'docs/specs/c/spec.md',
+ status: 'renamed',
+ changes: 2,
+ sha,
+ },
+ {
+ filename: 'docs/specs/b/spec.md',
+ previous_filename: a,
+ status: 'renamed',
+ changes: 0,
+ sha: 'blob-b',
+ },
+ ];
+ const harness = createHarness({
+ changedFiles: swap('blob-a-now'),
+ headContent: currentRecord,
+ baseContent: currentRecord,
+ contentAt: {[`${oldHead}:${a}`]: changedRecord},
+ filesAt: {[oldHead]: swap('blob-a-approved')},
+ comments: [ownerComment(`/approve-spec ${oldHead}`)],
+ });
+
+ await run(harness, context({runId: 100n}));
+
+ expect(latestReviewGate(harness.state)).toMatchObject({
+ state: 'pending',
+ description: waiting,
+ });
+ });
+
+ it("still resets when a moved file's text changed", async () => {
+ const target = moved[7];
+ const harness = createHarness({
+ changedFiles: moved,
+ headContent: currentRecord,
+ baseContent: currentRecord,
+ contentAt: {[`${oldHead}:${target.filename}`]: changedRecord},
+ filesAt: {
+ [oldHead]: moved.map(file =>
+ file === target ? {...file, sha: 'blob-earlier'} : file,
+ ),
+ },
+ comments: [ownerComment(`/approve-spec ${oldHead}`)],
+ });
+
+ await run(harness, context({runId: 100n}));
+
+ expect(latestReviewGate(harness.state)).toMatchObject({
+ state: 'pending',
+ description: waiting,
+ });
+ });
+ });
+
it('reads a spec wait as satisfied code review, not an older code wait', async () => {
const harness = createHarness({
headContent: currentRecord,