mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 23:08:26 +01:00
fix(verify): report stale SDK public input pins locally, before CI (#21283)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Runner support suite proves the plugin SDK public types against
pinned source. The pins are in
`tests/runner-e2e/source-sdk-public-inputs.json`.
> - The pins cover every file in `packages/shared/src` and
`packages/plugins/sdk/src`, and the SDK build inputs (for example
`pnpm-lock.yaml`).
> - A PR that edits a pinned file and does not refresh the registry
fails three files in the "Runner support suite" lane.
> - Between 2026-11-12 10:27Z and 2026-11-13 01:14Z, this failure
occurred in 14 CI runs on 12 PRs.
> - The local check, `pnpm verify`, returned exit 2 ("let CI cover it")
for these changes. It did not mention the pins. Authors pushed, and CI
failed.
> - This pull request makes `pnpm verify` find stale pins before the
push. It also makes the opaque fixture error name the file and the fix.
> - The benefit is that authors find and fix the problem in seconds,
locally, instead of after a 6-minute CI lane.
## Linked Issues or Issue Description
**What happened?**
Three files in the "Runner support suite" lane failed together on many
unrelated PRs: `source-sdk-evidence.test.ts`,
`source-sdk-public-inputs.test.mjs` and
`source-sdk-public-type.test.ts`. Two of the three failed with the
opaque error `Reviewed SDK reference source changed`.
**Root cause**
The pins on master are not stale. The tests pass on master (58/58). Each
failing PR edited a pinned input and did not refresh the registry. I
compared the PR heads with their merge base:
- All 14 failing heads (12 PRs) changed a pinned input. None of them
changed `source-sdk-public-inputs.json`.
- All 19 heads in the same window that changed a pinned input and passed
this lane also refreshed the registry. This includes later heads of
three PRs that failed first (#21119, #21121, #21156).
- Two of the 12 PRs are Dependabot PRs that change only `pnpm-lock.yaml`
(#19593, #19594). The lockfile refresh bot already resyncs the pins for
lock changes on master.
**Steps to reproduce**
1. Start from `origin/master`.
2. Add one line to `packages/shared/src/types/heartbeat.ts` and commit
it.
3. Run `node node_modules/vitest/vitest.mjs run --config
tests/runner-e2e/vitest.config.ts source-sdk-evidence.test.ts
source-sdk-public-inputs.test.mjs source-sdk-public-type.test.ts`.
4. The result is the same as CI: 3 files fail, with the same 4 failures.
5. Run `pnpm verify --explain`. It returns exit 2 and does not mention
the pins.
**Expected behavior**
`pnpm verify` reports the stale pins and the refresh command before the
author pushes.
## What Changed
- `tests/runner-e2e/source-sdk-public-inputs.mjs`: add
`staleSdkPublicInputsInWorkingTree(root)`. It applies the existing drift
guard to the working tree (tracked and untracked files that git does not
ignore). Add `isSdkPublicInput(file)` and the shared failure message
`staleSdkPublicInputsMessage(stale)`. The committed-tree guard keeps its
behavior and now uses a shared comparison.
- `scripts/local-verify.mjs`: when the diff touches a pinned input, the
registry or `report-lock.json`, `pnpm verify` checks the pins first. If
they are stale, it exits 1 and prints the files and the refresh command.
The check reads files only. It does not write the registry.
- `tests/runner-e2e/source-sdk-reviewed-fixture.ts`: the error `Reviewed
SDK reference source changed` now names the file and gives the refresh
command.
- `tests/runner-e2e/source-sdk-public-inputs.test.mjs`: new test for the
working-tree guard (uncommitted edit, untracked file, ignored file). The
CI drift test uses the shared message.
- `doc/DEVELOPING.md`: document the new check under "Incremental local
verification".
No assertion is weakened. No pin is changed. No file under `.github/` is
changed.
## Verification
- Master, without this change: the three files pass (58/58).
- Red: on master plus a one-line edit to
`packages/shared/src/types/heartbeat.ts`, the three files fail with the
CI signature. `pnpm verify --explain` returns exit 2 and does not
mention the pins.
- With this change on the same red commit: `pnpm verify` exits 1 in
about 15 s and prints `tests/runner-e2e/source-sdk-public-inputs.json is
stale for 1 pinned input(s): packages/shared/src/types/heartbeat.ts
(changed). Commit your change, run ... --write, and commit the updated
registry.`
- Green: I followed the printed command (`node
tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD> --write`, then
commit). The three files then pass (59/59, with the new test).
- `node --test scripts/__tests__/local-verify.test.mjs`: 14/14 pass.
- `pnpm verify` on this branch returns exit 2 because
`scripts/local-verify.mjs` is a global CI input. Required CI supplies
the broad coverage.
## Risks
- Low risk. The new check only reads files. It runs only when the diff
touches a pinned input.
- `pnpm verify` now fails (exit 1) for a change that also fails in CI.
Before, it returned exit 2.
- The check needs a working `git ls-files` in the repository. `pnpm
verify` already needs git.
- Dependabot lock PRs still fail this lane until the lockfile bot
refreshes the pins. This PR does not change that path.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude (Anthropic), Claude Code agent with tool use (shell, git,
GitHub CLI). Commits are attributed to Claude Fable 5.2.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
1 parent
0c63f0fdb3
commit
db3d7223e0
6 files changed
+151
-10
No files matched your search
@@ -94,21 +94,62 @@ export async function synchronizeSdkPublicInputs(root, revision, { write = false
|
||||
*/
|
||||
export async function staleSdkPublicInputs(root, revision = "HEAD") {
|
||||
const registry = JSON.parse(await readFile(path.join(root, registryPath), "utf8"));
|
||||
const pinned = registry.inputs ?? {};
|
||||
const committed = {};
|
||||
for (const entry of git(root, ["ls-tree", "-rz", revision, "--", ...sourceRoots, ...buildInputs]).split("\0").filter(Boolean)) {
|
||||
const match = /^\d+ blob ([a-f0-9]{40})\t(.+)$/.exec(entry);
|
||||
if (match) committed[match[2]] = match[1];
|
||||
}
|
||||
const stale = [...new Set([...Object.keys(pinned), ...Object.keys(committed)])].sort()
|
||||
.filter(file => pinned[file] !== committed[file])
|
||||
.map(file => ({ file, change: !pinned[file] ? "unpinned" : !committed[file] ? "removed" : "changed" }));
|
||||
// A lockfile refresh rewrites report-lock.json; lockSha256 must follow its output hash.
|
||||
const policy = JSON.parse(git(root, ["show", `${revision}:${reportLockPath}`]));
|
||||
return compareSdkPublicInputs(registry, committed, policy);
|
||||
}
|
||||
|
||||
function compareSdkPublicInputs(registry, actual, policy) {
|
||||
const pinned = registry.inputs ?? {};
|
||||
const stale = [...new Set([...Object.keys(pinned), ...Object.keys(actual)])].sort()
|
||||
.filter(file => pinned[file] !== actual[file])
|
||||
.map(file => ({ file, change: !pinned[file] ? "unpinned" : !actual[file] ? "removed" : "changed" }));
|
||||
if (registry.lockSha256 !== policy.outputSha256) stale.push({ file: `${reportLockPath} outputSha256`, change: "lockSha256 changed" });
|
||||
return stale;
|
||||
}
|
||||
|
||||
const committedLockBlob = root => {
|
||||
try { return git(root, ["rev-parse", "--verify", "--quiet", "HEAD:pnpm-lock.yaml"]).trim(); }
|
||||
catch { return null; }
|
||||
};
|
||||
|
||||
/** True when a repository path is one of the inputs the registry pins. */
|
||||
export const isSdkPublicInput = file => sourcePath(file) || buildInputs.includes(file);
|
||||
|
||||
/**
|
||||
* The same drift guard over the working tree (tracked and untracked, non-ignored
|
||||
* files), so local verification reports a missing registry refresh before the
|
||||
* change is pushed. CI runs the committed-tree guard in the Runner support suite.
|
||||
*/
|
||||
export async function staleSdkPublicInputsInWorkingTree(root) {
|
||||
const registry = JSON.parse(await readFile(path.join(root, registryPath), "utf8"));
|
||||
const actual = {};
|
||||
const listed = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...sourceRoots, ...buildInputs]);
|
||||
for (const file of [...new Set(listed.split("\0").filter(Boolean))]) {
|
||||
try {
|
||||
const bytes = await readFile(path.join(root, file));
|
||||
// Preserve the authenticated restored-lock exception: prepare-report-lock.mjs may leave the
|
||||
// reviewed output lock in the working tree while the registry keeps the committed input pin.
|
||||
// It applies only as an uncommitted overlay over a committed lock that matches its pin.
|
||||
actual[file] = file === "pnpm-lock.yaml" && hex64(registry.lockSha256) && sha256(bytes) === registry.lockSha256
|
||||
&& committedLockBlob(root) === registry.inputs?.[file] ? registry.inputs[file] : blob(bytes);
|
||||
} catch (error) { if (error.code !== "ENOENT") throw error; }
|
||||
}
|
||||
const policy = JSON.parse(await readFile(path.join(root, reportLockPath), "utf8"));
|
||||
return compareSdkPublicInputs(registry, actual, policy);
|
||||
}
|
||||
|
||||
/** The actionable failure text shared by the CI drift guard and local verification. */
|
||||
export function staleSdkPublicInputsMessage(stale) {
|
||||
return `${registryPath} is stale for ${stale.length} pinned input(s): ${stale.slice(0, 10).map(row => `${row.file} (${row.change})`).join(", ")}${stale.length > 10 ? ", ..." : ""}. `
|
||||
+ "Commit your change, run `node tests/runner-e2e/source-sdk-public-inputs.mjs $(git rev-parse HEAD) --write`, and commit the updated registry.";
|
||||
}
|
||||
|
||||
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
||||
const [revision, mode] = process.argv.slice(2);
|
||||
if (process.argv.length !== 4 || !["--check", "--write"].includes(mode)) throw new Error("Usage: node tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD-40hex> --check|--write");
|
||||
|
||||
@@ -6,7 +6,7 @@ import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { afterEach, test } from "vitest";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { staleSdkPublicInputs, synchronizeSdkPublicInputs } from "./source-sdk-public-inputs.mjs";
|
||||
import { isSdkPublicInput, staleSdkPublicInputs, staleSdkPublicInputsInWorkingTree, staleSdkPublicInputsMessage, synchronizeSdkPublicInputs } from "./source-sdk-public-inputs.mjs";
|
||||
|
||||
const registry = "tests/runner-e2e/source-sdk-public-inputs.json";
|
||||
const reportLock = "tests/runner-e2e/report-lock.json";
|
||||
@@ -116,8 +116,35 @@ test("refuses a committed lock that the report-lock policy does not review", asy
|
||||
test("the committed SDK public source pins match this checkout's committed tree", async () => {
|
||||
const root = fileURLToPath(new URL("../..", import.meta.url));
|
||||
const stale = await staleSdkPublicInputs(root);
|
||||
assert.deepEqual(stale, [], `${registry} is stale for ${stale.length} pinned input(s): ${stale.slice(0, 10).map(row => `${row.file} (${row.change})`).join(", ")}${stale.length > 10 ? ", ..." : ""}. `
|
||||
+ "Commit your change, run `node tests/runner-e2e/source-sdk-public-inputs.mjs $(git rev-parse HEAD) --write`, and commit the updated registry.");
|
||||
assert.deepEqual(stale, [], staleSdkPublicInputsMessage(stale));
|
||||
});
|
||||
// pnpm verify reads the working tree, so an uncommitted or unpushed edit to a
|
||||
// pinned input is reported locally instead of failing the Runner support suite in CI.
|
||||
test("the working-tree drift guard sees uncommitted and untracked pinned inputs", async () => {
|
||||
const { root, revision } = await fixture();
|
||||
await synchronizeSdkPublicInputs(root, revision, { write: true }); commit(root, "resync");
|
||||
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), []);
|
||||
await put(root, "packages/shared/src/schema.ts", "uncommitted synthetic edit\n");
|
||||
await put(root, "packages/shared/src/untracked.ts", "untracked synthetic source\n");
|
||||
await put(root, "packages/shared/src/ignored.ts", "ignored synthetic source\n"); await put(root, ".gitignore", "packages/shared/src/ignored.ts\n");
|
||||
const stale = await staleSdkPublicInputsInWorkingTree(root);
|
||||
assert.deepEqual(stale, [{ file: "packages/shared/src/schema.ts", change: "changed" }, { file: "packages/shared/src/untracked.ts", change: "unpinned" }]);
|
||||
assert.match(staleSdkPublicInputsMessage(stale), /packages\/shared\/src\/schema\.ts \(changed\).*source-sdk-public-inputs\.mjs \$\(git rev-parse HEAD\) --write/);
|
||||
assert.deepEqual(await staleSdkPublicInputs(root), [], "the committed-tree guard is unaffected by uncommitted edits");
|
||||
git(root, "checkout", "--", "packages/shared/src/schema.ts");
|
||||
await rm(path.join(root, "packages/shared/src/untracked.ts"));
|
||||
// The reviewed restored lock overlay in the working tree is not drift; any other lock edit is.
|
||||
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic authenticated restored lock");
|
||||
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), []);
|
||||
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic unreviewed lock edit\n");
|
||||
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), [{ file: "pnpm-lock.yaml", change: "changed" }]);
|
||||
// Committing the reviewed output lock without a registry refresh is drift: CI's committed-tree guard reports it, so must this one.
|
||||
await writeFile(path.join(root, "pnpm-lock.yaml"), "synthetic authenticated restored lock"); commit(root, "commit reviewed output lock");
|
||||
assert.deepEqual(await staleSdkPublicInputs(root), [{ file: "pnpm-lock.yaml", change: "changed" }]);
|
||||
assert.deepEqual(await staleSdkPublicInputsInWorkingTree(root), [{ file: "pnpm-lock.yaml", change: "changed" }]);
|
||||
assert.equal(isSdkPublicInput("packages/shared/src/types/heartbeat.ts"), true);
|
||||
assert.equal(isSdkPublicInput("pnpm-lock.yaml"), true);
|
||||
assert.equal(isSdkPublicInput("server/src/index.ts"), false);
|
||||
});
|
||||
test("the drift guard names changed, unpinned and removed inputs and clears after a resync", async () => {
|
||||
const { root, revision } = await fixture();
|
||||
|
||||
@@ -44,7 +44,8 @@ export async function prepareReviewedSdkReference(original:string,directory:stri
|
||||
if(![policy.inputSha256,policy.outputSha256].includes(sha(committed)))throw new Error("Committed SDK reference lock is not reviewed");
|
||||
for(const [file,expected]of Object.entries(pins.inputs)){
|
||||
const bytes=file==="pnpm-lock.yaml"?committed:await readFile(path.join(original,file));
|
||||
if(file!=="pnpm-lock.yaml"&&blob(bytes)!==expected)throw new Error("Reviewed SDK reference source changed");
|
||||
if(file!=="pnpm-lock.yaml"&&blob(bytes)!==expected)throw new Error(`Reviewed SDK reference source changed: ${file} does not match its pin in tests/runner-e2e/source-sdk-public-inputs.json. `
|
||||
+"Commit your change, run `node tests/runner-e2e/source-sdk-public-inputs.mjs $(git rev-parse HEAD) --write`, and commit the updated registry.");
|
||||
const target=path.join(directory,file);await mkdir(path.dirname(target),{recursive:true});
|
||||
if(file==="pnpm-lock.yaml")await writeFile(target,bytes);else await copyFile(path.join(original,file),target);
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user