Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
The public-surface check fails under CI when it cannot read its base (#9478)
Garry Tanaa920e366d4d
diff --git a/changelog.d/capy-public-surface-unreadable-base.md b/changelog.d/capy-public-surface-unreadable-base.mdnew file mode 100644index 0000000000..83867c4d7b--- /dev/null+++ b/changelog.d/capy-public-surface-unreadable-base.md@@ -0,0 +1,5 @@+**The public-surface check no longer passes silently when it cannot read master's copy of a file it compares with.**++### Fixed+- After a shallow CI checkout is deepened with `--filter=blob:none`, `bun run check:public-surface` fetches file contents at the merge base on demand. When that fetch failed, it read master's manifest as missing and skipped the removal check. It now tells a file that is missing on the merge base from one it could not read. Under `CI=true` it fails with git's own error, and locally it skips.+- A file already on master whose name git quotes (one with non-ASCII characters) now counts as on master, so an old `changelog.d` waiver no longer covers a new golden change.diff --git a/scripts/check-public-surface.ts b/scripts/check-public-surface.tsindex a92c3e1f9f..3754594426 100644--- a/scripts/check-public-surface.ts+++ b/scripts/check-public-surface.ts@@ -21,9 +21,9 @@* 4. a change to the CLI or agent-contract goldens with no new behavior-changes.d fragment and no changelog.d line* `<!-- public-surface: no-behavior-change: <reason> -->`.* The manifest's freshness is regen:all's (scripts/build-public-surface.ts --check). Dates are UTC days;- * GBRAIN_SURFACE_TODAY (YYYY-MM-DD) overrides today for tests. When the base ref or a merge base is unavailable the- * check fails under CI=true and skips locally. Fetches (the stable ref, deepening a shallow clone with- * --filter=blob:none, since GitHub's pack-objects crashes on tree:0 for a shallow clone that is not partial) stop after+ * GBRAIN_SURFACE_TODAY (YYYY-MM-DD) overrides today for tests. When the base ref, a merge base or a file on the merge+ * base is unavailable the check fails under CI=true and skips locally. Fetches (the stable ref, deepening a shallow+ * clone with --filter=blob:none, since GitHub's pack-objects crashes on tree:0 for a shallow clone that is not partial) stop after* 20 s and 30 s, or $GBRAIN_SURFACE_FETCH_TIMEOUT_S; a failed fetch prints git's own error. Exit: 0 ok or skipped,* 1 refused.*/@@ -75,7 +75,7 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefinconst today = env.GBRAIN_SURFACE_TODAY || new Date().toISOString().slice(0, 10);const git = (...args: string[]) => {const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });- return { ok: r.status === 0, out: r.stdout ?? '' };+ return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim() };};const fetchTimeout = (seconds: number) => Number(env.GBRAIN_SURFACE_FETCH_TIMEOUT_S) || seconds;let fetchError = '';@@ -103,7 +103,7 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefinif (!mergeBase.ok && git('rev-parse', '--is-shallow-repository').out.trim() === 'true') {const tip = git('rev-parse', `${ref}^{commit}`).out.trim();const parents = git('cat-file', '-p', 'HEAD').out.split('\n').filter(l => l.startsWith('parent ')).map(l => l.slice('parent '.length));- if (parents.includes(tip)) mergeBase = { ok: true, out: tip };+ if (parents.includes(tip)) mergeBase = { ok: true, out: tip, err: '' };for (const depth of [200, 2000]) {if (mergeBase.ok || deepened === 'timeout') break;deepened = fetch(30, '--filter=blob:none', `--deepen=${depth}`, 'origin', git('rev-parse', 'HEAD').out.trim(), tip);@@ -121,7 +121,18 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefinreturn 0;}const base = mergeBase.out.trim();- const onBase = (path: string) => git('cat-file', '-e', `${base}:${path}`).ok;+ let unreadable: { path: string; error: string } | null = null;+ const onBase = (path: string) => {+ const listed = git('ls-tree', '-z', '--name-only', base, '--', path);+ if (!listed.ok) unreadable ??= { path, error: listed.err };+ return listed.ok && listed.out === `${path}\0`;+ };+ const readBase = (path: string) => {+ if (!onBase(path)) return null;+ const shown = git('show', `${base}:${path}`);+ if (!shown.ok) unreadable ??= { path, error: shown.err };+ return shown.ok ? shown.out : null;+ };const listDir = (dir: string) => (existsSync(join(root, dir)) ? readdirSync(join(root, dir)).filter(f => f.endsWith('.md') && f !== 'README.md').sort() : []);const problems: string[] = [];@@ -139,7 +150,8 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefin!DATE.test(record.remove_after) && 'remove_after: must be a date (YYYY-MM-DD)',].filter(Boolean);for (const b of bad) problems.push(`${path}: ${b}`);- const baseFront = onBase(path) ? frontOf(git('show', `${base}:${path}`).out) : null;+ const baseText = readBase(path);+ const baseFront = baseText === null ? null : frontOf(baseText);const baseDate = baseFront ? baseFront.remove_after ?? '' : null;if (!bad.length && baseFront?.surface && baseFront.name && (baseFront.surface !== record.surface || baseFront.name !== record.name)) {problems.push(`${path}: it named ${baseFront.surface} \`${baseFront.name}\` on ${ref}; a record keeps the surface and name it was announced with, so add a new record for ${record.surface} \`${record.name}\``);@@ -158,10 +170,25 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefin.map(f => ({ path: `${FRAGMENT_DIR}/${f}`, ...parseNoticeFragment(readFileSync(join(root, FRAGMENT_DIR, f), 'utf8')) }));const exceptions = new Set(newNotices.filter(n => n.front.kind === 'breaking' && n.front.exception).map(n => n.front.exception));- const baseManifest = git('show', `${base}:${MANIFEST}`);- if (baseManifest.ok && existsSync(join(root, MANIFEST))) {+ const unreadableBase = (): number | null => {+ if (!unreadable) return null;+ const { path, error } = unreadable;+ if (env.CI === 'true') {+ log(`FAIL: check-public-surface: ${path} could not be read at ${ref}'s merge base ${base.slice(0, 12)}, so the check cannot compare with it.`);+ if (error) log(`git: ${error.split('\n').filter(Boolean).slice(-4).join(' / ').slice(-600)}`);+ log('Fix: rerun once origin answers, or fetch full history in the workflow (actions/checkout fetch-depth: 0)');+ return 1;+ }+ log(`GBRAIN_CHECK_SKIPPED: ${path} could not be read at the merge base ${base.slice(0, 12)}`);+ return 0;+ };++ const baseManifest = readBase(MANIFEST);+ const manifestUnread = unreadableBase();+ if (manifestUnread !== null) return manifestUnread;+ if (baseManifest !== null && existsSync(join(root, MANIFEST))) {const head: PublicSurface = JSON.parse(readFileSync(join(root, MANIFEST), 'utf8'));- const dropped = exceptions.has('security') || exceptions.has('data-loss') ? [] : droppedEntries(JSON.parse(baseManifest.out), head);+ const dropped = exceptions.has('security') || exceptions.has('data-loss') ? [] : droppedEntries(JSON.parse(baseManifest), head);const stableRef = env.GBRAIN_SURFACE_STABLE_REF || 'refs/tags/stable';const resolveStable = () => git('rev-parse', '--verify', '-q', `${stableRef}^{commit}`);let stableCommit = resolveStable();@@ -191,7 +218,7 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefinif (!record) problems.push(`${surface} \`${name}\` is removed or changed with no ${DEPRECATION_DIR}/<id>.md naming it (surface: ${surface}, name: ${name})${exceptions.has('revert') ? '; it is on stable, so exception: revert does not cover it' : ''}`);else if (!matured(record)) problems.push(`${surface} \`${name}\` is removed before its record ${DEPRECATION_DIR}/${record.id}.md allows it (remove_after ${record.remove_after}); keep it working with a warning until then`);}- } else if (!baseManifest.ok) {+ } else if (baseManifest === null) {log(`check-public-surface: ${ref} has no ${MANIFEST} yet; the removal check starts once it does`);}@@ -205,12 +232,16 @@ export function main(opts: { cwd?: string; env?: Record<string, string | undefinelse if (!matured(record)) problems.push(`${path}: deprecation: ${front.deprecation} has not matured (remove_after ${record.remove_after})`);}- const goldens = git('diff', '--name-only', base, '--', ...GOLDEN_DIRS).out.split('\n').filter(Boolean);+ const goldenDiff = git('diff', '--name-only', base, '--', ...GOLDEN_DIRS);+ if (!goldenDiff.ok) unreadable ??= { path: GOLDEN_DIRS.join(', '), error: goldenDiff.err };+ const goldens = goldenDiff.out.split('\n').filter(Boolean);if (goldens.length && !newNotices.length) {const waived = listDir(CHANGELOG_FRAGMENT_DIR).some(f => !onBase(`${CHANGELOG_FRAGMENT_DIR}/${f}`) && NO_BEHAVIOR_CHANGE.test(readFileSync(join(root, CHANGELOG_FRAGMENT_DIR, f), 'utf8')));if (!waived) problems.push(`CLI or agent-contract goldens changed (${goldens.slice(0, 3).join(', ')}${goldens.length > 3 ? `, +${goldens.length - 3} more` : ''}) with no new ${FRAGMENT_DIR} row; add one with its kind, or put <!-- public-surface: no-behavior-change: <reason> --> in your ${CHANGELOG_FRAGMENT_DIR} fragment`);}+ const goldensUnread = unreadableBase();+ if (goldensUnread !== null) return goldensUnread;if (!problems.length) {log(`check-public-surface: ok against ${ref} (${records.size} deprecation record(s), ${newNotices.length} new behaviour-change row(s))`);return 0;diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsvindex 56da26a436..f4884d2882 100644--- a/scripts/structural-suites.tsv+++ b/scripts/structural-suites.tsv@@ -313,7 +313,7 @@ test/scripts/check-dynamic-ci.test.ts check-dynamic-ci.ts 1 exec-scan,readFileSytest/scripts/check-function-size.test.ts check-function-size.ts rules 11 readFileSynctest/scripts/check-item-allowlist-catches.test.ts CLI 2 readFileSynctest/scripts/check-public-surface.test.ts dropped manifest entries 5 bun-file-test/scripts/check-public-surface.test.ts the base it compares with 9 bun-file+test/scripts/check-public-surface.test.ts the base it compares with 10 bun-filetest/scripts/check-public-surface.test.ts the committed manifest 2 bun-filetest/scripts/chunk-visibility-ratchet.test.ts check-chunk-visibility.ts 6 readFileSynctest/scripts/ci-bounded-run.test.ts (file-level) 7 readFileSyncdiff --git a/test/scripts/check-public-surface.test.ts b/test/scripts/check-public-surface.test.tsindex 11a47e1e8f..ce36bf105b 100644--- a/test/scripts/check-public-surface.test.ts+++ b/test/scripts/check-public-surface.test.ts@@ -250,6 +250,23 @@ describe('the base it compares with', () => {expect(r.out).toMatch(/git: .*(does not appear to be a git repository|not found|No such file)/);});+ test('a base manifest that cannot be read fails under CI instead of counting as missing, and skips locally', () => {+ const origin = repo({}, { [MANIFEST]: manifest({ 'mcp-tool': [] }) });+ git(origin, 'config', 'uploadpack.allowFilter', 'true');+ const clone = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-clone-'));+ roots.push(clone);+ git(clone, 'clone', '-q', '--filter=blob:none', '--no-tags', '--branch', 'head', `file://${origin}`, '.');+ git(clone, 'fetch', '-q', '--no-tags', 'origin', '+refs/heads/base:refs/remotes/origin/base');+ git(clone, 'remote', 'set-url', 'origin', join(clone, 'no-such-remote'));+ const ci = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });+ expect(ci.code).toBe(1);+ expect(ci.out).toContain(`FAIL: check-public-surface: ${MANIFEST} could not be read at origin/base's merge base`);+ expect(ci.out).toMatch(/\ngit: \S/);+ const local = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base' });+ expect(local.code).toBe(0);+ expect(local.out).toContain(`GBRAIN_CHECK_SKIPPED: ${MANIFEST} could not be read at the merge base`);+ });+test('a shallow pull-request merge commit whose parent is the base tip needs no fetch', () => {const origin = repo({}, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) });git(origin, 'checkout', '-q', 'base');@@ -398,6 +415,15 @@ describe('golden changes', () => {expect(run(repo({ [golden]: 'old\n' }, { [golden]: 'new\n', 'changelog.d/x.md': 'Entry.\n\n<!-- public-surface: no-behavior-change: help text reflowed -->\n' })).code).toBe(0);});+ test('a waiver already on the base does not cover a new golden change, whatever its file name', () => {+ const waiver = 'Entry.\n\n<!-- public-surface: no-behavior-change: help text reflowed -->\n';+ for (const name of ['changelog.d/x.md', 'changelog.d/café.md']) {+ const r = run(repo({ [golden]: 'old\n', [name]: waiver }, { [golden]: 'new\n' }));+ expect(r.code).toBe(1);+ expect(r.out).toContain('CLI or agent-contract goldens changed (test/fixtures/goldens/cli/search-help.txt)');+ }+ });+test('other goldens are not covered', () => {expect(run(repo({ 'test/fixtures/goldens/doctor/a.json': '1\n' }, { 'test/fixtures/goldens/doctor/a.json': '2\n' })).code).toBe(0);});