@miroshnik/elves 0.0.0 → 2026.1018.0

package/skills/spec/scripts/spec-exceptions.ts

@@ -0,0 +1,233 @@
+#!/usr/bin/env bun
+/**
+ * spec-exceptions — moving exceptions to the "file per item" format: each `exceptions.ts` (`.mts`, `.js`, `.mjs`,
+ * `.json`) of a decision folder `tests/<kind>/<name>` or its subfolder is split into the decision folder's
+ * `exceptions/` directory — a `<item>.json` file per exception (`{ item, rule?, issue, reason }`), the old file is
+ * deleted; which file belongs where — the `exceptionFile` rule (speclib). The import in the folder's files
+ * (`import exceptions from "./exceptions.ts"`) becomes the harness's `const exceptions = exceptionsIn()`, the path to the
+ * old file in `package.json` and the CI workflow (`spec-claims --exceptions`) — the path to the directory. What can't be
+ * rewritten (a reference from another folder, no harness import) — a `!` line. A repeated run changes nothing.
+ *
+ *   bun spec-exceptions.ts [--root DIR]
+ *
+ * Codes: 0 — moved or nothing to move, 1 — something is left to fix by hand, 2 — a call error or a bad exceptions file.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+
+import { EXCEPTIONS_DIR, exceptionFile, TESTS } from "./speclib.ts";
+
+const USAGE = "spec-exceptions [--root DIR]";
+/** `--help`, `-h` (tests/standards/cli-help): the synopsis, what it does and examples; `elves` prints it under its name. */
+export const HELP = `${USAGE}
+
+Moves exceptions to the "file per item" format: each exceptions.ts of a decision folder — into its exceptions/ directory,
+a file per exception; a repeated run changes nothing. Code 0 — moved or nothing to move, 1 — something is left to fix by
+hand, 2 — a call error.
+
+Examples:
+  spec-exceptions
+  spec-exceptions --root packages/api`;
+const CODE = /\.[cm]?[jt]sx?$/;
+const SKIP_DIRS = new Set(["node_modules", ".git", EXCEPTIONS_DIR]);
+
+interface Entry {
+  item: string;
+  rule?: string;
+  issue: number;
+  reason: string;
+}
+
+/** Files under the directory (from the project root), in order; exception and dependency directories are skipped. */
+function walk(root: string, rel: string): string[] {
+  let entries;
+  try {
+    entries = readdirSync(path.join(root, rel), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .flatMap((e) => (e.isDirectory() ? (SKIP_DIRS.has(e.name) ? [] : walk(root, `${rel}/${e.name}`)) : [`${rel}/${e.name}`]))
+    .sort();
+}
+
+/** The exceptions list from the former file: JSON — parsed, a module — `default` (or `exceptions`). */
+async function loadLegacy(abs: string): Promise<unknown> {
+  if (abs.endsWith(".json")) return JSON.parse(readFileSync(abs, "utf8"));
+  const mod = (await import(pathToFileURL(abs).href)) as { default?: unknown; exceptions?: unknown };
+  return mod.default ?? mod.exceptions;
+}
+
+/** The exception file's name is the item (and the convention) in Latin letters: stable, visible in the tree and in the diff. */
+const slug = (e: Entry): string =>
+  ((e.rule ? `${e.rule}--` : "") + e.item)
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^[-.]+|-+$/g, "")
+    .slice(0, 100) || "exception";
+
+const json = (e: Entry): string =>
+  JSON.stringify({ item: e.item, ...(e.rule ? { rule: e.rule } : {}), issue: e.issue, reason: e.reason }, null, 2) + "\n";
+
+// import x from "./exceptions.ts" · import { exceptions } from … · import { exceptions as x } from … (+ with { type })
+const IMPORT = /^import\s+(?:(\w+)|\{\s*(\w+)(?:\s+as\s+(\w+))?\s*\})\s+from\s+(["'])([^"']+)\4(?:\s+with\s*\{[^}]*\})?\s*;?[ \t]*\n?/gm;
+const ANY_IMPORT = /(?:\bfrom\s*|\bimport\s*\(?\s*)(["'])([^"']+)\1/g;
+const HARNESS = /^import\s*\{([^}]*)\}\s*from\s*(["'])([^"']*\/harness(?:\.ts)?)\2/m;
+const HARNESS_TYPE = /^import\s+type\s*\{[^}]*\}\s*from\s*(["'])([^"']*\/harness(?:\.ts)?)\1\s*;?[ \t]*\n/m;
+
+/** The import path from the file points to the former exceptions file (with or without the extension). */
+function pointsTo(fromFile: string, spec: string, legacy: string): boolean {
+  if (!spec.startsWith(".")) return false;
+  const target = path.posix.join(path.posix.dirname(fromFile), spec);
+  return target === legacy || target === legacy.replace(/\.[^./]+$/, "");
+}
+
+/** The end of the last import statement at the start of the file — after its line. */
+function afterImports(text: string): number {
+  let end = 0;
+  let open = false;
+  let at = 0;
+  for (const line of text.split("\n")) {
+    const next = at + line.length + 1;
+    if (!open && /^import\b/.test(line)) open = true;
+    if (open && (/\bfrom\s*["'][^"']+["']/.test(line) || /^import\s*["'][^"']+["']/.test(line))) {
+      open = false;
+      end = Math.min(next, text.length);
+    }
+    at = next;
+  }
+  return end;
+}
+
+/** Add `exceptionsIn` to the harness import: to the value list, otherwise next to the type import; neither — null. */
+function withHarnessImport(text: string): string | null {
+  const m = HARNESS.exec(text);
+  if (m) {
+    const names = m[1]!.split(",").map((x) => x.trim()).filter(Boolean);
+    if (names.includes("exceptionsIn")) return text;
+    const sorted = names.every((x, i) => i === 0 || names[i - 1]! <= x);
+    const all = sorted ? [...names, "exceptionsIn"].sort() : [...names, "exceptionsIn"];
+    const indent = /\n([ \t]+)\S/.exec(m[1]!)?.[1];
+    const list = indent !== undefined ? `{\n${all.map((x) => `${indent}${x},`).join("\n")}\n}` : `{ ${all.join(", ")} }`;
+    return text.slice(0, m.index) + `import ${list} from ${m[2]}${m[3]}${m[2]}` + text.slice(m.index + m[0].length);
+  }
+  const t = HARNESS_TYPE.exec(text);
+  if (t) {
+    const at = t.index + t[0].length;
+    return text.slice(0, at) + `import { exceptionsIn } from ${t[1]}${t[2]}${t[1]};\n` + text.slice(at);
+  }
+  return null;
+}
+
+export async function main(argv: string[]): Promise<number> {
+  let values;
+  try {
+    ({ values } = parseArgs({ args: argv, options: { root: { type: "string" }, help: { type: "boolean", short: "h", default: false } } }));
+  } catch (e) {
+    console.error(`spec-exceptions: ${(e as Error).message}\n${USAGE}`);
+    return 2;
+  }
+  if (values.help) return console.log(HELP), 0;
+  const root = path.resolve(values.root ?? ".");
+  const files = walk(root, TESTS);
+  // former files — by the exceptionFile rule: in the decision folder or its subfolder, they move to the decision folder's directory
+  const legacyOf = (f: string) => {
+    const x = exceptionFile(f);
+    return x?.legacy ? x : null;
+  };
+  const legacy = files.filter((f) => legacyOf(f) !== null);
+  const configs = ["package.json", ...walk(root, ".github/workflows").filter((f) => /\.ya?ml$/.test(f))].filter((f) => existsSync(path.join(root, f)));
+  const out: string[] = [];
+  const manual: string[] = [];
+  const moved: string[] = [];
+
+  for (const rel of legacy) {
+    let list: unknown;
+    try {
+      list = await loadLegacy(path.join(root, rel));
+    } catch (e) {
+      console.error(`spec-exceptions: ${rel} doesn't load: ${(e as Error).message}`);
+      return 2;
+    }
+    if (!Array.isArray(list)) {
+      console.error(`spec-exceptions: ${rel} — export default [{ item, issue, reason }] is needed`);
+      return 2;
+    }
+    const bad = list.findIndex((x) => !x || typeof x !== "object" || typeof x.item !== "string");
+    if (bad >= 0) {
+      console.error(`spec-exceptions: ${rel}: entry ${bad + 1} is not an exception { item, issue, reason }`);
+      return 2;
+    }
+    const folder = legacyOf(rel)!.folder;
+    const dir = `${folder}/${EXCEPTIONS_DIR}`;
+    const written: string[] = [];
+    for (const e of list as Entry[]) {
+      const body = json(e);
+      let name = slug(e);
+      // the name is taken by another exception — a suffix; the same text — already moved
+      for (let n = 2; existsSync(path.join(root, dir, `${name}.json`)) && readFileSync(path.join(root, dir, `${name}.json`), "utf8") !== body; n++) {
+        name = `${slug(e)}-${n}`;
+      }
+      mkdirSync(path.join(root, dir), { recursive: true });
+      writeFileSync(path.join(root, dir, `${name}.json`), body);
+      written.push(`${dir}/${name}.json`);
+    }
+    rmSync(path.join(root, rel));
+    moved.push(rel);
+    out.push(`- ${rel} → ${dir}/ (${written.length})`, ...written.map((w) => `+ ${w}`));
+
+    // the import in the files of the folder and its subfolders — to exceptionsIn(): the harness finds the directory of the test's decision folder itself
+    for (const file of files.filter((f) => f.startsWith(`${folder}/`) && CODE.test(f) && f !== rel)) {
+      const text = readFileSync(path.join(root, file), "utf8");
+      const names: string[] = [];
+      const rest = text.replace(IMPORT, (all, def: string | undefined, named: string | undefined, alias: string | undefined, _q: string, spec: string) => {
+        if (!pointsTo(file, spec, rel)) return all;
+        if (named !== undefined && named !== "exceptions" && named !== "default") return all;
+        names.push(def ?? alias ?? named!);
+        return "";
+      });
+      const name = names[0];
+      if (name === undefined) continue;
+      const at = afterImports(rest);
+      const next = withHarnessImport(rest.slice(0, at) + `\nconst ${name} = exceptionsIn();\n` + rest.slice(at));
+      if (next === null) {
+        manual.push(`! ${file}: the import of ${rel} isn't replaced — no harness import, add import { exceptionsIn } and const ${name} = exceptionsIn()`);
+        continue;
+      }
+      writeFileSync(path.join(root, file), next);
+      out.push(`~ ${file}: import → exceptionsIn()`);
+    }
+  }
+
+  // the path to the former file in the project's scripts and CI (spec-claims --exceptions) — by the path to the directory
+  for (const file of configs) {
+    let text = readFileSync(path.join(root, file), "utf8");
+    for (const rel of moved) {
+      const re = new RegExp(`(?<![\\w./-])${rel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w/-])`, "g");
+      if (!re.test(text)) continue;
+      const dir = `${legacyOf(rel)!.folder}/${EXCEPTIONS_DIR}`;
+      text = text.replace(re, dir);
+      out.push(`~ ${file}: ${rel} → ${dir}`);
+    }
+    if (text !== readFileSync(path.join(root, file), "utf8")) writeFileSync(path.join(root, file), text);
+  }
+
+  // references to the moved files that the command didn't rewrite — by hand
+  for (const file of walk(root, TESTS).filter((f) => CODE.test(f))) {
+    const text = readFileSync(path.join(root, file), "utf8");
+    for (const m of text.matchAll(ANY_IMPORT)) {
+      const rel = moved.find((l) => pointsTo(file, m[2]!, l));
+      if (rel) manual.push(`! ${file}: a reference to ${rel} — replace it with the harness's exceptionsIn("${legacyOf(rel)!.folder}")`);
+    }
+  }
+
+  if (!moved.length) out.push("no exceptions.ts in decision folders — nothing to move");
+  for (const l of [...out, ...manual]) console.log(l);
+  return manual.length ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/spec/scripts/spec-publish.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+/**
+ * spec-publish — publishing the generated documentation (docs/spec) to a separate branch (spec): the branch root is the
+ * directory's contents, the commit message names the SHA it was built from. The documentation isn't committed to main:
+ * it is a derived copy of the tests, and parallel PRs would conflict in its pages and table of contents.
+ *
+ * The working copy and HEAD aren't touched: the tree is built in a temporary index, the commit — `git commit-tree` on top
+ * of the published one, the push — `<commit>:refs/heads/<branch>`. The same source — no new commit; the same contents
+ * from a new source — a commit with the same tree and a new `Source:` (the branch names the last checked main); the
+ * published `Source:` is a descendant of the new source — "already newer", the branch isn't touched. A rejected push (the
+ * branch moved by a parallel publish, a hosting failure) — a pause of `--interval` × the attempt number, the branch is
+ * re-read and the decision is made again, up to `--attempts` attempts. After the push the branch is read from the remote
+ * and compared with the directory — exactly what was built is published; a later publish already on top of our commit
+ * isn't a mismatch. `--check` — comparison only.
+ *
+ *   bun spec-publish.ts [--dir docs/spec] [--branch spec] [--remote origin] [--source <sha>] [--attempts 3] [--interval 5] [--check] [--root DIR]
+ *
+ * Codes: 0 — published, matches or already newer, 1 — the branch differs from the directory (or doesn't exist) with
+ * --check, the push was rejected on all attempts, 2 — a call error (no directory, not git). Runs under Bun, no
+ * dependencies.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { sourceOf } from "./speclib.ts";
+
+const USAGE =
+  "spec-publish [--dir docs/spec] [--branch spec] [--remote origin] [--source <sha>] [--attempts 3] [--interval 5] [--check] [--root DIR]";
+/** `--help`, `-h` (tests/standards/cli-help): the synopsis, what it does and examples; `elves` prints it under its name. */
+export const HELP = `${USAGE}
+
+Publishes the generated documentation (docs/spec) to the spec branch without touching the working copy; the commit
+names the source SHA. Code 0 — published, matches or already newer, 1 — differs with --check or the push was rejected on
+all attempts, 2 — a call error.
+
+Examples:
+  spec-publish --source "$GITHUB_SHA"
+  spec-publish --check`;
+
+// a publish commit without a configured git user (CI) — in the name of the GitHub Actions bot
+const BOT = { name: "github-actions[bot]", email: "41898282+github-actions[bot]@users.noreply.github.com" };
+
+class Fail extends Error {
+  code: number;
+  constructor(message: string, code: number) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function git(root: string, args: string[], env: Record<string, string> = {}): string {
+  return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env } }).trim();
+}
+
+function tryGit(root: string, args: string[]): string | null {
+  try {
+    return git(root, args);
+  } catch {
+    return null;
+  }
+}
+
+/** The directory's tree as a git object: a temporary index, --work-tree = the directory; the repository's .gitignore doesn't interfere (-f). */
+function treeOf(root: string, dir: string): string {
+  const tmp = mkdtempSync(path.join(os.tmpdir(), "spec-publish-"));
+  try {
+    const env = { GIT_INDEX_FILE: path.join(tmp, "index") };
+    // cwd is the directory itself: index paths from its root; git-dir is the repository's (in a worktree — its own, objects shared)
+    const gitDir = git(root, ["rev-parse", "--absolute-git-dir"]);
+    git(dir, ["--git-dir", gitDir, "--work-tree", dir, "add", "-A", "-f", "."], env);
+    return git(dir, ["--git-dir", gitDir, "write-tree"], env);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** The branch's published commit on the remote (after fetch) or null if there is no branch. */
+function remoteHead(root: string, remote: string, branch: string): string | null {
+  if (!tryGit(root, ["ls-remote", "--exit-code", "--heads", remote, branch])) return null;
+  git(root, ["fetch", "-q", remote, `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`]);
+  return git(root, ["rev-parse", `refs/remotes/${remote}/${branch}`]);
+}
+
+/** Paths by which the branch's tree differs from the directory's tree. */
+function diffPaths(root: string, a: string, b: string): string[] {
+  const out = git(root, ["diff-tree", "-r", "--name-only", "--no-commit-id", a, b]);
+  return out ? out.split("\n") : [];
+}
+
+/** Why git refused: the last stderr lines without hints — the first error line names only the command. */
+function reason(e: unknown): string {
+  const stderr = String((e as { stderr?: unknown }).stderr ?? "");
+  const lines = stderr.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("hint:"));
+  return lines.length ? lines.slice(-3).join("; ") : (e as Error).message.split("\n")[0]!;
+}
+
+function count(name: string, value: string, min: number): number {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min) throw new Fail(`--${name}: expected an integer ≥ ${min}, got «${value}»`, 2);
+  return n;
+}
+
+function identity(root: string): Record<string, string> {
+  const name = tryGit(root, ["config", "user.name"]) || BOT.name;
+  const email = tryGit(root, ["config", "user.email"]) || BOT.email;
+  return { GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email };
+}
+
+export async function main(argv: string[]): Promise<number> {
+  let opts;
+  try {
+    opts = parseArgs({
+      args: argv,
+      options: {
+        dir: { type: "string", default: path.join("docs", "spec") },
+        branch: { type: "string", default: "spec" },
+        remote: { type: "string", default: "origin" },
+        source: { type: "string" },
+        attempts: { type: "string", default: "3" },
+        interval: { type: "string", default: "5" },
+        check: { type: "boolean", default: false },
+        root: { type: "string" },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    console.error(`spec-publish: ${(e as Error).message}\n${USAGE}`);
+    return 2;
+  }
+  const v = opts.values;
+  if (v.help) return console.log(HELP), 0;
+  try {
+    const root = v.root ? path.resolve(v.root) : git(process.cwd(), ["rev-parse", "--show-toplevel"]);
+    const dir = path.resolve(root, v.dir);
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+      throw new Fail(`no directory ${v.dir} — build the documentation first: spec-doc <report> --out ${v.dir}`, 2);
+    }
+    const attempts = count("attempts", v.attempts, 1);
+    const interval = count("interval", v.interval, 0);
+    const tree = treeOf(root, dir);
+
+    if (v.check) {
+      const head = remoteHead(root, v.remote, v.branch);
+      if (!head) throw new Fail(`no branch ${v.branch} on ${v.remote} — the documentation isn't published`, 1);
+      const published = git(root, ["rev-parse", `${head}^{tree}`]);
+      if (published !== tree) throw new Fail(`${v.remote}/${v.branch} differs: ${diffPaths(root, published, tree).join(", ")}`, 1);
+      console.error(`spec-publish: ${v.remote}/${v.branch} matches ${v.dir}`);
+      return 0;
+    }
+
+    const source = v.source ?? git(root, ["rev-parse", "HEAD"]);
+    const sha = tryGit(root, ["rev-parse", "--verify", "-q", `${source}^{commit}`]);
+    const message = `spec: ${source.slice(0, 12)}\n\nSource: ${source}\n`;
+    let same = false;
+    let commit = "";
+    // a push is rejected when the branch moved between fetch and push or on a hosting failure: each attempt re-reads the
+    // branch and decides again — after a move it may turn out to be built from a descendant
+    for (let attempt = 1; ; attempt++) {
+      const head = remoteHead(root, v.remote, v.branch);
+      const published = head ? git(root, ["rev-parse", `${head}^{tree}`]) : null;
+      // publishes don't arrive in merge order (main runs are parallel): an old one isn't published on top of one built
+      // from a descendant. Comparing needs history: in a shallow clone the published source is unknown — it is published
+      const was = head ? sourceOf(git(root, ["log", "-1", "--format=%B", head])) : undefined;
+      if (was && sha && sha !== was && tryGit(root, ["merge-base", "--is-ancestor", sha, was]) !== null) {
+        console.error(`spec-publish: skipped — ${v.remote}/${v.branch} already newer: published from ${was.slice(0, 12)}`);
+        return 0;
+      }
+      same = published === tree;
+      if (same && (sha ?? source) === was) {
+        console.error(`spec-publish: no changes — ${v.remote}/${v.branch} already matches ${v.dir}`);
+        return 0;
+      }
+      // the same tree from a new source is a commit too: `Source:` names the last checked main, and spec-diff sees a gap
+      // with the diff base only after a skipped publish, not after every merge without spec changes
+      commit = git(root, ["commit-tree", tree, ...(head ? ["-p", head] : []), "-m", message], identity(root));
+      try {
+        git(root, ["push", "-q", v.remote, `${commit}:refs/heads/${v.branch}`]);
+        break;
+      } catch (e) {
+        const rejected = `push to ${v.remote}/${v.branch} rejected (attempt ${attempt} of ${attempts}): ${reason(e)}`;
+        if (attempt >= attempts) throw new Fail(rejected, 1);
+        console.error(`spec-publish: ${rejected} — re-reading the branch, retrying in ${interval * attempt} s`);
+        await new Promise((resolve) => setTimeout(resolve, interval * attempt * 1000));
+      }
+    }
+    // check what reached the reader: the branch on the remote, not our own commit. Between the push and this read the
+    // next publish may have landed on top (main runs are parallel): our commit in the branch's history is published —
+    // only a publish not older goes on top, an older one is skipped as "already newer"
+    const after = remoteHead(root, v.remote, v.branch);
+    const moved = after !== null && git(root, ["rev-parse", `${after}^{tree}`]) !== tree;
+    if (!after || (moved && tryGit(root, ["merge-base", "--is-ancestor", commit, after]) === null)) {
+      throw new Fail(`after the push ${v.remote}/${v.branch} doesn't match ${v.dir}`, 1);
+    }
+    if (same) console.error(`spec-publish: no changes — ${v.remote}/${v.branch} confirmed for ${source.slice(0, 12)}`);
+    else console.error(`spec-publish: published ${v.dir} → ${v.remote}/${v.branch} ${commit.slice(0, 12)} (from ${source.slice(0, 12)})`);
+    if (moved) console.error(`spec-publish: ${v.remote}/${v.branch} has moved on since — a later publish on top: ${after.slice(0, 12)}`);
+    return 0;
+  } catch (e) {
+    if (e instanceof Fail) {
+      console.error(`spec-publish: ${e.message}`);
+      return e.code;
+    }
+    console.error(`spec-publish: ${(e as Error).message}`);
+    return 2;
+  }
+}
+
+if (import.meta.main) {
+  process.exitCode = await main(process.argv.slice(2));
+}