@coldtea/pr-lens-cli 0.1.0

package/src/cli.ts

@@ -0,0 +1,120 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import { analyzeCommand, USAGE as ANALYZE_USAGE } from "./commands/analyze.js";
+import { commentCommand, USAGE as COMMENT_USAGE } from "./commands/comment.js";
+import { exportCommand, USAGE as EXPORT_USAGE } from "./commands/export.js";
+import { renderCommand, USAGE as RENDER_USAGE } from "./commands/render.js";
+import { USAGE as VALIDATE_USAGE, validateCommand } from "./commands/validate.js";
+import { formatError, PrLensCliError } from "./errors.js";
+import type { Terminal } from "./terminal.js";
+import { CLI_VERSION } from "./version.js";
+
+const COMMANDS = ["analyze", "render", "comment", "validate", "export"] as const;
+type CommandName = (typeof COMMANDS)[number];
+
+const isCommand = (value: string): value is CommandName =>
+  COMMANDS.some((command) => command === value);
+
+const HELP = `pr-lens — review what actually matters
+
+  pr-lens analyze   --base <ref>            a diff, read by your own model, as a graph document
+  pr-lens render    <graph.json>            that document, as light and dark SVGs
+  pr-lens comment   --graph --manifest      the pull request comment, as markdown
+  pr-lens validate  <file...>               any PR Lens document, checked against the contract
+  pr-lens export    <graph.json>            the merged state, as a map worth committing
+
+  pr-lens <command> --help                  what a command takes
+  pr-lens --version
+
+Your model key is read from the environment and goes only to the provider you
+name. https://github.com/coldteadotai/pr-lens`;
+
+const usageFor = (command: CommandName): string => {
+  switch (command) {
+    case "analyze":
+      return ANALYZE_USAGE;
+    case "render":
+      return RENDER_USAGE;
+    case "comment":
+      return COMMENT_USAGE;
+    case "validate":
+      return VALIDATE_USAGE;
+    case "export":
+      return EXPORT_USAGE;
+    default:
+      return assertNever(command, "Unhandled command");
+  }
+};
+
+const dispatch = (
+  command: CommandName,
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  switch (command) {
+    case "analyze":
+      return analyzeCommand(args, terminal, env);
+    case "render":
+      return renderCommand(args, terminal);
+    case "comment":
+      return commentCommand(args, terminal);
+    case "validate":
+      return validateCommand(args, terminal);
+    case "export":
+      return exportCommand(args, terminal);
+    default:
+      return assertNever(command, "Unhandled command");
+  }
+};
+
+const EXIT_OK = 0;
+const EXIT_FAILED = 1;
+const EXIT_MISUSED = 2;
+
+export const run = async (
+  argv: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<number> => {
+  const [name, ...args] = argv;
+
+  if (name === undefined) {
+    terminal.err(HELP);
+    return EXIT_MISUSED;
+  }
+
+  if (name === "--help" || name === "-h" || name === "help") {
+    terminal.out(HELP);
+    return EXIT_OK;
+  }
+
+  if (name === "--version" || name === "-v") {
+    terminal.out(CLI_VERSION);
+    return EXIT_OK;
+  }
+
+  if (!isCommand(name)) {
+    terminal.err(formatError(new PrLensCliError("USAGE", `unknown command ${JSON.stringify(name)}`)));
+    terminal.err(HELP);
+    return EXIT_MISUSED;
+  }
+
+  if (args.includes("--help") || args.includes("-h")) {
+    terminal.out(usageFor(name));
+    return EXIT_OK;
+  }
+
+  try {
+    await dispatch(name, args, terminal, env);
+    return EXIT_OK;
+  } catch (error) {
+    if (!(error instanceof PrLensCliError)) throw error;
+
+    terminal.err(formatError(error));
+    if (error.code !== "USAGE") return EXIT_FAILED;
+
+    terminal.err("");
+    terminal.err(usageFor(name));
+    return EXIT_MISUSED;
+  }
+};

package/src/commands/analyze.ts

@@ -0,0 +1,206 @@
+import { LENSES, type GraphDocInput, type Lens } from "@coldtea/pr-lens-schema";
+import { createRequire } from "node:module";
+import { parseOptions, readBoolean, readInt, readList, readString } from "../args.js";
+import { discoverConfig, loadConfig, type LoadedConfig } from "../config-file.js";
+import { PrLensCliError, usageError } from "../errors.js";
+import { extractGraph } from "../extract.js";
+import { collectDiff, mergeBase, parseRepoSlug, remoteSlug, repositoryRoot, resolveCommit } from "../git.js";
+import { readTextFile, writeJsonFile } from "../io.js";
+import { buildExtractionPrompt, SYSTEM_PROMPT } from "../prompt.js";
+import { completeJson, isProviderId, PROVIDER_IDS, resolveProvider } from "../providers/index.js";
+import type { Terminal } from "../terminal.js";
+import { CLI_VERSION, GENERATOR_NAME } from "../version.js";
+
+const DEFAULT_OUT = "pr-lens/graph.json";
+const DEFAULT_MAX_OUTPUT_TOKENS = 32_768;
+const DEFAULT_MAX_DIFF_BYTES = 400_000;
+
+export const USAGE = `pr-lens analyze --base <ref> [options]
+
+Reads the diff between two commits and asks your own model to describe it as a
+graph document. The key never leaves your machine: it is read from the
+environment, and the diff goes straight to the provider you name.
+
+  --base <ref>              what the change is measured against (required)
+  --head <ref>              the tip of the change (default HEAD)
+  --repo <dir>              repository to read (default .)
+  --provider <id>           ${PROVIDER_IDS.join(" | ")} (default gemini)
+  --model <name>            model to ask (required for openai-compatible)
+  --base-url <url>          provider endpoint, for a compatible or local server
+  --api-key-env <name>      environment variable holding the key
+  --lens <lens>             ${LENSES.join(", ")} (repeatable, default both)
+  --config <file>           read the lenses from this config (default the repository's)
+  --no-config               ignore the repository's config
+  --pr <number>             pull request number, recorded in provenance
+  --repo-slug <owner/name>  override the slug read from the git remote
+  --remote <name>           remote to read the slug from (default origin)
+  --max-diff-bytes <n>      truncate the diff sent to the model (default ${DEFAULT_MAX_DIFF_BYTES})
+  --max-output-tokens <n>   room for the answer (default ${DEFAULT_MAX_OUTPUT_TOKENS})
+  --dry-run                 report what would be sent, and send nothing
+  -o, --out <file>          where to write the document (default ${DEFAULT_OUT})`;
+
+const readLenses = (values: Record<string, unknown>): Lens[] | undefined => {
+  const requested = readList(values.lens, "lens");
+  if (requested === undefined) return undefined;
+
+  const unknown = requested.filter((lens) => !LENSES.some((known) => known === lens));
+  if (unknown.length > 0)
+    throw usageError(`unknown lens ${unknown.join(", ")}`, `known lenses: ${LENSES.join(", ")}`);
+
+  return LENSES.filter((lens) => requested.includes(lens));
+};
+
+const readProviderId = (values: Record<string, unknown>) => {
+  const id = readString(values.provider, "provider") ?? "gemini";
+  if (!isProviderId(id))
+    throw usageError(`unknown provider ${JSON.stringify(id)}`, `known providers: ${PROVIDER_IDS.join(", ")}`);
+  return id;
+};
+
+const graphJsonSchema = (): Promise<string> =>
+  readTextFile(
+    createRequire(import.meta.url).resolve("@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json"),
+  );
+
+export const analyzeCommand = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    base: { type: "string" },
+    head: { type: "string" },
+    repo: { type: "string" },
+    provider: { type: "string" },
+    model: { type: "string" },
+    "base-url": { type: "string" },
+    "api-key-env": { type: "string" },
+    lens: { type: "string", multiple: true },
+    config: { type: "string" },
+    "no-config": { type: "boolean" },
+    pr: { type: "string" },
+    "repo-slug": { type: "string" },
+    remote: { type: "string" },
+    "max-diff-bytes": { type: "string" },
+    "max-output-tokens": { type: "string" },
+    "dry-run": { type: "boolean" },
+    out: { type: "string", short: "o" },
+  });
+
+  if (positionals.length > 0) throw usageError(`analyze takes no positional arguments, got ${positionals.join(" ")}`);
+
+  const base = readString(values.base, "base");
+  if (base === undefined) throw usageError("--base is required", "it names the commit the change is measured against, e.g. --base origin/main");
+
+  const repo = readString(values.repo, "repo") ?? process.cwd();
+  const head = readString(values.head, "head") ?? "HEAD";
+  const maxDiffBytes = readInt(values["max-diff-bytes"], "max-diff-bytes", DEFAULT_MAX_DIFF_BYTES);
+
+  const slugOption = readString(values["repo-slug"], "repo-slug");
+  const slug = slugOption === undefined
+    ? await remoteSlug(repo, readString(values.remote, "remote") ?? "origin")
+    : parseRepoSlug(slugOption);
+
+  if (slug === undefined)
+    throw new PrLensCliError(
+      "REPOSITORY_UNKNOWN",
+      "cannot tell which repository this is",
+      "pass --repo-slug owner/name, or add a git remote the CLI can read",
+    );
+
+  const configPath = readString(values.config, "config");
+  const configured: LoadedConfig | undefined = readBoolean(values["no-config"])
+    ? undefined
+    : configPath === undefined
+      ? await discoverConfig(await repositoryRoot(repo))
+      : await loadConfig(configPath);
+
+  const requestedLenses = readLenses(values);
+  const lenses = requestedLenses ?? configured?.config.lenses ?? [...LENSES];
+
+  const headCommit = await resolveCommit(repo, head);
+  const baseCommit = await resolveCommit(repo, base);
+  const comparedAgainst = await mergeBase(repo, baseCommit.sha, headCommit.sha);
+  const diff = await collectDiff(repo, comparedAgainst, headCommit.sha, maxDiffBytes);
+
+  if (diff.files.length === 0)
+    throw new PrLensCliError(
+      "EMPTY_DIFF",
+      `${base} and ${head} have the same content`,
+      "there is nothing to draw",
+    );
+
+  const promptContext = {
+    repo: { owner: slug.owner, name: slug.name },
+    base: { sha: comparedAgainst, ref: baseCommit.ref },
+    head: { sha: headCommit.sha, ref: headCommit.ref },
+    diff,
+    lenses,
+  };
+
+  const user = buildExtractionPrompt(promptContext, await graphJsonSchema());
+  const provider = readBoolean(values["dry-run"])
+    ? undefined
+    : resolveProvider(
+        {
+          id: readProviderId(values),
+          model: readString(values.model, "model"),
+          baseUrl: readString(values["base-url"], "base-url"),
+          apiKeyEnv: readString(values["api-key-env"], "api-key-env"),
+        },
+        env,
+      );
+
+  terminal.err(
+    `${diff.files.length} files, +${diff.additions} -${diff.deletions}, ${Buffer.byteLength(diff.patch, "utf8")} bytes of diff${diff.truncatedAt === undefined ? "" : " (truncated)"}`,
+  );
+  terminal.err(`prompt: ${Buffer.byteLength(user, "utf8")} bytes`);
+
+  if (provider === undefined) {
+    terminal.out(`✓ dry run — nothing was sent, and nothing was written`);
+    return;
+  }
+
+  const pr = values.pr === undefined ? undefined : readInt(values.pr, "pr", 0);
+  const pullRequest =
+    pr === undefined
+      ? undefined
+      : { number: pr, url: `https://${slug.host}/${slug.owner}/${slug.name}/pull/${pr}` };
+
+  const provenance: GraphDocInput["provenance"] = {
+    repo: slug,
+    base: { sha: comparedAgainst, ref: baseCommit.ref },
+    head: { sha: headCommit.sha, ref: headCommit.ref },
+    ...(pullRequest === undefined ? {} : { pullRequest }),
+    generator: { name: GENERATOR_NAME, version: CLI_VERSION, model: provider.model },
+  };
+
+  terminal.err(`asking ${provider.id} (${provider.model})…`);
+
+  const { document, attempts } = await extractGraph(
+    {
+      system: SYSTEM_PROMPT,
+      user,
+      maxOutputTokens: readInt(values["max-output-tokens"], "max-output-tokens", DEFAULT_MAX_OUTPUT_TOKENS),
+      known: {
+        provenance,
+        lenses,
+        stats: {
+          filesChanged: diff.files.length,
+          additions: diff.additions,
+          deletions: diff.deletions,
+        },
+        generatedAt: new Date().toISOString(),
+      },
+      onAttempt: (attempt) => {
+        if (attempt > 1) terminal.err(`the document did not validate — asking for a correction`);
+      },
+    },
+    (request) => completeJson(provider, request),
+  );
+
+  const written = await writeJsonFile(readString(values.out, "out") ?? DEFAULT_OUT, document);
+  terminal.out(
+    `✓ ${written} — ${document.nodes.length} nodes, ${document.edges.length} edges, ${document.flows.length} flows${attempts > 1 ? ` (${attempts} attempts)` : ""}`,
+  );
+};

package/src/commands/comment.ts

@@ -0,0 +1,77 @@
+import { graphContentHash } from "@coldtea/pr-lens-renderer";
+import { parseOptions, readBoolean, readString } from "../args.js";
+import { composeComment, COMMENT_MARKER } from "../comment.js";
+import { loadConfig } from "../config-file.js";
+import { readGraphDoc, readRenderManifest } from "../document.js";
+import { usageError } from "../errors.js";
+import { writeTextFile } from "../io.js";
+import type { Terminal } from "../terminal.js";
+
+export const USAGE = `pr-lens comment --graph <graph.json> --manifest <manifest.json> [options]
+
+Composes the pull request comment: the diagrams as light/dark <picture> pairs,
+the headline numbers, and the drill-down tree. It posts nothing — the markdown
+goes to stdout, or to a file, for whatever does the posting.
+
+      --graph <file>          the document that was rendered — the one the render
+                              wrote beside the manifest, not the one it read
+      --manifest <file>       what the render produced (required)
+      --asset-base-url <url>  where the rendered SVGs are published, when the
+                              manifest records local paths
+      --config <file>         read 'branding' from a repository config
+      --no-branding           leave off the PR Lens footer
+      --print-marker          print the hidden marker that identifies the
+                              comment, and nothing else
+  -o, --out <file>            write the markdown here instead of stdout`;
+
+export const commentCommand = async (args: readonly string[], terminal: Terminal): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    graph: { type: "string" },
+    manifest: { type: "string" },
+    "asset-base-url": { type: "string" },
+    config: { type: "string" },
+    "no-branding": { type: "boolean" },
+    "print-marker": { type: "boolean" },
+    out: { type: "string", short: "o" },
+  });
+
+  if (positionals.length > 0)
+    throw usageError(`comment takes no positional arguments, got ${positionals.join(" ")}`);
+
+  if (readBoolean(values["print-marker"])) {
+    terminal.out(COMMENT_MARKER);
+    return;
+  }
+
+  const graphPath = readString(values.graph, "graph");
+  const manifestPath = readString(values.manifest, "manifest");
+  if (graphPath === undefined || manifestPath === undefined)
+    throw usageError("--graph and --manifest are both required");
+
+  const configPath = readString(values.config, "config");
+  const configured = configPath === undefined ? undefined : await loadConfig(configPath);
+
+  const graph = await readGraphDoc(graphPath);
+  const manifest = await readRenderManifest(manifestPath);
+
+  if (graphContentHash(graph) !== manifest.graph.contentHash)
+    throw usageError(
+      `${graphPath} is not the document ${manifestPath} describes`,
+      "corrections change what the diagrams show, so a comment built from a different document would announce sections that were never drawn. Pass the drawn.graph.json the render wrote beside the manifest",
+    );
+
+  const body = composeComment({
+    graph,
+    manifest,
+    assetBaseUrl: readString(values["asset-base-url"], "asset-base-url"),
+    branding: readBoolean(values["no-branding"]) ? false : (configured?.config.branding ?? true),
+  });
+
+  const out = readString(values.out, "out");
+  if (out === undefined) {
+    terminal.out(body.trimEnd());
+    return;
+  }
+
+  terminal.err(`✓ ${await writeTextFile(out, body)}`);
+};

package/src/commands/export.ts

@@ -0,0 +1,61 @@
+import { expectOne, parseOptions, readString } from "../args.js";
+import { invalidDocument, readGraphDoc } from "../document.js";
+import { PrLensCliError, usageError } from "../errors.js";
+import { writeJsonFile } from "../io.js";
+import { toStoredMap } from "../snapshot.js";
+import type { Terminal } from "../terminal.js";
+
+const DEFAULT_OUT = ".github/pr-lens.map.json";
+
+export const USAGE = `pr-lens export <graph.json> [options]
+
+Turns a pull-request document into the stored map of the system once that pull
+request has merged: elements the change deletes are dropped, the rest stops
+being annotated, and the result is stamped with the single commit it reflects.
+
+The map is a snapshot, not a source of truth — nothing reads it back into the
+pipeline. Committing it gives a repository something to read, to diff, and to
+hand an agent.
+
+  -o, --out <file>   where to write it (default ${DEFAULT_OUT})
+      --id <id>      map id, so a patch can name it (default <owner>/<name>)
+      --sha <sha>    the commit it reflects, in full (default the document's head)`;
+
+export const exportCommand = async (args: readonly string[], terminal: Terminal): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    out: { type: "string", short: "o" },
+    id: { type: "string" },
+    sha: { type: "string" },
+  });
+
+  const source = expectOne(positionals, "one graph document to export");
+  if (/^https?:\/\//.test(source))
+    throw usageError(
+      "export reads a local graph document",
+      "fetching a map from a hosted pipeline is not something the CLI does yet",
+    );
+
+  const graph = await readGraphDoc(source);
+  const out = readString(values.out, "out") ?? DEFAULT_OUT;
+
+  const stored = toStoredMap(graph, {
+    id: readString(values.id, "id") ?? `${graph.provenance.repo.owner}/${graph.provenance.repo.name}`,
+    sha: readString(values.sha, "sha") ?? graph.provenance.head.sha,
+    generatedAt: new Date().toISOString(),
+  });
+
+  if (!stored.ok) {
+    if (stored.error.code === "NOT_A_SNAPSHOT" || stored.error.code === "PATCH_CONFLICT")
+      throw new PrLensCliError(
+        "INVALID_DOCUMENT",
+        `${source} cannot be exported as a stored map [${stored.error.code}]`,
+        stored.error.message,
+      );
+    throw invalidDocument(source, "graph", stored.error);
+  }
+
+  const written = await writeJsonFile(out, stored.value);
+  terminal.out(
+    `✓ ${written} — stored map of ${stored.value.provenance.repo.owner}/${stored.value.provenance.repo.name} at ${stored.value.provenance.head.sha.slice(0, 7)} · ${stored.value.nodes.length} nodes, ${stored.value.edges.length} edges`,
+  );
+};

package/src/commands/render.ts

@@ -0,0 +1,125 @@
+import { applyCorrections, PrLensRenderError, renderAll, THEMES, type Theme } from "@coldtea/pr-lens-renderer";
+import { safeParseGraphDoc, type Config, type GraphDoc } from "@coldtea/pr-lens-schema";
+import { join } from "node:path";
+import { expectOne, parseOptions, readBoolean, readString } from "../args.js";
+import { discoverConfig, loadConfig } from "../config-file.js";
+import { unmatchedCorrections } from "../corrections.js";
+import { readGraphDoc } from "../document.js";
+import { PrLensCliError, usageError } from "../errors.js";
+import { repositoryRoot } from "../git.js";
+import { writeJsonFile, writeTextFile } from "../io.js";
+import type { Terminal } from "../terminal.js";
+
+const DEFAULT_OUT = "pr-lens";
+const MANIFEST = "manifest.json";
+
+/**
+ * The document as it was drawn, written beside the manifest.
+ *
+ * Corrections are applied here, so the document on the way in and the
+ * diagrams on the way out can describe different systems — a view whose every
+ * element was excluded is drawn by neither. Whatever composes the comment has
+ * to read the one the pictures came from, and it is a different file from the
+ * one analyze wrote so that neither overwrites the other.
+ */
+const DRAWN = "drawn.graph.json";
+
+export const USAGE = `pr-lens render <graph.json> [options]
+
+Draws the document as self-contained SVGs — one per drill-down section per
+lens, in light and dark — and writes the manifest describing them. A document
+with no sections gets one diagram per lens it declares.
+
+  -o, --out <dir>      where the SVGs and the manifest go (default ${DEFAULT_OUT}/)
+      --theme <theme>  light | dark | both (default both)
+      --config <file>  corrections to draw with (default the repository's, if any)
+      --no-config      ignore the repository's corrections`;
+
+const readThemes = (value: unknown): readonly Theme[] => {
+  const theme = readString(value, "theme") ?? "both";
+  switch (theme) {
+    case "light":
+    case "dark":
+      return [theme];
+    case "both":
+      return THEMES;
+    default:
+      throw usageError(`--theme takes light, dark or both, got ${JSON.stringify(theme)}`);
+  }
+};
+
+/**
+ * The overlay is applied here rather than by passing the config into
+ * `renderAll`, which would apply the same function to the same document — but
+ * out of reach, and the comment has to be composed from what was drawn.
+ */
+const correct = (graph: GraphDoc, config: Config): GraphDoc => {
+  try {
+    return applyCorrections(graph, config.map);
+  } catch (error) {
+    if (!(error instanceof PrLensRenderError)) throw error;
+    throw new PrLensCliError("RENDER_FAILED", `${error.message} [${error.code}]`);
+  }
+};
+
+export const renderCommand = async (args: readonly string[], terminal: Terminal): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    out: { type: "string", short: "o" },
+    theme: { type: "string" },
+    config: { type: "string" },
+    "no-config": { type: "boolean" },
+  });
+
+  const graph = await readGraphDoc(expectOne(positionals, "one graph document to render"));
+  const out = readString(values.out, "out") ?? DEFAULT_OUT;
+
+  const configPath = readString(values.config, "config");
+  const configured = readBoolean(values["no-config"])
+    ? undefined
+    : configPath === undefined
+      ? await discoverConfig(await repositoryRoot(process.cwd()).catch(() => process.cwd()))
+      : await loadConfig(configPath);
+
+  const themes = readThemes(values.theme);
+
+  const drawn = (() => {
+    if (configured === undefined) return graph;
+
+    for (const warning of unmatchedCorrections(graph, configured.config))
+      terminal.err(`${configured.path}: ${warning}`);
+
+    const corrected = correct(graph, configured.config);
+    const parsed = safeParseGraphDoc(corrected);
+    if (!parsed.ok)
+      throw new PrLensCliError(
+        `INVALID_DOCUMENT`,
+        `${configured.path} leaves a document that no longer validates [${parsed.error.code}]`,
+        parsed.error.message,
+      );
+
+    return parsed.value;
+  })();
+
+  const rendered = (() => {
+    try {
+      return renderAll(drawn, { themes });
+    } catch (error) {
+      if (!(error instanceof PrLensRenderError)) throw error;
+      throw new PrLensCliError("RENDER_FAILED", `${error.message} [${error.code}]`);
+    }
+  })();
+
+  for (const drawing of rendered.assets) {
+    const { id, path } = drawing.asset;
+    if (path === undefined)
+      throw new PrLensCliError("RENDER_FAILED", `the render named no file for asset '${id}'`);
+    await writeTextFile(join(out, path), drawing.svg);
+  }
+  await writeJsonFile(join(out, DRAWN), drawn);
+  await writeJsonFile(join(out, MANIFEST), rendered.manifest);
+
+  const diagrams = new Set(rendered.assets.map((asset) => asset.asset.view ?? asset.lens));
+  terminal.out(
+    `✓ ${join(out, MANIFEST)} — ${rendered.assets.length} SVGs across ${diagrams.size} ${diagrams.size === 1 ? "diagram" : "diagrams"}${configured === undefined ? "" : `, corrected by ${configured.path}`}`,
+  );
+};

package/src/commands/validate.ts

@@ -0,0 +1,57 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import { parseOptions } from "../args.js";
+import { validateDocumentFile, type ValidatedDocument } from "../document.js";
+import { formatError, PrLensCliError, usageError } from "../errors.js";
+import type { Terminal } from "../terminal.js";
+
+const count = (n: number, singular: string): string =>
+  `${n} ${n === 1 ? singular : `${singular}s`}`;
+
+const describe = (validated: ValidatedDocument): string => {
+  switch (validated.kind) {
+    case "graph": {
+      const { lanes, nodes, edges, flows, lenses } = validated.document;
+      return `graph document · ${count(lanes.length, "lane")}, ${count(nodes.length, "node")}, ${count(edges.length, "edge")}, ${count(flows.length, "flow")} · ${lenses.join(", ")}`;
+    }
+    case "patch":
+      return `patch document · ${count(validated.document.ops.length, "operation")} · ${validated.document.target.fromSha.slice(0, 7)} → ${validated.document.target.toSha.slice(0, 7)}`;
+    case "render-manifest":
+      return `render manifest · ${count(validated.document.assets.length, "asset")}`;
+    case "config": {
+      const { map, lenses } = validated.document;
+      const corrections =
+        map.rename.length + map.exclude.length + map.lane.length + map.group.length;
+      return `config · ${lenses.join(", ")} · ${count(corrections, "correction")}`;
+    }
+    default:
+      return assertNever(validated, "Unhandled document");
+  }
+};
+
+export const USAGE = `pr-lens validate <file...>
+
+Parses graph documents, patch documents, render manifests and configs — JSON or
+YAML — and reports every problem in each, rather than only the first. A file
+without a 'kind' field is read as a config.`;
+
+export const validateCommand = async (args: readonly string[], terminal: Terminal): Promise<void> => {
+  const { positionals } = parseOptions(args, {});
+  if (positionals.length === 0) throw usageError("expected at least one file to validate");
+
+  let failed = 0;
+  for (const path of positionals) {
+    try {
+      terminal.out(`✓ ${path} — ${describe(await validateDocumentFile(path))}`);
+    } catch (error) {
+      if (!(error instanceof PrLensCliError)) throw error;
+      failed += 1;
+      terminal.err(formatError(error));
+    }
+  }
+
+  if (failed > 0)
+    throw new PrLensCliError(
+      "INVALID_DOCUMENT",
+      `${failed} of ${count(positionals.length, "document")} did not validate`,
+    );
+};