@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/standards.test.ts

@@ -0,0 +1,206 @@
+import { BASE_CONFIG } from "../fixtures/base-config.ts";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse, type ParseError } from "jsonc-parser";
+import { afterEach, describe, expect, it } from "vitest";
+import { CONFIG_FILE, type LintSkip, type Pack } from "../config.ts";
+import { runSync } from "../sync.ts";
+import type { Output, SyncContext } from "./outputs.ts";
+import { standards } from "./standards.ts";
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function context(packs: Pack[], name = "app", skip: readonly LintSkip[] = []): SyncContext {
+  return {
+    root: "/repo",
+    config: {
+      packs,
+      agents: { hosts: [], skills: [] },
+      ...BASE_CONFIG,
+      lint: { skip },
+    },
+    workspace: { root: "/repo", manifest: { name }, packages: [] },
+    read: () => null,
+  };
+}
+
+const file = (rel: string, tracked: boolean, managed: Output["managed"] = "whole"): Output => ({
+  kind: "file",
+  path: rel,
+  content: "x\n",
+  tracked,
+  managed,
+});
+const link = (rel: string, tracked: boolean): Output => ({
+  kind: "link",
+  path: rel,
+  target: "../x",
+  tracked,
+  managed: "whole",
+});
+
+function contentOf(outputs: readonly Output[], rel: string): unknown {
+  const found = outputs.find((output) => output.path === rel);
+  if (found?.kind !== "file") throw new Error(`no file output ${rel}`);
+  const errors: ParseError[] = [];
+  const value: unknown = parse(found.content, errors, { allowTrailingComma: true });
+  if (errors.length > 0) throw new Error(`${rel} does not parse`);
+  return value;
+}
+
+describe("the standards pass", () => {
+  it("writes the oxlint config of the workspace: the repo plugin, and a package bin's override", () => {
+    const ctx = context(["standards"]);
+    ctx.workspace.packages.push({ dir: "packages/cli", manifest: { bin: "./bin/cli.ts" } });
+    const { outputs, errors } = standards(ctx, []);
+    expect(errors).toEqual([]);
+    const config = contentOf(outputs, ".oxlintrc.json") as { jsPlugins: unknown; overrides: unknown[] };
+    expect(config.jsPlugins).toEqual([{ name: "repo", specifier: "@workerstack/repo/lint" }]);
+    expect(config.overrides).toContainEqual({
+      files: ["packages/cli/bin/cli.ts"],
+      rules: { "repo/no-module-side-effects": "off" },
+    });
+  });
+
+  it("writes each lint.skip entry as the last override, and refuses a rule the config never runs with no output", () => {
+    const reason = "the parsed config cache lives for the process";
+    const live = { files: ["src/cache.ts"], rules: ["repo/no-module-state"], reason };
+    const { outputs, errors } = standards(context(["standards"], "app", [live]), []);
+    expect(errors).toEqual([]);
+    const config = contentOf(outputs, ".oxlintrc.json") /* the oxlint config always has overrides */ as {
+      overrides: unknown[];
+    };
+    expect(config.overrides.at(-1)).toEqual({ files: ["src/cache.ts"], rules: { "repo/no-module-state": "off" } });
+
+    const typo = { ...live, rules: ["repo/no-modul-state"] };
+    expect(standards(context(["standards"], "app", [typo]), [])).toEqual({
+      outputs: [],
+      errors: [
+        'workerstack.config.ts: lint.skip[0].rules: "repo/no-modul-state" is not a rule the generated config runs',
+      ],
+    });
+  });
+
+  it("writes the oxfmt config: width 120, package.json left unsorted, no trailing commas in JSONC, markdown and fixtures ignored", () => {
+    const { outputs } = standards(context(["standards"]), []);
+    expect(contentOf(outputs, ".oxfmtrc.jsonc")).toEqual({
+      printWidth: 120,
+      sortPackageJson: false,
+      overrides: [{ files: ["**/*.jsonc"], options: { trailingComma: "none" } }],
+      ignorePatterns: [
+        "**/*.md",
+        "**/fixtures/**",
+        "/.gitattributes",
+        "/.githooks/commit-msg",
+        "/.githooks/pre-commit",
+        "/.gitignore",
+        "/.oxfmtrc.jsonc",
+        "/.oxlintrc.json",
+        "/.vscode/settings.json",
+        "/knip.json",
+      ],
+    });
+  });
+
+  it("has oxfmt ignore every planned output of a repo that commits its trees, tracked or not, whole or block, anchored at the root", () => {
+    const planned = [
+      file("bunfig.toml", true),
+      file(".claude/settings.json", true),
+      file(".codex/hooks.json", false),
+      file("packages/api/references/INDEX.md", true, "block"),
+      link(".claude/skills/deploy", true),
+    ];
+    const { outputs } = standards(context(["agents", "standards"], "@workerstack/repo"), planned);
+    expect(contentOf(outputs, ".oxfmtrc.jsonc")).toMatchObject({
+      ignorePatterns: [
+        "**/*.md",
+        "**/fixtures/**",
+        "/.claude/settings.json",
+        "/.claude/skills/deploy",
+        "/.codex/hooks.json",
+        "/.gitattributes",
+        "/.githooks/commit-msg",
+        "/.githooks/pre-commit",
+        "/.gitignore",
+        "/.oxfmtrc.jsonc",
+        "/.oxlintrc.json",
+        "/.vscode/settings.json",
+        "/bunfig.toml",
+        "/knip.json",
+        "/packages/api/references/INDEX.md",
+      ],
+    });
+  });
+
+  it("plans both configs as sync's own, untracked files, the hooks as tracked ones, and nothing without the pack", () => {
+    const shapes = standards(context(["standards"]), []).outputs.map(({ kind, path: rel, tracked, managed }) => ({
+      kind,
+      path: rel,
+      tracked,
+      managed,
+    }));
+    expect(shapes).toEqual([
+      { kind: "file", path: ".oxlintrc.json", tracked: false, managed: "whole" },
+      { kind: "file", path: "knip.json", tracked: false, managed: "whole" },
+      { kind: "file", path: ".oxfmtrc.jsonc", tracked: false, managed: "whole" },
+      { kind: "file", path: ".githooks/commit-msg", tracked: true, managed: "whole" },
+      { kind: "file", path: ".githooks/pre-commit", tracked: true, managed: "whole" },
+    ]);
+    expect(standards(context(["agents", "docs"]), [file("bunfig.toml", true)])).toEqual({ outputs: [], errors: [] });
+  });
+});
+
+function repo(packs: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-standards-"));
+  temps.push(root);
+  fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "app" }));
+  fs.writeFileSync(path.join(root, CONFIG_FILE), `export default { packs: ${packs} }\n`);
+  return root;
+}
+const sync = (root: string) => runSync([], { cwd: root, stdout: () => {}, stderr: () => {} }, { generators: [] });
+
+describe("repo sync with the standards pack", () => {
+  it("writes both configs and has git ignore them, then prunes them once the pack is dropped", async () => {
+    const root = repo('["standards"]');
+    expect(await sync(root)).toBe(0);
+    expect(fs.existsSync(path.join(root, ".oxlintrc.json"))).toBe(true);
+    expect(fs.existsSync(path.join(root, ".oxfmtrc.jsonc"))).toBe(true);
+    for (const hook of ["pre-commit", "commit-msg"]) {
+      expect(fs.statSync(path.join(root, ".githooks", hook)).mode & 0o777).toBe(
+        process.platform === "win32" ? 0o666 : 0o755,
+      ); // no execute bits on win32
+    }
+    expect(fs.readFileSync(path.join(root, ".gitignore"), "utf8").split("\n")).toEqual(
+      expect.arrayContaining([".oxfmtrc.jsonc", ".oxlintrc.json", ".oxlintrc.unskipped-*.json"]),
+    );
+
+    fs.writeFileSync(path.join(root, CONFIG_FILE), "export default { packs: [] }\n");
+    expect(await sync(root)).toBe(0);
+    expect(fs.existsSync(path.join(root, ".oxlintrc.json"))).toBe(false);
+    expect(fs.existsSync(path.join(root, ".oxfmtrc.jsonc"))).toBe(false);
+    expect(fs.existsSync(path.join(root, ".githooks"))).toBe(false);
+    expect(fs.readFileSync(path.join(root, ".gitignore"), "utf8")).not.toContain(".ox");
+  });
+});
+
+describe("repo sync with the standards pack and knip", () => {
+  it("writes knip.json with the knip.ignore entries and has git ignore it and its one-run copies, then prunes it", async () => {
+    const root = repo('["standards"]');
+    const config = `export default { packs: ["standards"], knip: { ignore: [{ file: "src/old.ts", reason: "by name" }] } }\n`;
+    fs.writeFileSync(path.join(root, CONFIG_FILE), config);
+    expect(await sync(root)).toBe(0);
+    expect(JSON.parse(fs.readFileSync(path.join(root, "knip.json"), "utf8"))).toMatchObject({
+      workspaces: { ".": { ignoreFiles: ["src/old.ts"] } },
+    });
+    expect(fs.readFileSync(path.join(root, ".gitignore"), "utf8").split("\n")).toEqual(
+      expect.arrayContaining(["knip.json", "knip.unignored-*.json"]),
+    );
+    fs.writeFileSync(path.join(root, CONFIG_FILE), "export default { packs: [] }\n");
+    expect(await sync(root)).toBe(0);
+    expect(fs.existsSync(path.join(root, "knip.json"))).toBe(false);
+  });
+});

package/cli/sync/standards.ts

@@ -0,0 +1,179 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { repoBinLookup } from "../scripts/hook-command.ts";
+import { lines } from "../scripts/managed-text.ts";
+import { canonicalPath } from "../scripts/workspace-root.ts";
+import { GIT_FILE_PATHS, type PostPass } from "./git-files.ts";
+import type { Output, SyncContext } from "./outputs.ts";
+import { EXECUTABLE_MODE, INDEX_FIELDS, WINDOWS_PLATFORM } from "./standards.constants.ts";
+import { KNIP_CONFIG_PATH, knipConfig } from "./knip-config.ts";
+import { FIXTURES, OXLINT_CONFIG_PATH, oxlintConfig } from "./oxlint-config.ts";
+
+export const OXFMT_CONFIG_PATH = ".oxfmtrc.jsonc";
+/** Where the git hooks live; sync points `core.hooksPath` here. */
+const HOOKS_DIR = ".githooks";
+const HEADER = "# Generated by repo sync. Do not edit.";
+/** Each git hook and the repo command it runs, with the arguments git passes. */
+const GIT_HOOKS = { "commit-msg": 'commit-msg "$1"', "pre-commit": "turn --staged" } as const;
+const HOOK_PATHS = Object.keys(GIT_HOOKS).map((name) => `${HOOKS_DIR}/${name}`);
+/** The line width oxfmt formats to. */
+export const PRINT_WIDTH = 120;
+
+/**
+ * The oxfmt config: width 120, package.json keys left in their order, JSONC without trailing commas, and no
+ * markdown, fixture or sync output touched; each output path is anchored at the root, so it matches that file alone.
+ */
+function oxfmtConfig(planned: readonly string[]): string {
+  const outputs = [
+    ...new Set([...planned, ...GIT_FILE_PATHS, ...HOOK_PATHS, OXLINT_CONFIG_PATH, OXFMT_CONFIG_PATH, KNIP_CONFIG_PATH]),
+  ].map((rel) => `/${rel}`);
+  const config = {
+    printWidth: PRINT_WIDTH,
+    sortPackageJson: false,
+    // Hand-written JSONC (hooks, MCP policy) is read by parsers that refuse a trailing comma.
+    overrides: [{ files: ["**/*.jsonc"], options: { trailingComma: "none" } }],
+    ignorePatterns: ["**/*.md", FIXTURES, ...outputs.sort()],
+  };
+  return `// Generated by repo sync. Do not edit.\n${JSON.stringify(config, null, 2)}\n`;
+}
+
+/**
+ * The tracked, executable git hooks: each finds the bin from `.`, the worktree top level git runs hooks in, never from
+ * an agent's project dir. A hook at either path without the generated header is the user's, so sync refuses it.
+ */
+function gitHooks(ctx: SyncContext): { outputs: Output[]; errors: string[] } {
+  const outputs: Output[] = [];
+  const errors: string[] = [];
+  for (const [name, command] of Object.entries(GIT_HOOKS)) {
+    const rel = `${HOOKS_DIR}/${name}`;
+    const existing = ctx.read(rel);
+    if (existing !== null && lines(existing)[1] !== HEADER) {
+      errors.push(`${rel} is hand-written; delete it so repo sync can own it`);
+      continue;
+    }
+    const content = `#!/bin/sh\n${HEADER}\n${repoBinLookup(".")}\n"$r" ${command}\n`;
+    outputs.push({ kind: "file", path: rel, content, tracked: true, managed: "whole", executable: true });
+  }
+  return errors.length > 0 ? { outputs: [], errors } : { outputs, errors };
+}
+
+/**
+ * Under the standards pack, `.oxlintrc.json` (with an override per `lint.skip` entry), `knip.json` (with the
+ * `knip.ignore` entries) and `.oxfmtrc.jsonc`, all untracked and sync's own, and the git hooks; a hand-written hook or a skip of a rule the config never runs refuses all.
+ * It runs after the generators so oxfmt can ignore every output, and before the git files pass, whose paths it names
+ * itself and which marks the hooks generated.
+ */
+export const standards: PostPass = (ctx, outputs) => {
+  if (!ctx.config.packs.includes("standards")) return { outputs: [], errors: [] };
+  const file = (target: string, content: string): Output => ({
+    kind: "file",
+    path: target,
+    content,
+    tracked: false,
+    managed: "whole",
+  });
+  const hooks = gitHooks(ctx);
+  const oxlint = oxlintConfig(ctx.workspace, ctx.config.lint.skip);
+  const errors = [...hooks.errors, ...(oxlint.ok ? [] : oxlint.errors)];
+  if (!oxlint.ok || errors.length > 0) return { outputs: [], errors };
+  return {
+    outputs: [
+      file(OXLINT_CONFIG_PATH, oxlint.value),
+      file(KNIP_CONFIG_PATH, knipConfig(ctx.workspace, ctx.config.knip.ignore)),
+      file(OXFMT_CONFIG_PATH, oxfmtConfig(outputs.map((output) => output.path))),
+      ...hooks.outputs,
+    ],
+    errors: [],
+  };
+};
+
+/** One git command run at a root, with `input` on its stdin; `status` is null when git could not start. */
+export type GitRun = (
+  root: string,
+  args: readonly string[],
+  input?: string,
+) => { status: number | null; stdout: string; stderr: string };
+
+/** Runs git at `root`; a git that cannot start is a null status with the reason as its stderr. */
+export const runGit: GitRun = (root, args, input) => {
+  const result = spawnSync("git", [...args], { cwd: root, encoding: "utf8", input });
+  if (result.error) return { status: null, stdout: "", stderr: result.error.message };
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+};
+
+/** What the hooks path step did, for the summary line, and what it could not do, one line each. */
+export type HooksPathResult = { done: string[]; warnings: string[] };
+
+/**
+ * Converges `core.hooksPath` on the pack, in a checkout whose top level is `root`: set to the hooks when unset and the
+ * pack is on, unset when it is ours and the pack is off, and anything else left. A value pointing elsewhere while the
+ * pack is on is reported on every run, never taken over, since the user put it there.
+ */
+export function syncHooksPath(root: string, on: boolean, git: GitRun = runGit): HooksPathResult {
+  const none: HooksPathResult = { done: [], warnings: [] };
+  const top = git(root, ["rev-parse", "--show-toplevel"]);
+  if (top.status !== 0 || canonicalPath(top.stdout.trim()) !== canonicalPath(root)) return none;
+  const change = (args: string[], what: string): HooksPathResult => {
+    const result = git(root, ["config", ...args]);
+    return result.status === 0
+      ? { done: [what], warnings: [] }
+      : { done: [], warnings: [`cannot ${what}: ${result.stderr.trim()}`] };
+  };
+  const got = git(root, ["config", "--show-scope", "--get", "core.hooksPath"]);
+  if (got.status !== 0) return on ? change(["core.hooksPath", HOOKS_DIR], `set core.hooksPath to ${HOOKS_DIR}`) : none;
+  const [scope, value] = got.stdout.trim().split("\t") as [string, string];
+  if (value !== HOOKS_DIR) return on ? { done: [], warnings: [foreignLine(scope, value)] } : none;
+  return on || scope !== "local" ? none : change(["--unset", "core.hooksPath"], "unset core.hooksPath");
+}
+
+/** Whether `git ls-files -s` fields are `mode sha stage path`. */
+const isIndexRow = (fields: string[]): fields is [string, string, string, string] => fields.length === INDEX_FIELDS;
+
+/** The mode and blob of each path in `git ls-files -s` output, by path; a line of another shape is left out. */
+function indexEntries(listing: string): Map<string, { mode: string; sha: string }> {
+  const entries = new Map<string, { mode: string; sha: string }>();
+  for (const line of listing.split("\n")) {
+    const fields = line.split(/[ \t]/, INDEX_FIELDS);
+    if (!isIndexRow(fields)) continue;
+    const [mode, sha, , rel] = fields;
+    entries.set(rel, { mode, sha });
+  }
+  return entries;
+}
+
+/**
+ * On win32 git cannot see an executable bit, so `git add` records the hooks as `100644` and a Unix clone cannot run
+ * them. Sets the index mode of each hook sync wrote to `100755` (staging one git does not track yet), in a checkout
+ * whose top level is `root`. Elsewhere the file mode carries it and this does nothing.
+ */
+export function markHooksExecutable(root: string, platform: string, git: GitRun = runGit): HooksPathResult {
+  const none: HooksPathResult = { done: [], warnings: [] };
+  if (platform !== WINDOWS_PLATFORM) return none;
+  const top = git(root, ["rev-parse", "--show-toplevel"]);
+  if (top.status !== 0 || canonicalPath(top.stdout.trim()) !== canonicalPath(root)) return none;
+  const listed = git(root, ["ls-files", "-s", "--", ...HOOK_PATHS]);
+  if (listed.status !== 0) return none;
+  const entries = indexEntries(listed.stdout);
+  const todo = HOOK_PATHS.filter(
+    (rel) => entries.get(rel)?.mode !== EXECUTABLE_MODE && fs.existsSync(path.join(root, rel)),
+  );
+  if (todo.length === 0) return none;
+  // A tracked hook keeps its staged blob (`--cacheinfo`); `--add` hashes the file as it is now, for one git has not seen.
+  const results = todo.map((rel) => {
+    const entry = entries.get(rel);
+    return entry
+      ? git(root, ["update-index", "--cacheinfo", `${EXECUTABLE_MODE},${entry.sha},${rel}`])
+      : git(root, ["update-index", "--add", "--chmod=+x", "--", rel]);
+  });
+  const failed = results.find((result) => result.status !== 0);
+  return failed === undefined
+    ? { done: [`marked ${todo.join(", ")} executable in the index`], warnings: [] }
+    : { done: [], warnings: [`cannot mark the git hooks executable: ${failed.stderr.trim()}`] };
+}
+
+/** The line for a `core.hooksPath` that points elsewhere, with the command that unsets it at its scope. */
+function foreignLine(scope: string, value: string): string {
+  const flag = scope === "local" ? "" : `--${scope} `;
+  return `core.hooksPath is ${value}, so repo's hooks never run; unset it (git config ${flag}--unset core.hooksPath) and sync again`;
+}