refactor(scripts): extract shared sync helpers into scripts/lib/sync.ts

Both sync-schemas.ts and packages/codex-plugin/build.mts were hand-rolling
the same "compare source to target, print drift, exit 1 in --check mode"
pattern with slightly different output shapes. Extract:

- walkFiles(root, filter?) — recursive relative-path lister shared with
  the codex-plugin drift checker
- reportAndExit(drifted, { checkMode, label, fixCommand }) — prints a
  unified ✓/✗ summary, caps drift list, exits non-zero in check mode

Both callers now produce the same output shape so contributors see the
same UI whether they're syncing schemas or the codex plugin:

  ✗ <label> is out of sync:
    changed <path>
    missing <path>
    extra   <path>
  Run `<fix command>` and commit the result.

Verified: lint, format:check, sync-schemas:check, check:codex-plugin all
pass. Drift injection tests pass on both sync paths. Pre-commit hook still
auto-rebuilds the plugin skills/ copy on source changes and correctly
skips when only the plugin copy is edited (no clobber cycle).
This commit is contained in:
James
2026-04-21 19:36:52 +00:00
parent d04e02ddd0
commit 462bdf48ee
3 changed files with 123 additions and 64 deletions
+31 -48
View File
@@ -20,6 +20,9 @@ import {
import { join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import type { DriftEntry } from "../../scripts/lib/sync.ts";
import { reportAndExit, walkFiles } from "../../scripts/lib/sync.ts";
const __dirname = fileURLToPath(new URL(".", import.meta.url));
const repoSkillsDir = resolve(__dirname, "..", "..", "skills");
const outDir = resolve(__dirname, "skills");
@@ -60,34 +63,11 @@ function reportExtras() {
}
}
function assemble() {
rmSync(outDir, { recursive: true, force: true });
mkdirSync(outDir, { recursive: true });
for (const name of SKILLS) {
const src = join(repoSkillsDir, name);
assertSkillDir(src);
cpSync(src, join(outDir, name), { recursive: true });
console.log(` ${name}`);
}
}
function walkFiles(root: string): string[] {
const out: string[] = [];
const entries = readdirSync(root, { withFileTypes: true });
for (const e of entries) {
const abs = join(root, e.name);
if (e.isDirectory()) {
for (const rel of walkFiles(abs)) out.push(join(e.name, rel));
} else if (e.isFile()) {
out.push(e.name);
}
}
return out;
}
function detectDrift(): string[] {
// Build the expected file map from source skills; the committed output is
// the "actual". A drifted path is any that differs, is missing, or extra.
/**
* Returns the expected file map (relative path → bytes) and the actual file
* map from the built output. Used by both apply and check modes.
*/
function buildFileMaps(): { expected: Map<string, Buffer>; actual: Map<string, Buffer> } {
const expected = new Map<string, Buffer>();
for (const name of SKILLS) {
const src = join(repoSkillsDir, name);
@@ -96,44 +76,47 @@ function detectDrift(): string[] {
expected.set(join(name, rel), readFileSync(join(src, rel)));
}
}
const actual = new Map<string, Buffer>();
if (existsSync(outDir)) {
for (const rel of walkFiles(outDir)) {
actual.set(rel, readFileSync(join(outDir, rel)));
}
}
return { expected, actual };
}
const drifted: string[] = [];
function diff(expected: Map<string, Buffer>, actual: Map<string, Buffer>): DriftEntry[] {
const drifted: DriftEntry[] = [];
for (const [path, content] of expected) {
const have = actual.get(path);
if (!have) {
drifted.push(`missing: ${path}`);
} else if (!have.equals(content)) {
drifted.push(`changed: ${path}`);
}
if (!have) drifted.push({ kind: "missing", path });
else if (!have.equals(content)) drifted.push({ kind: "changed", path });
}
for (const path of actual.keys()) {
if (!expected.has(path)) drifted.push(`extra: ${path}`);
if (!expected.has(path)) drifted.push({ kind: "extra", path });
}
return drifted.sort();
return drifted.sort((a, b) => a.path.localeCompare(b.path));
}
if (checkMode) {
const drifted = detectDrift();
const { expected, actual } = buildFileMaps();
const drifted = diff(expected, actual);
reportExtras();
if (drifted.length === 0) {
console.log("\n✓ Codex plugin skills/ is up to date.");
} else {
console.error("\n✗ Codex plugin skills/ is out of sync with repo skills/:\n");
for (const line of drifted.slice(0, 30)) console.error(` ${line}`);
if (drifted.length > 30) console.error(` … and ${drifted.length - 30} more`);
console.error("\nRun `bun run --cwd packages/codex-plugin build` and commit the result.");
process.exit(1);
}
reportAndExit(drifted, {
checkMode: true,
label: "Codex plugin skills/",
fixCommand: "bun run --cwd packages/codex-plugin build",
});
} else {
console.log(`Assembling Codex plugin skills/ from ${repoSkillsDir}\n`);
assemble();
rmSync(outDir, { recursive: true, force: true });
mkdirSync(outDir, { recursive: true });
for (const name of SKILLS) {
const src = join(repoSkillsDir, name);
assertSkillDir(src);
cpSync(src, join(outDir, name), { recursive: true });
console.log(` ${name}`);
}
reportExtras();
console.log(`\n✓ Wrote ${SKILLS.length} skills to ${outDir}`);
}
+78
View File
@@ -0,0 +1,78 @@
/**
* Shared primitives for scripts that mirror one tree/file set into another
* and need a --check mode that fails CI on drift.
*
* Used by `scripts/sync-schemas.ts` (flat file list) and
* `packages/codex-plugin/build.mts` (recursive skill directories).
*/
import { readdirSync } from "node:fs";
import { join } from "node:path";
export type DriftKind = "changed" | "missing" | "extra";
export interface DriftEntry {
kind: DriftKind;
/** Display path, relative to the source/target roots. */
path: string;
}
/**
* Recursively list file paths under `root`, returning paths relative to
* `root`. Skips everything that isn't a regular file (symlinks, sockets).
* Optional `filter` returns true to keep the file.
*/
export function walkFiles(root: string, filter?: (relPath: string) => boolean): string[] {
const out: string[] = [];
function visit(dir: string, prefix: string) {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const abs = join(dir, entry.name);
const rel = prefix ? join(prefix, entry.name) : entry.name;
if (entry.isDirectory()) {
visit(abs, rel);
} else if (entry.isFile() && (!filter || filter(rel))) {
out.push(rel);
}
}
}
visit(root, "");
return out;
}
/**
* Print a sync/check result and, in check mode, exit non-zero on drift.
*
* The output shape is shared across sync scripts so users learn one pattern:
* a ✓/✗ header, a per-entry list (capped), and a "run X to fix" hint.
*/
export function reportAndExit(
drifted: DriftEntry[],
options: {
checkMode: boolean;
/** What is being synced. Used in the success message. */
label: string;
/** Command the user should run to fix drift. */
fixCommand: string;
/** Max entries to print before truncating. Default 30. */
maxEntries?: number;
},
): void {
const max = options.maxEntries ?? 30;
if (drifted.length === 0) {
console.log(`\n✓ ${options.label} is up to date.`);
return;
}
if (!options.checkMode) {
console.log(`\n${options.label}: ${drifted.length} file(s) updated.`);
return;
}
console.error(`\n✗ ${options.label} is out of sync:\n`);
for (const entry of drifted.slice(0, max)) {
console.error(` ${entry.kind.padEnd(7)} ${entry.path}`);
}
if (drifted.length > max) {
console.error(` … and ${drifted.length - max} more`);
}
console.error(`\nRun \`${options.fixCommand}\` and commit the result.`);
process.exit(1);
}
+14 -16
View File
@@ -17,14 +17,17 @@
import { readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import type { DriftEntry } from "./lib/sync.ts";
import { reportAndExit } from "./lib/sync.ts";
const ROOT = join(import.meta.dirname, "..");
const SOURCE_DIR = join(ROOT, "packages/core/schemas");
const TARGET_DIR = join(ROOT, "docs/schema");
const MIRRORED = ["registry.json", "registry-item.json"];
function main() {
const checkOnly = process.argv.includes("--check");
let drift = 0;
const checkMode = process.argv.includes("--check");
const drifted: DriftEntry[] = [];
for (const name of MIRRORED) {
const source = readFileSync(join(SOURCE_DIR, name), "utf-8");
@@ -37,24 +40,19 @@ function main() {
}
})();
if (target === source) {
console.log(` ✓ ${name} in sync`);
continue;
}
if (target === source) continue;
drift++;
if (checkOnly) {
console.error(` ✗ ${name} out of sync (run \`bun run sync-schemas\` to fix)`);
continue;
drifted.push({ kind: target === null ? "missing" : "changed", path: name });
if (!checkMode) {
writeFileSync(targetPath, source);
}
writeFileSync(targetPath, source);
console.log(` → ${name} updated`);
}
if (checkOnly && drift > 0) {
console.error(`\n${drift} schema${drift === 1 ? "" : "s"} drifted from source.`);
process.exit(1);
}
reportAndExit(drifted, {
checkMode,
label: "docs/schema/",
fixCommand: "bun run sync-schemas",
});
}
main();