Skip to content

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.md
new file mode 100644
index 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.ts
index 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 | undefin
const 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 | undefin
if (!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 | undefin
return 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 | undefin
if (!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 | undefin
else 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.tsv
index 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,readFileSy
test/scripts/check-function-size.test.ts check-function-size.ts rules 11 readFileSync
test/scripts/check-item-allowlist-catches.test.ts CLI 2 readFileSync
test/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-file
test/scripts/check-public-surface.test.ts the committed manifest 2 bun-file
test/scripts/chunk-visibility-ratchet.test.ts check-chunk-visibility.ts 6 readFileSync
test/scripts/ci-bounded-run.test.ts (file-level) 7 readFileSync
diff --git a/test/scripts/check-public-surface.test.ts b/test/scripts/check-public-surface.test.ts
index 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);
});