@intentset/cli 0.1.0

package/src/git.ts

@@ -0,0 +1,81 @@
+/**
+ * The git reads `review` needs: a base to compare with and the files changed
+ * since it. Every call is a read and passes --no-optional-locks, so not even
+ * git's own index refresh is written (invariant 7). Paths come back relative
+ * to the repository root the CLI is working in, which may be a subdirectory
+ * of the git work tree.
+ */
+import { execFileSync } from "node:child_process";
+import { compareStrings } from "@intentset/core";
+
+function git(root: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", ["--no-optional-locks", ...args], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 256 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+}
+
+function paths(out: string | null): string[] {
+  return out === null ? [] : out.split("\0").filter((path) => path !== "");
+}
+
+export interface Base {
+  /** How the base was chosen, for the report: the ref given, "merge-base with main", or "HEAD~1". */
+  ref: string;
+  commit: string;
+}
+
+export interface Changes {
+  base: Base | null;
+  /** Why there is no base, when there is none. */
+  baseUnavailable?: string;
+  /** Changed between the base and HEAD, sorted. */
+  committed: string[];
+  /** Changed in the working tree or index against HEAD, and untracked files .gitignore does not exclude, sorted. */
+  uncommitted: string[];
+}
+
+/** The commit a ref names, or null. */
+export function resolveCommit(root: string, ref: string): string | null {
+  const out = git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  return out === null || out.trim() === "" ? null : out.trim();
+}
+
+/**
+ * The base: `given` when there is one (null when it names no commit), else
+ * the merge-base with main when that is not HEAD itself, else HEAD~1.
+ */
+export function chooseBase(root: string, given: string | undefined): Base | null | { unavailable: string } {
+  if (given !== undefined) {
+    const commit = resolveCommit(root, given);
+    return commit === null ? null : { ref: given, commit };
+  }
+  const head = resolveCommit(root, "HEAD");
+  if (head === null) return { unavailable: "the repository has no commit at HEAD" };
+  const mergeBase = git(root, ["merge-base", "HEAD", "main"])?.trim();
+  if (mergeBase !== undefined && mergeBase !== "" && mergeBase !== head) {
+    return { ref: "merge-base with main", commit: mergeBase };
+  }
+  const parent = resolveCommit(root, "HEAD~1");
+  if (parent !== null) return { ref: "HEAD~1", commit: parent };
+  return { unavailable: "HEAD has no parent and no merge-base with main differs from it" };
+}
+
+export function changedFiles(root: string, base: Base | null): Omit<Changes, "base" | "baseUnavailable"> {
+  const committed =
+    base === null ? [] : paths(git(root, ["diff", "--relative", "--name-only", "-z", `${base.commit}...HEAD`]));
+  const uncommitted = [
+    ...paths(git(root, ["diff", "--relative", "--name-only", "-z", "HEAD"])),
+    ...paths(git(root, ["ls-files", "-z", "--others", "--exclude-standard"])),
+  ];
+  return {
+    committed: [...new Set(committed)].sort(compareStrings),
+    uncommitted: [...new Set(uncommitted)].sort(compareStrings),
+  };
+}

package/src/glob.ts

@@ -0,0 +1,58 @@
+/**
+ * The pattern language of `.intentset/config.yaml` scope and ignore lists,
+ * which is VSA §3's: repository-relative POSIX paths made of literal segments,
+ * `*` within one segment, and `**` across zero or more segments. Nothing else
+ * is special: no `?`, no classes, no braces, no negation, so there is no
+ * precedence to explain. A pattern and a path match segment by segment, and
+ * `*` never crosses a `/`.
+ *
+ * The architecture package has its own copy for claims. Duplicating thirty
+ * lines keeps the CLI's core commands independent of it.
+ */
+
+/** VSA §3: true when the repository-relative POSIX `path` matches `pattern`. */
+export function matchGlob(pattern: string, path: string): boolean {
+  const p = normalize(pattern).split("/");
+  const s = path.split("/");
+  // Memo of (pattern index, path index) pairs already known not to match, so
+  // several `**` in one pattern stay polynomial rather than exponential.
+  const failed = new Set<number>();
+  const width = s.length + 1;
+  const match = (i: number, j: number): boolean => {
+    if (failed.has(i * width + j)) return false;
+    let ok: boolean;
+    if (i === p.length) ok = j === s.length;
+    else if (p[i] === "**") ok = match(i + 1, j) || (j < s.length && match(i, j + 1));
+    else ok = j < s.length && matchSegment(p[i], s[j]) && match(i + 1, j + 1);
+    if (!ok) failed.add(i * width + j);
+    return ok;
+  };
+  return match(0, 0);
+}
+
+/** True when any of `patterns` matches `path`. */
+export function matchAny(patterns: readonly string[], path: string): boolean {
+  return patterns.some((pattern) => matchGlob(pattern, path));
+}
+
+/** A leading `./` names the same path; repeated `/` separate nothing. */
+function normalize(pattern: string): string {
+  return pattern.replace(/^(?:\.\/)+/, "").replace(/\/{2,}/g, "/");
+}
+
+const SEGMENTS = new Map<string, RegExp>();
+
+/** One segment: literal text, with each `*` standing for any run of characters other than `/`. */
+function matchSegment(pattern: string, name: string): boolean {
+  if (!pattern.includes("*")) return pattern === name;
+  let regex = SEGMENTS.get(pattern);
+  if (regex === undefined) {
+    const body = pattern
+      .split("*")
+      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+      .join("[^/]*");
+    regex = new RegExp(`^${body}$`);
+    SEGMENTS.set(pattern, regex);
+  }
+  return regex.test(name);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @intentset/cli as a library: `main` for running the command in-process,
+ * and the repository loader and pattern matcher it is built on.
+ */
+export { main, USAGE } from "./main.ts";
+export type { Io } from "./output.ts";
+export { matchAny, matchGlob } from "./glob.ts";
+export { CONFIG_PATH, enumerate, findRoot, loadRepository, readCommit, type Repository } from "./repository.ts";

package/src/intentset.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { main } from "./main.ts";
+
+// The first SIGINT or SIGTERM asks a long-running command (serve, mcp) to stop
+// cleanly; the listener is removed as it fires, so a second one terminates.
+const controller = new AbortController();
+for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => controller.abort());
+
+const code = await main(process.argv.slice(2), {
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+  cwd: process.cwd(),
+  signal: controller.signal,
+});
+process.exitCode = code;

package/src/main.ts

@@ -0,0 +1,408 @@
+/**
+ * The `intentset` command: argument parsing, dispatch and exit codes, with
+ * every command's work in commands/. `main` returns the exit code rather than
+ * exiting, so tests run it in-process with captured io.
+ *
+ * Exit codes (Core §11, ADR 0004): 0 no errors, 1 validation errors, 2
+ * invocation or tool failure. validate, graph, architecture check, impact,
+ * context, review, serve and mcp never write; graph --out, architecture
+ * check --write-baseline, evidence import --out, publish --out and serve
+ * --out write only what they name; init only creates.
+ */
+import { parseArgs } from "node:util";
+import type { Mode } from "@intentset/architecture";
+import { LEVELS, type Level } from "@intentset/core";
+import type { RunScope } from "@intentset/verification";
+import { architectureCommand } from "./commands/architecture.ts";
+import { contextCommand } from "./commands/context.ts";
+import { evidenceImportCommand, evidenceUsageProblem } from "./commands/evidence.ts";
+import { graphCommand, graphUsageProblem, parseRelease } from "./commands/graph.ts";
+import { impactCommand } from "./commands/impact.ts";
+import { initCommand } from "./commands/init.ts";
+import { mcpCommand, mcpUsageProblem } from "./commands/mcp.ts";
+import { publishCommand, publishUsageProblem } from "./commands/publish.ts";
+import { reviewCommand } from "./commands/review.ts";
+import { serveCommand } from "./commands/serve.ts";
+import { validateCommand } from "./commands/validate.ts";
+import type { Io } from "./output.ts";
+import { type CarrierName, CARRIERS, findRoot } from "./repository.ts";
+import { EVIDENCE_DIR, evidenceFiles, openSession, type SessionOptions } from "./session.ts";
+
+export type { Io } from "./output.ts";
+
+export const USAGE = `usage: intentset <command> [options]
+
+commands
+  init [--repository <name>] [--example]
+                            create .intentset/config.yaml and an empty .intentset/registries.yaml;
+                            --example adds the scheduling example under product/scheduling/.
+                            Never overwrites a file.
+  validate                  every check the level asks for; exit 1 when any diagnostic is an error
+  graph [--format json] [--include-bodies] [--release <product>:<label>] [--out <file>]
+        [--generated-at <time>]
+                            print the intentset/export/0.1 envelope, or write it to --out
+  architecture check [--mode migration|strict] [--baseline <file>] [--write-baseline <file>]
+                            ownership, claims, imports, layers and regions (default level L2)
+  evidence import --from vitest|node-tap <report> --out <file> --product <ID> --release <label>
+        [--environment <text>] [--started-at <time>] [--finished-at <time>] [--uri-base <uri>]
+        [--tool-version <v>]
+                            turn a test report into run records bound to this commit and graph
+  impact <ID>               what depends on an artifact: direct, candidates, review context, ancestors
+  context <ID> [--include-restricted]
+                            the bounded engineering context of an artifact, with paths and bodies
+  review [--base <ref>]     the local review report: checks, coverage, and the impact of what changed
+  publish --visibility <v> --audience <a> --product <ID> --release <r> --role <r> --edition <e>
+        [--flag <f>]... [--authorized-internal] [--authorized-restricted] --out <dir> [--html]
+        [--published-at <time>]
+                            reviewed knowledge for one audience and release, as Markset with provenance
+  serve [--port <n>] [--host <address>] [--out <dir>]
+                            the Atlas, the internal review pages, on http://127.0.0.1:3000/ (rebuilt
+                            when a file changes), or written to --out; runs at L2, or L3 with run records
+  mcp --mode engineering [--include-restricted]
+  mcp --mode customer --visibility <public|customer> --audience <a> --product <ID> --release <r>
+        --role <r> --edition <e> [--flag <f>]...
+                            the read-only MCP server on stdio: the engineering graph, or one
+                            publication made in memory as publish makes it, and nothing else
+
+options
+  --root <dir>              repository root (default: the nearest directory at or above this one
+                            holding .intentset/config.yaml)
+  --json                    machine-readable output, keys in canonical order
+  --carrier <markset|plain> how documents are read (default markset)
+  --level <L1..L4>          conformance level; each includes those below it (default L1):
+                            L2 adds architecture, L3 evidence, L4 publication readiness
+  --evidence <file>         L3 and above: run records to read, repeatable (default: every *.json in
+                            ${EVIDENCE_DIR}/, which holds local output and is not committed)
+  --product <ID> --release <label>
+                            L3 and above: the exact scope evidence is assessed for (default: every scope)
+  --mode <migration|strict> --baseline <file>
+                            L2 and above: whether a baseline of known violations applies, and which
+                            (for mcp, --mode names the server's mode instead)
+  -h, --help                show this help
+
+exit codes: 0 no errors, 1 validation errors, 2 invocation or tool failure`;
+
+const COMMANDS = [
+  "init",
+  "validate",
+  "graph",
+  "architecture",
+  "evidence",
+  "impact",
+  "context",
+  "review",
+  "publish",
+  "serve",
+  "mcp",
+];
+
+const GLOBAL = ["root", "json", "carrier", "level", "help"];
+const LEVEL_OPTIONS = ["evidence", "product", "release", "mode", "baseline"];
+const COMMAND_OPTIONS: Record<string, string[]> = {
+  init: ["repository", "example"],
+  validate: LEVEL_OPTIONS,
+  graph: ["format", "include-bodies", "release", "out", "generated-at", "evidence", "mode", "baseline"],
+  architecture: ["mode", "baseline", "write-baseline"],
+  evidence: [
+    "from",
+    "out",
+    "product",
+    "release",
+    "environment",
+    "started-at",
+    "finished-at",
+    "uri-base",
+    "tool-version",
+  ],
+  impact: LEVEL_OPTIONS,
+  context: ["include-restricted", ...LEVEL_OPTIONS],
+  review: ["base", ...LEVEL_OPTIONS],
+  serve: ["port", "host", "out", ...LEVEL_OPTIONS],
+  mcp: [
+    "mode",
+    "include-restricted",
+    "visibility",
+    "audience",
+    "product",
+    "release",
+    "role",
+    "edition",
+    "flag",
+    "authorized-internal",
+    "authorized-restricted",
+    "published-at",
+  ],
+  publish: [
+    "visibility",
+    "audience",
+    "product",
+    "release",
+    "role",
+    "edition",
+    "flag",
+    "authorized-internal",
+    "authorized-restricted",
+    "out",
+    "html",
+    "published-at",
+  ],
+};
+
+/** Positional arguments after the command: a fixed subcommand, then how many more. */
+const POSITIONALS: Record<string, { sub?: string; count: number; what?: string }> = {
+  architecture: { sub: "check", count: 0 },
+  evidence: { sub: "import", count: 1, what: "a report file" },
+  impact: { count: 1, what: "an artifact ID" },
+  context: { count: 1, what: "an artifact ID" },
+};
+
+export async function main(argv: string[], io: Io): Promise<number> {
+  let parsed: ReturnType<typeof parse>;
+  try {
+    parsed = parse(argv);
+  } catch (error) {
+    io.stderr(`intentset: ${(error as Error).message}\n\n${USAGE}\n`);
+    return 2;
+  }
+  const { values, positionals, tokens } = parsed;
+  const [command, ...rest] = positionals;
+  if (values.help || command === undefined) {
+    io.stdout(`${USAGE}\n`);
+    return values.help ? 0 : 2;
+  }
+  // The command is checked before its arguments, so a typo reads as a typo and not as a missing ID.
+  if (!COMMANDS.includes(command)) {
+    io.stderr(`intentset: unknown command "${command}"\n\n${USAGE}\n`);
+    return 2;
+  }
+  const usage = (message: string) => {
+    io.stderr(`intentset ${command}: ${message}\n`);
+    return 2;
+  };
+  const allowed = [...GLOBAL, ...(COMMAND_OPTIONS[command] ?? [])];
+  for (const token of tokens) {
+    if (token.kind === "option" && !allowed.includes(token.name)) {
+      return usage(`--${token.name} is not an option of ${command}`);
+    }
+  }
+
+  const shape = POSITIONALS[command] ?? { count: 0 };
+  let args = rest;
+  if (shape.sub !== undefined) {
+    if (args[0] !== shape.sub) return usage(`the only subcommand is "${command} ${shape.sub}"`);
+    args = args.slice(1);
+  }
+  if (args.length < shape.count) return usage(`${shape.what} is required`);
+  if (args.length > shape.count) {
+    const hint = shape.count === 0 ? " (use --root <dir> to name the repository)" : "";
+    return usage(`unexpected argument "${args[shape.count]}"${hint}`);
+  }
+
+  const carrier = values.carrier ?? "markset";
+  if (!Object.hasOwn(CARRIERS, carrier)) {
+    return usage(`--carrier ${carrier}: the carriers are ${Object.keys(CARRIERS).join(" and ")}`);
+  }
+  const levelGiven = values.level as Level | undefined;
+  if (levelGiven !== undefined && !LEVELS.includes(levelGiven)) {
+    return usage(`--level ${levelGiven}: the levels are ${LEVELS.join(", ")}`);
+  }
+  if (levelGiven === "L5") {
+    return usage("L5 is a claim about continuous CI, not something one run can check (Core §11).");
+  }
+  if (command !== "mcp" && values.mode !== undefined && values.mode !== "migration" && values.mode !== "strict") {
+    return usage(`--mode ${values.mode}: the modes are migration and strict`);
+  }
+  if (command === "init") {
+    return initCommand({ root: values.root, repository: values.repository, example: values.example }, io);
+  }
+
+  // Evidence scope: --product with --release, or graph's --release <product>:<label>.
+  let scope: RunScope | null = null;
+  if (command !== "evidence" && command !== "publish" && command !== "mcp") {
+    if (command === "graph") {
+      const release = values.release === undefined ? null : parseRelease(values.release);
+      scope = release === null ? null : { product: release.product, release: release.label };
+    } else if ((values.product === undefined) !== (values.release === undefined)) {
+      return usage("--product and --release name one scope together; give both or neither");
+    } else if (values.product !== undefined && values.release !== undefined) {
+      scope = { product: values.product, release: values.release };
+    }
+  }
+
+  const sessionOptions = (level: Level): SessionOptions => ({
+    root: values.root,
+    carrier: carrier as CarrierName,
+    level,
+    mode: command === "mcp" ? undefined : (values.mode as Mode | undefined),
+    baseline: values.baseline,
+    evidence: values.evidence,
+    scope,
+  });
+
+  switch (command) {
+    case "validate": {
+      const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
+      return typeof session === "number" ? session : validateCommand(session, values.json, io);
+    }
+    case "graph": {
+      const options = {
+        format: values.format,
+        includeBodies: values["include-bodies"],
+        release: values.release,
+        out: values.out,
+        generatedAt: values["generated-at"],
+      };
+      const problem = graphUsageProblem(options);
+      if (problem !== null) return usage(problem);
+      const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
+      return typeof session === "number" ? session : graphCommand(session, options, io);
+    }
+    case "architecture": {
+      if (levelGiven === "L1") return usage("the architecture check runs at L2 and above, where ownership joins");
+      const session = openSession("architecture check", sessionOptions(levelGiven ?? "L2"), io);
+      if (typeof session === "number") return session;
+      return architectureCommand(session, { writeBaseline: values["write-baseline"] }, values.json, io);
+    }
+    case "evidence": {
+      const options = {
+        from: values.from,
+        report: args[0],
+        out: values.out,
+        product: values.product,
+        release: values.release,
+        environment: values.environment,
+        startedAt: values["started-at"],
+        finishedAt: values["finished-at"],
+        uriBase: values["uri-base"],
+        toolVersion: values["tool-version"],
+      };
+      const problem = evidenceUsageProblem(options);
+      if (problem !== null) return usage(problem);
+      const session = openSession("evidence import", sessionOptions(levelGiven ?? "L1"), io);
+      return typeof session === "number" ? session : evidenceImportCommand(session, options, io);
+    }
+    case "impact": {
+      const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
+      return typeof session === "number" ? session : impactCommand(session, args[0], values.json, io);
+    }
+    case "context": {
+      const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
+      if (typeof session === "number") return session;
+      return contextCommand(session, args[0], values["include-restricted"], values.json, io);
+    }
+    case "review": {
+      let level = levelGiven;
+      let reason = "as asked";
+      if (level === undefined) {
+        const root = findRoot(io.cwd, values.root);
+        const records = root === null ? [] : evidenceFiles(root, io.cwd, values.evidence);
+        level = records.length > 0 ? "L4" : "L2";
+        reason =
+          records.length > 0
+            ? "the highest the inputs allow: run records were given or found"
+            : `the highest the inputs allow: no run records were given or found in ${EVIDENCE_DIR}/, so L3 and L4 were not checked`;
+      }
+      const session = openSession(command, sessionOptions(level), io);
+      if (typeof session === "number") return session;
+      return reviewCommand(session, { base: values.base, levelReason: reason }, values.json, io);
+    }
+    case "serve": {
+      const port = values.port === undefined ? 3000 : Number(values.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535 || values.port === "") {
+        return usage(`--port ${values.port}: give a port number from 0 to 65535`);
+      }
+      let level = levelGiven;
+      if (level === undefined) {
+        const root = findRoot(io.cwd, values.root);
+        level = root !== null && evidenceFiles(root, io.cwd, values.evidence).length > 0 ? "L3" : "L2";
+      }
+      return serveCommand({ port, host: values.host ?? "127.0.0.1", out: values.out }, sessionOptions(level), io);
+    }
+    case "mcp": {
+      const options = {
+        mode: values.mode,
+        includeRestricted: values["include-restricted"],
+        visibility: values.visibility,
+        audience: values.audience,
+        product: values.product,
+        release: values.release,
+        role: values.role,
+        edition: values.edition,
+        flags: values.flag ?? [],
+        authorizedInternal: values["authorized-internal"],
+        authorizedRestricted: values["authorized-restricted"],
+        publishedAt: values["published-at"],
+      };
+      const problem = mcpUsageProblem(options);
+      if (problem !== null) return usage(problem);
+      return mcpCommand(options, sessionOptions(levelGiven ?? "L1"), io);
+    }
+    default: {
+      const options = {
+        visibility: values.visibility,
+        audience: values.audience,
+        product: values.product,
+        release: values.release,
+        role: values.role,
+        edition: values.edition,
+        flags: values.flag ?? [],
+        authorizedInternal: values["authorized-internal"],
+        authorizedRestricted: values["authorized-restricted"],
+        out: values.out,
+        html: values.html,
+        publishedAt: values["published-at"],
+      };
+      const problem = publishUsageProblem(options);
+      if (problem !== null) return usage(problem);
+      const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
+      return typeof session === "number" ? session : publishCommand(session, options, io);
+    }
+  }
+}
+
+function parse(argv: string[]) {
+  return parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    tokens: true,
+    options: {
+      root: { type: "string" },
+      json: { type: "boolean", default: false },
+      carrier: { type: "string" },
+      level: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+      repository: { type: "string" },
+      example: { type: "boolean", default: false },
+      format: { type: "string" },
+      "include-bodies": { type: "boolean", default: false },
+      release: { type: "string" },
+      out: { type: "string" },
+      "generated-at": { type: "string" },
+      "include-restricted": { type: "boolean", default: false },
+      evidence: { type: "string", multiple: true },
+      product: { type: "string" },
+      mode: { type: "string" },
+      baseline: { type: "string" },
+      "write-baseline": { type: "string" },
+      from: { type: "string" },
+      environment: { type: "string" },
+      "started-at": { type: "string" },
+      "finished-at": { type: "string" },
+      "uri-base": { type: "string" },
+      "tool-version": { type: "string" },
+      base: { type: "string" },
+      visibility: { type: "string" },
+      audience: { type: "string" },
+      role: { type: "string" },
+      edition: { type: "string" },
+      flag: { type: "string", multiple: true },
+      "authorized-internal": { type: "boolean", default: false },
+      "authorized-restricted": { type: "boolean", default: false },
+      html: { type: "boolean", default: false },
+      "published-at": { type: "string" },
+      port: { type: "string" },
+      host: { type: "string" },
+    },
+  });
+}

package/src/output.ts

@@ -0,0 +1,78 @@
+/**
+ * What every command shares about output: the io it writes through, the
+ * tool's identity, JSON in canonical key order, and the one text form of a
+ * diagnostic. Nothing here touches the filesystem except reading this
+ * package's own manifest for its version.
+ */
+import { readFileSync } from "node:fs";
+import { type Diagnostic, sortKeysDeep } from "@intentset/core";
+
+export interface Io {
+  stdout(s: string): void;
+  stderr(s: string): void;
+  /** The directory the command was run from; relative paths in arguments resolve against it. */
+  cwd: string;
+  /** Aborted to stop a long-running command (serve, mcp); the bin aborts it on SIGINT and SIGTERM. */
+  signal?: AbortSignal;
+}
+
+/** The checker identity a report carries (Core §11: publish the checker version). */
+export const TOOL: { name: "intentset"; version: string } = { name: "intentset", version: readVersion() };
+
+function readVersion(): string {
+  const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+    version: string;
+  };
+  return manifest.version;
+}
+
+/** ADR 0005: JSON with every object's keys sorted, two-space indent, one trailing newline. */
+export function json(value: unknown): string {
+  return `${JSON.stringify(sortKeysDeep(value), null, 2)}\n`;
+}
+
+/** Core §9 and ADR 0004: origin "syntax" is Markset's alone, so the origin decides. */
+export function isMarkset(d: Diagnostic): boolean {
+  return d.origin === "syntax";
+}
+
+/**
+ * ADR 0004 as text: `<path>:<line>:<col> <severity> <CODE> [<artifact>] <message>`,
+ * then the remediation and the field on their own indented lines. A location
+ * that is not known is left out rather than written as 0. Markset's
+ * diagnostics are prefixed `markset:` so they read as Markset's (Core §9).
+ */
+export function formatDiagnostic(d: Diagnostic): string {
+  const where = d.path ?? "(repository)";
+  const line = d.location === undefined ? "" : `:${d.location.line}`;
+  const column = d.location?.column === undefined ? "" : `:${d.location.column}`;
+  const artifact = d.artifact === null ? "" : ` [${d.artifact}]`;
+  const prefix = isMarkset(d) ? "markset: " : "";
+  let text = `${prefix}${where}${line}${column} ${d.severity} ${d.code}${artifact} ${d.message}\n`;
+  if (d.remediation !== "") text += `  fix: ${d.remediation}\n`;
+  if (d.field !== undefined) text += `  field: ${d.field}\n`;
+  return text;
+}
+
+/** "1 artifact", "2 artifacts"; "1 entry", "2 entries" with the plural given. */
+export function count(n: number, noun: string, plural = `${noun}s`): string {
+  return `${n} ${n === 1 ? noun : plural}`;
+}
+
+/** The snapshot a report describes (Core §10, §11): the commit, or why there is none, and the graph hash. */
+export interface Snapshot {
+  commit: string | null;
+  commitUnavailable?: string;
+  /** True when tracked files differ from the commit; the graph hash still describes exactly what was read. */
+  uncommitted?: boolean;
+  graphHash: string;
+}
+
+/** One line naming the snapshot, for the top of a text report. */
+export function snapshotLine(snapshot: Snapshot): string {
+  const commit =
+    snapshot.commit === null
+      ? `no commit (${snapshot.commitUnavailable ?? "none was read"})`
+      : `commit ${snapshot.commit}${snapshot.uncommitted === true ? " plus uncommitted changes" : ""}`;
+  return `Snapshot: ${commit}, graph ${snapshot.graphHash}`;
+}