@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/init.ts

@@ -0,0 +1,275 @@
+import { execFileSync } from "./spawn.ts";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_FILE, HOSTS, SKILL_PACKS, defaultPacks } from "./config.ts";
+import { PRINT_WIDTH } from "./sync/standards.ts";
+import { PACKAGE_NAME } from "./sync/stock.ts";
+
+export { PACKAGE_NAME };
+
+const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The `repo:*` scripts older inits copied into a consumer, with every value they wrote: init removes one still equal to one of them. */
+const OLD_DEFAULT_SCRIPTS: Record<string, readonly string[]> = {
+  "repo:build": ["tsc -p tsconfig.build.json"],
+  "repo:prepack": ["bun run build"],
+  "repo:rulesync:generate": [
+    "bun ./.rulesync/scripts/guarded-roots.ts generate",
+    "node ./.rulesync/scripts/guarded-roots.mjs generate",
+    "node ./scripts/guarded-roots.mjs generate",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks && node scripts/emit-mcp-policy.mjs && node scripts/emit-gemini.mjs && node scripts/emit-agent-shell-tools.mjs && node scripts/hooks-union.mjs",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks && node scripts/emit-mcp-policy.mjs",
+  ],
+  "repo:rulesync:watch": [
+    "bun ./.rulesync/scripts/guarded-roots.ts watch",
+    "node ./.rulesync/scripts/guarded-roots.mjs watch",
+    "node ./scripts/guarded-roots.mjs watch",
+    "node scripts/emit-mcp-policy.mjs && node scripts/emit-gemini.mjs && node scripts/emit-agent-shell-tools.mjs && rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills --watch",
+    "node scripts/emit-mcp-policy.mjs && rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents --watch",
+  ],
+  "repo:rulesync:check": [
+    "bun ./.rulesync/scripts/guarded-roots.ts check",
+    "node ./.rulesync/scripts/guarded-roots.mjs check",
+    "node ./scripts/guarded-roots.mjs check",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,skills --check && rulesync generate -t codexcli,antigravity-cli,grokcli -f subagents --check && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks --check && node scripts/emit-mcp-policy.mjs --check && node scripts/emit-gemini.mjs --check && node scripts/emit-agent-shell-tools.mjs --check && node scripts/check-globals.mjs && node scripts/hooks-union.mjs --check",
+    "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents --check && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks --check && node scripts/emit-mcp-policy.mjs --check && node scripts/check-globals.mjs",
+  ],
+  "repo:hooks:union": [
+    "bun .rulesync/scripts/hooks-union.ts",
+    "node .rulesync/scripts/hooks-union.mjs",
+    "node scripts/hooks-union.mjs",
+  ],
+  "repo:hooks:check": [
+    "bun .rulesync/scripts/hooks-union.ts --check",
+    "node .rulesync/scripts/hooks-union.mjs --check",
+    "node scripts/hooks-union.mjs --check",
+  ],
+  "repo:doctor": [
+    "repo doctor",
+    "bun ./.rulesync/scripts/doctor.ts",
+    "node ./.rulesync/scripts/doctor.mjs",
+    "node ./scripts/doctor.mjs",
+  ],
+  "repo:clean": ["repo clean", "bun ./.rulesync/scripts/clean.ts", "node ./.rulesync/scripts/clean.mjs"],
+  "repo:setup": [
+    "repo setup",
+    "bun ./.rulesync/scripts/setup.ts",
+    "node ./.rulesync/scripts/setup.mjs",
+    "node ./scripts/setup.mjs",
+  ],
+  "repo:tasks": ["repo tasks", "bun .rulesync/scripts/vscode-tasks.ts", "node .rulesync/scripts/vscode-tasks.mjs"],
+  "repo:rulesync:doctor": ["rulesync doctor"],
+  "repo:sync:globals": [
+    "repo sync-globals",
+    "bun .rulesync/scripts/sync-global-settings.ts",
+    "node .rulesync/scripts/sync-global-settings.mjs",
+    "node scripts/sync-global-settings.mjs",
+  ],
+  "repo:sync:globals:check": [
+    "bun .rulesync/scripts/check-globals.ts",
+    "node .rulesync/scripts/check-globals.mjs",
+    "node scripts/check-globals.mjs",
+  ],
+  "repo:sync:globals:apply": [
+    "repo sync-globals --apply",
+    "bun .rulesync/scripts/sync-global-settings.ts --apply",
+    "node .rulesync/scripts/sync-global-settings.mjs --apply",
+    "node scripts/sync-global-settings.mjs --apply",
+  ],
+  "repo:purge:global-mcps": [
+    "repo purge-mcps",
+    "bun .rulesync/scripts/purge-global-mcps.ts",
+    "node .rulesync/scripts/purge-global-mcps.mjs",
+    "node scripts/purge-global-mcps.mjs",
+  ],
+  "repo:purge:global-mcps:apply": [
+    "repo purge-mcps --apply",
+    "bun .rulesync/scripts/purge-global-mcps.ts --apply",
+    "node .rulesync/scripts/purge-global-mcps.mjs --apply",
+    "node scripts/purge-global-mcps.mjs --apply",
+  ],
+  "repo:typecheck": ["tsc -p ."],
+  "repo:test:e2e": ["vitest run -c vitest.e2e.config.ts"],
+  "repo:antigravity": ["antigravity --dangerously-skip-permissions"],
+  "repo:claude": ["claude --dangerously-skip-permissions"],
+  "repo:codex": ["codex --dangerously-bypass-approvals-and-sandbox"],
+  "repo:gemini": ["gemini --yolo"],
+  "repo:grok": ["grok --yolo"],
+};
+
+function sortKeys<T>(obj: Record<string, T>): Record<string, T> {
+  // k comes from Object.keys(obj), so it is always present
+  return Object.fromEntries(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k]!]),
+  );
+}
+
+export function samePath(a: string, b: string): boolean {
+  try {
+    return fs.realpathSync.native(a) === fs.realpathSync.native(b);
+  } catch {
+    return path.resolve(a) === path.resolve(b);
+  }
+}
+
+/** The slice of package.json init reads; other keys pass through. */
+interface PackageJson {
+  name?: string;
+  version?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function isStringRecord(v: unknown): v is Record<string, string> {
+  return isRecord(v) && Object.values(v).every((x) => typeof x === "string");
+}
+
+/** True when name and version are strings and the script and dependency maps hold only strings. */
+function isPackageJson(v: unknown): v is PackageJson {
+  return (
+    isRecord(v) &&
+    [v.name, v.version].every((x) => x === undefined || typeof x === "string") &&
+    [v.scripts, v.dependencies, v.devDependencies].every((x) => x === undefined || isStringRecord(x))
+  );
+}
+
+/** The JSON file at `file`, refused with a clear error unless `is` accepts its shape. */
+function readJsonFile<T>(file: string, is: (v: unknown) => v is T): T {
+  const value: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!is(value)) throw new Error(`${file} does not hold the shape repo needs`);
+  return value;
+}
+
+export function placeDevDependency(destPkg: PackageJson, srcPkg?: PackageJson): void {
+  const deps = destPkg.dependencies && typeof destPkg.dependencies === "object" ? destPkg.dependencies : null;
+  const devDeps: Record<string, string> = { ...(destPkg.devDependencies || {}) };
+  destPkg.devDependencies = devDeps;
+  const fromDep = deps?.[PACKAGE_NAME];
+  const fromDev = devDeps[PACKAGE_NAME];
+  if (fromDep != null && deps) {
+    delete deps[PACKAGE_NAME];
+    if (fromDev == null) devDeps[PACKAGE_NAME] = fromDep;
+    if (Object.keys(deps).length === 0) delete destPkg.dependencies;
+  }
+  if (devDeps[PACKAGE_NAME] == null && srcPkg?.name === PACKAGE_NAME && srcPkg.version) {
+    devDeps[PACKAGE_NAME] = srcPkg.version;
+  }
+}
+
+/** The skill packs of a `--packs` list (comma separated, `none` or empty for no packs), once each in `SKILL_PACKS` order; an unknown name throws. */
+export function parsePacksFlag(value: string): string[] {
+  const text = value.trim();
+  if (!text || text === "none") return [];
+  const names = text
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+  for (const name of names) {
+    if (!SKILL_PACKS.some((pack) => pack === name)) throw new Error(`unknown pack ${name}`);
+  }
+  return SKILL_PACKS.filter((pack) => names.includes(pack));
+}
+
+const SYNC_POSTINSTALL = "repo sync --postinstall";
+
+/** Write `workerstack.config.ts`, formatted as oxfmt would, with the default packs (agents, standards and docs), every host and the chosen skill packs, only when the repo has no config. */
+export function writeConfigIfMissing(dest: string, skills: readonly string[] = []): void {
+  const configPath = path.join(dest, CONFIG_FILE);
+  if (fs.existsSync(configPath)) return;
+  const list = (names: readonly string[]) => names.map((n) => JSON.stringify(n)).join(", ");
+  const keys = [`hosts: [${list(HOSTS)}]`, ...(skills.length > 0 ? [`skills: [${list(skills)}]`] : [])];
+  // Laid out as the standards pack's oxfmt would: one line while it fits the width, else one key per line.
+  const inline = `  agents: { ${keys.join(", ")} },`;
+  const agents =
+    inline.length <= PRINT_WIDTH ? inline : `  agents: {\n${keys.map((key) => `    ${key},\n`).join("")}  },`;
+  fs.writeFileSync(
+    configPath,
+    `import { defineConfig } from "${PACKAGE_NAME}";\n\nexport default defineConfig({\n  packs: [${list(defaultPacks())}],\n${agents}\n});\n`,
+  );
+}
+
+/** The root keys `repo check` requires; a value already there stays, even one check would fail. */
+function defaultManifestKeys(pkg: PackageJson) {
+  pkg.private ??= true;
+  // A root with workspaces is not a package, so `repo check` does not ask it for sideEffects.
+  if (pkg.workspaces === undefined) pkg.sideEffects ??= false;
+  pkg.packageManager ??= `bun@${Bun.version}`;
+}
+
+/**
+ * Put the postinstall that runs `repo sync` and the `@workerstack/repo` devDependency into the repo's
+ * package.json, default `private`, `sideEffects` and `packageManager` when absent, and drop the `repo:*` scripts an older init copied while they still hold a value it wrote.
+ */
+export function mergePackageJson(dest: string, pkgRoot: string): void {
+  const destPath = path.join(dest, "package.json");
+  let destPkg: PackageJson = {};
+  if (fs.existsSync(destPath)) {
+    destPkg = readJsonFile(destPath, isPackageJson);
+  }
+  if (destPkg.name === PACKAGE_NAME) return;
+
+  const srcPkg = readJsonFile(path.join(pkgRoot, "package.json"), isPackageJson);
+  const destScripts: Record<string, string> = { ...(destPkg.scripts || {}) };
+  for (const [name, value] of Object.entries(destScripts)) {
+    if (OLD_DEFAULT_SCRIPTS[name]?.includes(value)) delete destScripts[name];
+  }
+  const postinstall = destScripts.postinstall;
+  if (postinstall == null) destScripts.postinstall = SYNC_POSTINSTALL;
+  else if (!postinstall.includes("repo sync")) destScripts.postinstall = `${SYNC_POSTINSTALL} && ${postinstall}`;
+  placeDevDependency(destPkg, srcPkg);
+  defaultManifestKeys(destPkg);
+  destPkg.scripts = sortKeys(destScripts);
+  destPkg.devDependencies = sortKeys(destPkg.devDependencies!);
+  fs.writeFileSync(destPath, `${JSON.stringify(destPkg, null, 2)}\n`);
+}
+
+export interface InitOptions {
+  pkgRoot?: string;
+  execFileSync?: (cmd: string, args: string[], opts: import("node:child_process").ExecFileSyncOptions) => unknown;
+  skipGlobals?: boolean;
+  onPhase?: (name: string, state: "start" | "stop") => void;
+  /** Skill packs written as `agents.skills` into a new config. */
+  packs?: string[];
+}
+
+/**
+ * Write the config and package.json entries a repo needs, install, and apply the global settings. The agent
+ * trees are not copied: the postinstall of `bun install` runs `repo sync`, which generates them.
+ * @param dest Workspace to initialise.
+ * @param [options]
+ * @returns
+ */
+export function init(
+  dest: string,
+  { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync, skipGlobals = false, onPhase, packs }: InitOptions = {},
+): void {
+  dest = path.resolve(dest);
+  const pkgRoot = path.resolve(pkgRootOpt ?? PKG_ROOT);
+  // This package is its own workspace: nothing to write, install or apply.
+  if (samePath(dest, pkgRoot)) return;
+
+  onPhase?.("merge", "start");
+  try {
+    mergePackageJson(dest, pkgRoot);
+    writeConfigIfMissing(dest, packs);
+  } finally {
+    onPhase?.("merge", "stop");
+  }
+
+  const bun = (name: string, args: string[]) => {
+    onPhase?.(name, "start");
+    onPhase?.(name, "stop");
+    exec("bun", args, { cwd: dest, stdio: "inherit" });
+  };
+  bun("install", ["install"]);
+  if (!skipGlobals) bun("yolo", ["repo", "yolo"]);
+}

package/cli/knip-check-ignores.test.ts

@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { answering, knipRoot, removeKnipRoots, report } from "./fixtures/knip-run.ts";
+import { checkKnip } from "./knip-check.ts";
+import type { KnipIgnore } from "./knip-schema.ts";
+
+afterEach(removeKnipRoots);
+
+const item = { name: "oxlint", line: 1, col: 1, pos: 0 };
+const dep = (reason = "spawned by path"): KnipIgnore => ({ dependency: "oxlint", reason });
+
+/** Checks `ignores` against `issues` in a root with `files` and a manifest depending on oxlint. */
+function check(ignores: KnipIgnore[], issues: Record<string, unknown>[], files: Record<string, string> = {}) {
+  return checkKnip(knipRoot(files, { oxlint: "1" }), ignores, answering(report(...issues)));
+}
+
+describe("an ignore matched by issues", () => {
+  it("is no problem and is reported with its reason", () => {
+    const out = check([dep()], [{ file: "package.json", dependencies: [item] }]);
+    expect(out).toEqual({ report: ["knip: 1 ignore: dependency oxlint (spawned by path)"], problems: [] });
+  });
+
+  it("a dependency entry takes the unused, dev, optional peer and unlisted issues of that name only", () => {
+    const issues = [
+      { file: "package.json", devDependencies: [item], optionalPeerDependencies: [item], dependencies: [item] },
+      { file: "a.ts", unlisted: [item, { ...item, name: "other" }], binaries: [item] },
+    ];
+    expect(check([dep()], issues).problems).toEqual([
+      'knip: a.ts: unlisted dependency "other"; add it to package.json',
+      'knip: a.ts: unlisted binary "oxlint"; add the package that provides it to package.json',
+    ]);
+  });
+
+  it("a binary entry takes the binaries of that name", () => {
+    const out = check(
+      [{ binary: "oxlint", reason: "run by a hook" }],
+      [{ file: "a.ts", binaries: [item, { ...item, name: "tsc" }], dependencies: [item] }],
+    );
+    expect(out.report).toEqual(["knip: 1 ignore: binary oxlint (run by a hook)"]);
+    expect(out.problems).toEqual([
+      'knip: a.ts: unused dependency "oxlint"; remove it',
+      'knip: a.ts: unlisted binary "tsc"; add the package that provides it to package.json',
+    ]);
+  });
+});
+
+describe("an ignore matched by files and several entries", () => {
+  it("a file entry takes every issue of the files its path or glob matches", () => {
+    const issues = [
+      { file: "src/old.ts", exports: [item], files: [{ name: "src/old.ts" }] },
+      { file: "src/new.ts", exports: [item] },
+    ];
+    const out = check([{ file: "src/old*.ts", reason: "loaded by name" }], issues, { "src/old.ts": "" });
+    expect(out.report).toEqual(["knip: 1 ignore: file src/old*.ts (loaded by name)"]);
+    expect(out.problems).toEqual(['knip: src/new.ts: unused export "oxlint"; delete it or stop exporting it']);
+  });
+
+  it("several entries make one line, plural", () => {
+    const issues = [
+      { file: "package.json", dependencies: [item] },
+      { file: "b.ts", binaries: [item] },
+    ];
+    const out = check([dep("r1"), { binary: "oxlint", reason: "r2" }], issues);
+    expect(out.report).toEqual(["knip: 2 ignores: dependency oxlint (r1), binary oxlint (r2)"]);
+  });
+});
+
+describe("a stale entry", () => {
+  it("a file that no longer exists is stale before the run", () => {
+    const out = check([{ file: "src/old.ts", reason: "r" }], [{ file: "src/old.ts", exports: [item] }]);
+    expect(out.problems).toEqual(["knip.ignore[0]: src/old.ts no longer exists; delete the entry"]);
+  });
+
+  it("a dependency in no package.json is stale before the run", () => {
+    const out = check([{ dependency: "left-pad", reason: "r" }], []);
+    expect(out.problems).toEqual(['knip.ignore[0]: dependency "left-pad" is in no package.json; delete the entry']);
+  });
+});
+
+describe("a stale entry once knip has run", () => {
+  it("a dependency of a workspace package is in a package.json", () => {
+    const ws = knipRoot({});
+    const manifest = { name: "a", devDependencies: { "left-pad": "1" } };
+    const stdout = report({ file: "a/package.json", devDependencies: [{ name: "left-pad" }] });
+    const out = checkKnip(
+      { ...ws, packages: [{ dir: "a", manifest }] },
+      [{ dependency: "left-pad", reason: "r" }],
+      answering(stdout),
+    );
+    expect(out.problems).toEqual([]);
+  });
+
+  it("an entry that matches no issue is stale after the run", () => {
+    const issues = [{ file: "b.ts", exports: [item] }];
+    const out = check([dep(), { file: "a.ts", reason: "r" }, { binary: "tsc", reason: "r" }], issues, {
+      "a.ts": "",
+      "b.ts": "",
+    });
+    expect(out.problems).toEqual([
+      'knip: b.ts: unused export "oxlint"; delete it or stop exporting it',
+      'knip.ignore[0]: dependency "oxlint" has no knip issue any more; delete the entry',
+      'knip.ignore[1]: file "a.ts" has no knip issue any more; delete the entry',
+      'knip.ignore[2]: binary "tsc" has no knip issue any more; delete the entry',
+    ]);
+    expect(out.report).toEqual([]);
+  });
+});

package/cli/knip-check-real.test.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { knipRoot, removeKnipRoots } from "./fixtures/knip-run.ts";
+import { checkKnipAt } from "./knip-check.ts";
+
+afterEach(removeKnipRoots);
+
+const SLOW = 120_000;
+const INSTALL = path.join(import.meta.dirname, "..", "node_modules");
+
+it(
+  "runs the real knip on a planted repo: an unused export and dependency fail, an ignore reports",
+  {
+    timeout: SLOW,
+  },
+  async () => {
+    const files = {
+      "src/index.ts": 'import { used } from "./lib.ts";\nconsole.log(used);\n',
+      "src/lib.ts": "export const used = 1;\nexport const unused = 2;\n",
+      "src/old.ts": "export const old = 1;\n",
+    };
+    const ws = knipRoot(files, { "left-pad": "1.0.0" });
+    fs.symlinkSync(INSTALL, path.join(ws.root, "node_modules"), "junction");
+    fs.writeFileSync(path.join(ws.root, "package.json"), JSON.stringify({ ...ws.manifest, main: "src/index.ts" }));
+    const ignore = '{ file: "src/old.ts", reason: "loaded by name" }';
+    fs.writeFileSync(
+      path.join(ws.root, "workerstack.config.ts"),
+      `export default { packs: ["standards"], knip: { ignore: [${ignore}] } };\n`,
+    );
+    const out = await checkKnipAt(ws.root);
+    expect(out.report).toEqual(["knip: 1 ignore: file src/old.ts (loaded by name)"]);
+    expect(out.problems.toSorted()).toEqual([
+      'knip: package.json: unused dependency "left-pad"; remove it',
+      'knip: src/lib.ts: unused export "unused"; delete it or stop exporting it',
+    ]);
+    expect(fs.readdirSync(ws.root).filter((name) => name.startsWith("knip."))).toEqual([]);
+  },
+);
+
+it(
+  "keeps knip's default entries: src/index.ts and what it imports are used with no main",
+  { timeout: SLOW },
+  async () => {
+    const files = {
+      "src/index.ts": 'import { answer } from "./answer.ts";\nconsole.log(answer);\n',
+      "src/answer.ts": "export const answer = 42;\n",
+    };
+    const ws = knipRoot(files, {});
+    fs.symlinkSync(INSTALL, path.join(ws.root, "node_modules"), "junction");
+    fs.writeFileSync(path.join(ws.root, "workerstack.config.ts"), 'export default { packs: ["standards"] };\n');
+    const out = await checkKnipAt(ws.root);
+    expect(out.problems).toEqual([]);
+  },
+);
+
+it("does not report @workerstack/repo as unused when the config does not import it", { timeout: SLOW }, async () => {
+  const ws = knipRoot({ "src/index.ts": "export {};\n" }, {});
+  fs.symlinkSync(INSTALL, path.join(ws.root, "node_modules"), "junction");
+  const manifest = { name: "app", type: "module", devDependencies: { "@workerstack/repo": "1.0.0" } };
+  fs.writeFileSync(path.join(ws.root, "package.json"), JSON.stringify(manifest));
+  fs.writeFileSync(path.join(ws.root, "workerstack.config.ts"), 'export default { packs: ["standards"] };\n');
+  const out = await checkKnipAt(ws.root);
+  expect(out.problems).toEqual([]);
+});

package/cli/knip-check.constants.ts

@@ -0,0 +1,46 @@
+/** knip's exit code for a config it cannot run with. */
+export const EXIT_BAD_CONFIG = 2;
+/** How many of knip's last stderr lines a failure problem quotes. */
+export const STDERR_LINES = 3;
+
+/** How a problem line names one issue type: what is wrong, and what fixes it. */
+export type Wording = { type: string; label: string; fix: string };
+
+/** The issue type of a file nothing imports, which names no export. */
+export const FILES_TYPE = "files";
+/** The issue type of a command no manifest provides. */
+export const BINARIES_TYPE = "binaries";
+const DELETE_OR_UNEXPORT = "delete it or stop exporting it";
+const REMOVE = "remove it";
+const ADD_TO_MANIFEST = "add it to package.json";
+
+/** Every issue type knip 6.43.0 reports, in the order a file's issues are printed. */
+export const WORDINGS: readonly Wording[] = [
+  { type: FILES_TYPE, label: "unused file", fix: "delete it" },
+  { type: "dependencies", label: "unused dependency", fix: REMOVE },
+  { type: "devDependencies", label: "unused devDependency", fix: REMOVE },
+  { type: "optionalPeerDependencies", label: "unused optional peer dependency", fix: REMOVE },
+  { type: "unlisted", label: "unlisted dependency", fix: ADD_TO_MANIFEST },
+  { type: BINARIES_TYPE, label: "unlisted binary", fix: "add the package that provides it to package.json" },
+  { type: "unresolved", label: "unresolved import", fix: "fix the path or install the package" },
+  { type: "exports", label: "unused export", fix: DELETE_OR_UNEXPORT },
+  { type: "nsExports", label: "unused namespace export", fix: DELETE_OR_UNEXPORT },
+  { type: "types", label: "unused type", fix: DELETE_OR_UNEXPORT },
+  { type: "nsTypes", label: "unused namespace type", fix: DELETE_OR_UNEXPORT },
+  { type: "enumMembers", label: "unused enum member", fix: "delete it" },
+  { type: "namespaceMembers", label: "unused namespace member", fix: "delete it" },
+  { type: "duplicates", label: "duplicate export", fix: "export it under one name" },
+  { type: "catalog", label: "unused catalog entry", fix: REMOVE },
+  { type: "catalogReferences", label: "unresolved catalog reference", fix: "add it to the catalog" },
+  { type: "cycles", label: "circular import", fix: "break the cycle" },
+];
+
+/** The issue types a `dependency` ignore covers. */
+export const DEPENDENCY_TYPES: readonly string[] = [
+  "dependencies",
+  "devDependencies",
+  "optionalPeerDependencies",
+  "unlisted",
+];
+/** The manifest fields a dependency can be declared in. */
+export const MANIFEST_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"] as const;

package/cli/knip-check.test.ts

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { answering, knipRoot, removeKnipRoots, report } from "./fixtures/knip-run.ts";
+import { checkKnip, checkKnipAt } from "./knip-check.ts";
+import { knipConfig } from "./sync/knip-config.ts";
+
+afterEach(removeKnipRoots);
+
+const run = (issues: Record<string, unknown>[]) => checkKnip(knipRoot({}), [], answering(report(...issues)));
+const item = { name: "x", line: 1, col: 1, pos: 0 };
+
+describe("one problem line per issue type", () => {
+  it.each([
+    ["files", { name: "cli/x.ts" }, "knip: cli/x.ts: unused file; delete it"],
+    ["dependencies", item, 'knip: cli/x.ts: unused dependency "x"; remove it'],
+    ["devDependencies", item, 'knip: cli/x.ts: unused devDependency "x"; remove it'],
+    ["optionalPeerDependencies", item, 'knip: cli/x.ts: unused optional peer dependency "x"; remove it'],
+    ["unlisted", item, 'knip: cli/x.ts: unlisted dependency "x"; add it to package.json'],
+    ["binaries", item, 'knip: cli/x.ts: unlisted binary "x"; add the package that provides it to package.json'],
+    ["unresolved", item, 'knip: cli/x.ts: unresolved import "x"; fix the path or install the package'],
+    ["exports", item, 'knip: cli/x.ts: unused export "x"; delete it or stop exporting it'],
+    ["nsExports", item, 'knip: cli/x.ts: unused namespace export "x"; delete it or stop exporting it'],
+    ["types", item, 'knip: cli/x.ts: unused type "x"; delete it or stop exporting it'],
+    ["nsTypes", item, 'knip: cli/x.ts: unused namespace type "x"; delete it or stop exporting it'],
+    ["enumMembers", { ...item, namespace: "E" }, 'knip: cli/x.ts: unused enum member "E.x"; delete it'],
+    ["namespaceMembers", { ...item, namespace: "n" }, 'knip: cli/x.ts: unused namespace member "n.x"; delete it'],
+    ["duplicates", item, 'knip: cli/x.ts: duplicate export "x"; export it under one name'],
+    ["catalog", item, 'knip: cli/x.ts: unused catalog entry "x"; remove it'],
+    ["catalogReferences", item, 'knip: cli/x.ts: unresolved catalog reference "x"; add it to the catalog'],
+    ["cycles", item, 'knip: cli/x.ts: circular import "x"; break the cycle'],
+  ])("%s", (type, entry, line) => {
+    expect(run([{ file: "cli/x.ts", [type]: [entry] }])).toEqual({ report: [], problems: [line] });
+  });
+});
+
+it("reports each issue of each file in order, and nothing for a clean run", () => {
+  const manifest = { file: "package.json", dependencies: [{ name: "left-pad" }] };
+  const source = { file: "cli/x.ts", exports: [item, { ...item, name: "y" }] };
+  expect(run([manifest, source]).problems).toEqual([
+    'knip: package.json: unused dependency "left-pad"; remove it',
+    'knip: cli/x.ts: unused export "x"; delete it or stop exporting it',
+    'knip: cli/x.ts: unused export "y"; delete it or stop exporting it',
+  ]);
+  expect(run([])).toEqual({ report: [], problems: [] });
+});
+
+describe("a knip that did not report", () => {
+  const TAIL = "run `bun repo sync` and check knip.json";
+
+  it("exit 2 is one problem naming the tail of its stderr", () => {
+    const out = checkKnip(knipRoot({}), [], answering("", 2, "a\nb\nc\nd\n"));
+    expect(out).toEqual({ report: [], problems: [`knip: exited 2: b c d; ${TAIL}`] });
+  });
+
+  it("output that is not knip's json is one problem", () => {
+    const out = checkKnip(knipRoot({}), [], answering("not json", 0, "boom"));
+    expect(out).toEqual({ report: [], problems: [`knip: exited 0: boom; ${TAIL}`] });
+    expect(checkKnip(knipRoot({}), [], answering('{"issues":3}')).problems).toHaveLength(1);
+  });
+});
+
+describe("the unignored config", () => {
+  it("is written beside knip.json for the run from the workspace without ignores, and removed after", () => {
+    const ws = knipRoot({});
+    const name = `knip.unignored-${process.pid}.json`;
+    let seen = "";
+    const out = checkKnip(ws, [{ file: "gone.ts", reason: "r" }], (args, cwd) => {
+      seen = fs.readFileSync(path.join(ws.root, name), "utf8");
+      expect(args.slice(-5)).toEqual(["--config", name, "--no-exit-code", "--reporter", "json"]);
+      expect(cwd).toBe(ws.root);
+      return { code: 0, stdout: report(), stderr: "" };
+    });
+    expect(seen).toBe(knipConfig(ws, []));
+    expect(fs.existsSync(path.join(ws.root, name))).toBe(false);
+    expect(out.problems).toHaveLength(1);
+  });
+
+  it("is removed when the runner throws", () => {
+    const ws = knipRoot({});
+    const boom = () => {
+      throw new Error("spawn failed");
+    };
+    expect(() => checkKnip(ws, [], boom)).toThrow("spawn failed");
+    expect(fs.readdirSync(ws.root)).toEqual(["package.json"]);
+  });
+});
+
+describe("checkKnipAt", () => {
+  const NONE = { report: [], problems: [] };
+  const pack = (root: string, body: string) =>
+    fs.writeFileSync(path.join(root, "workerstack.config.ts"), `export default ${body};\n`);
+
+  it("runs nothing without a config, without the standards pack or with an unreadable manifest", async () => {
+    const { root } = knipRoot({});
+    const runner = answering(report({ file: "a.ts", exports: [item] }));
+    expect(await checkKnipAt(root)).toEqual(NONE);
+    pack(root, '{ packs: ["docs"] }');
+    expect(await checkKnipAt(root, { run: runner })).toEqual(NONE);
+    pack(root, '{ packs: ["standards"] }');
+    fs.writeFileSync(path.join(root, "package.json"), "{");
+    expect(await checkKnipAt(root, { run: runner })).toEqual(NONE);
+    expect(runner.calls).toEqual([]);
+  });
+
+  it("runs knip with the config's ignores under the standards pack", async () => {
+    const { root } = knipRoot({ "a.ts": "export {};\n" });
+    pack(root, '{ packs: ["standards"], knip: { ignore: [{ file: "a.ts", reason: "loaded by name" }] } }');
+    const runner = answering(report({ file: "a.ts", files: [{ name: "a.ts" }] }));
+    const out = await checkKnipAt(root, { run: runner });
+    expect(out).toEqual({ report: ["knip: 1 ignore: file a.ts (loaded by name)"], problems: [] });
+    expect(runner.calls).toHaveLength(1);
+  });
+});