@intentset/cli 0.1.0

package/src/commands/publish.ts

@@ -0,0 +1,119 @@
+/**
+ * `intentset publish` (Core §9): the deny-by-default projection of reviewed
+ * knowledge for one audience, release and entitlement, as generated Markset
+ * with provenance, optional HTML, the index a customer tool may read, and
+ * retrieval chunks that carry the same filters. Refuses outright when the
+ * graph does not validate. Review pins are read as written: a real pin is a
+ * literal hash, and the fixtures' `@current` is never bound here, so an
+ * unbound one reads as changed. Writes only into the --out directory, which
+ * must be new or empty and outside the documents' scope.
+ */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { type Visibility, sortDiagnostics } from "@intentset/core";
+import { type PublicationRequest, publish, toChunks } from "@intentset/publisher";
+import { count, formatDiagnostic, type Io } from "../output.ts";
+import { outputDirProblem, outputProblem } from "../outputs.ts";
+import type { Session } from "../session.ts";
+
+export interface PublishCliOptions {
+  visibility?: string;
+  audience?: string;
+  product?: string;
+  release?: string;
+  role?: string;
+  edition?: string;
+  flags: string[];
+  authorizedInternal: boolean;
+  authorizedRestricted: boolean;
+  out?: string;
+  html: boolean;
+  publishedAt?: string;
+}
+
+const ISO_8601 = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})$/;
+
+export function publishUsageProblem(options: PublishCliOptions): string | null {
+  if (options.out === undefined || options.out === "") return "--out <dir> is required";
+  if (options.publishedAt !== undefined && !ISO_8601.test(options.publishedAt)) {
+    return `--published-at ${options.publishedAt}: give an ISO 8601 time such as 2026-10-02T12:00:00Z`;
+  }
+  return null;
+}
+
+export function publishCommand(session: Session, options: PublishCliOptions, io: Io): number {
+  const fail = (message: string) => {
+    io.stderr(`intentset publish: ${message}\n`);
+    return 2;
+  };
+  const { repo, result, snapshot } = session;
+  if (!result.ok) {
+    for (const d of session.diagnostics) io.stdout(formatDiagnostic(d));
+    io.stderr(
+      `intentset publish: refused: validation at ${session.level} has ${count(session.errors, "error")}, and nothing is published from a graph that does not validate.\n`,
+    );
+    return 1;
+  }
+  const dir = resolve(io.cwd, options.out as string);
+  if (existsSync(dir) && readdirSync(dir).length > 0) {
+    return fail(`--out ${options.out} is not empty; publish into a new or empty directory so nothing stale survives.`);
+  }
+  const where = outputDirProblem(repo, dir);
+  if (where !== null) return fail(`--out ${options.out} ${where}.`);
+
+  // The request exactly as given: a dimension left out stays out, and the publisher refuses it (no implicit wildcard).
+  const request = {
+    visibility: options.visibility as Visibility,
+    audience: options.audience,
+    product: options.product,
+    release: options.release,
+    role: options.role,
+    edition: options.edition,
+    flags: options.flags,
+    authorizedInternal: options.authorizedInternal,
+    authorizedRestricted: options.authorizedRestricted,
+  } as PublicationRequest;
+  const published = publish(result.graph, repo.registries, request, {
+    snapshot: { commit: snapshot.commit, graphHash: snapshot.graphHash },
+    publishedAt: options.publishedAt ?? new Date().toISOString(),
+    renderHtml: options.html,
+  });
+
+  const outputs = new Map<string, string>();
+  if (published.index.request !== null) {
+    for (const document of published.documents) {
+      outputs.set(`${document.id}.md`, document.markset);
+      if (document.html !== undefined) outputs.set(`${document.id}.html`, document.html);
+    }
+    outputs.set("index.json", `${JSON.stringify(published.index, null, 2)}\n`);
+    const chunks = toChunks(published.documents);
+    outputs.set("chunks.jsonl", chunks.map((chunk) => `${JSON.stringify(chunk)}\n`).join(""));
+  }
+  for (const name of outputs.keys()) {
+    const problem = outputProblem(repo, join(dir, name));
+    if (problem !== null) return fail(`--out ${options.out}: ${name} ${problem}; nothing was written.`);
+  }
+  if (outputs.size > 0) mkdirSync(dir, { recursive: true });
+  for (const [name, text] of outputs) writeFileSync(join(dir, name), text, { flag: "wx" });
+
+  for (const d of sortDiagnostics(published.diagnostics)) io.stdout(formatDiagnostic(d));
+  const index = published.index;
+  const lines: string[] = [];
+  if (index.request === null) {
+    lines.push("The request was refused, so nothing was projected and nothing was written.");
+  } else {
+    const r = index.request;
+    lines.push(
+      `Published ${count(index.published.length, "document")} for a ${r.visibility} projection: audience ${r.audience}, ${r.product} ${r.release}, role ${r.role}, edition ${r.edition}, flags ${r.flags.length === 0 ? "none" : r.flags.join(", ")}`,
+      ...index.published.map((id) => `  ${id}`),
+    );
+    const reasons = Object.keys(index.excludedCounts);
+    lines.push(
+      `Excluded, among what this projection may see (${reasons.length === 0 ? "none" : reasons.map((reason) => `${reason} ${index.excludedCounts[reason]}`).join(", ")})`,
+      `Snapshot: ${snapshot.commit === null ? `no commit (${snapshot.commitUnavailable})` : `commit ${snapshot.commit}`}, graph ${snapshot.graphHash}`,
+      `Wrote ${[...outputs.keys()].map((name) => join(options.out as string, name)).join(", ")}`,
+    );
+  }
+  io.stdout(`${lines.join("\n")}\n`);
+  return published.ok ? 0 : 1;
+}

package/src/commands/review.ts

@@ -0,0 +1,155 @@
+/**
+ * `intentset review` (Core §10): the local review report. Validation at the
+ * highest level the inputs allow (L2 always; L4 when run records are given
+ * or found, since L3's evidence is the only input L4 needs beyond it), the
+ * architecture summary, coverage, and the impact of the change: every file
+ * changed since the base, committed or not, mapped to the artifacts it
+ * touches, a changed record to its own artifact and a changed source file
+ * through the claiming slice to that slice's behaviors, each start's direct
+ * dependents shown apart from its candidates. Markdown by default. Read-only.
+ */
+import { type Graph, impact, compareStrings } from "@intentset/core";
+import { type Changes, changedFiles, chooseBase } from "../git.ts";
+import { matchGlob } from "../glob.ts";
+import { count, formatDiagnostic, type Io, json, snapshotLine, TOOL } from "../output.ts";
+import { levelJson, levelSections } from "../reports.ts";
+import type { Session } from "../session.ts";
+import { pathText, REACHABILITY_NOTE } from "./impact.ts";
+
+export interface Attribution {
+  /** The artifact impact starts from. */
+  start: string;
+  /** The changed files that led to it, and how. */
+  because: string[];
+}
+
+/** Map changed files to impact starts. A path that is a record names its artifact; a claimed source file names the claiming slices' behaviors. */
+export function attribute(graph: Graph, changed: readonly string[]): { starts: Attribution[]; unattributed: string[] } {
+  const byPath = new Map<string, string>();
+  for (const [id, artifact] of graph.artifacts) byPath.set(artifact.path, id);
+  const slices = [...graph.artifacts.values()]
+    .filter((a) => a.meta.type === "slice" && a.meta.status !== "retired" && a.meta.slice !== undefined)
+    .sort((a, b) => compareStrings(a.meta.id, b.meta.id));
+  const starts = new Map<string, Set<string>>();
+  const add = (id: string, reason: string) => {
+    const set = starts.get(id) ?? new Set<string>();
+    set.add(reason);
+    starts.set(id, set);
+  };
+  const unattributed: string[] = [];
+  for (const path of changed) {
+    const id = byPath.get(path);
+    if (id !== undefined) {
+      add(id, `${path} is its record`);
+      continue;
+    }
+    const owners = slices.filter((slice) => slice.meta.slice?.claims.some((claim) => matchGlob(claim.path, path)));
+    let attributed = false;
+    for (const slice of owners) {
+      for (const behavior of slice.meta.links.implements ?? []) {
+        if (!graph.artifacts.has(behavior)) continue;
+        add(behavior, `${path} is claimed by ${slice.meta.id}, which implements it`);
+        attributed = true;
+      }
+    }
+    if (!attributed) unattributed.push(path);
+  }
+  return {
+    starts: [...starts.keys()]
+      .sort(compareStrings)
+      .map((start) => ({ start, because: [...(starts.get(start) as Set<string>)].sort(compareStrings) })),
+    unattributed,
+  };
+}
+
+export function reviewCommand(
+  session: Session,
+  options: { base?: string; levelReason: string },
+  asJson: boolean,
+  io: Io,
+): number {
+  const { repo, result, snapshot } = session;
+  const graph = result.graph;
+  const chosen = chooseBase(repo.root, options.base);
+  if (chosen === null) {
+    io.stderr(`intentset review: --base ${options.base} names no commit.\n`);
+    return 2;
+  }
+  const base = "unavailable" in chosen ? null : chosen;
+  const changes: Changes = { base, ...changedFiles(repo.root, base) };
+  if ("unavailable" in chosen) changes.baseUnavailable = chosen.unavailable;
+  const changed = [...new Set([...changes.committed, ...changes.uncommitted])].sort(compareStrings);
+  const { starts, unattributed } = attribute(graph, changed);
+  const impacts = starts.map(({ start, because }) => {
+    const artifact = graph.artifacts.get(start);
+    const report = impact(graph, start);
+    return {
+      start,
+      type: artifact?.meta.type,
+      title: artifact?.meta.title,
+      because,
+      direct: report.direct,
+      candidates: report.candidates,
+    };
+  });
+
+  if (asJson) {
+    io.stdout(
+      json({
+        tool: TOOL,
+        snapshot,
+        level: session.level,
+        levelReason: options.levelReason,
+        changes,
+        validation: {
+          summary: { artifacts: graph.artifacts.size, errors: session.errors, warnings: session.warnings },
+          diagnostics: session.diagnostics,
+        },
+        ...levelJson(session),
+        note: REACHABILITY_NOTE,
+        impact: impacts,
+        unattributed,
+      }),
+    );
+    return session.errors > 0 ? 1 : 0;
+  }
+
+  const baseLine =
+    base === null
+      ? `- Base: none (${changes.baseUnavailable}); only uncommitted changes are considered`
+      : `- Base: ${base.ref}, ${base.commit}`;
+  const out = [
+    "# Review",
+    "",
+    `- ${snapshotLine(snapshot)}`,
+    baseLine,
+    `- Changed: ${count(changed.length, "file")} (${changes.committed.length} committed since the base, ${changes.uncommitted.length} uncommitted)`,
+    `- Level: ${session.level}, ${options.levelReason}`,
+    "",
+    "## Validation",
+    "",
+    `${count(graph.artifacts.size, "artifact")}, ${count(session.errors, "error")}, ${count(session.warnings, "warning")} (level ${session.level}, scope: ${repo.config.scope.join(", ")})`,
+  ];
+  if (session.diagnostics.length > 0) {
+    out.push("", "```text", ...session.diagnostics.map((d) => formatDiagnostic(d).trimEnd()), "```");
+  }
+  const sections = levelSections(session);
+  if (sections.length > 0) out.push("", "## Checks above L1", "", "```text", ...sections.slice(1), "```");
+  out.push("", "## Impact of the change", "", REACHABILITY_NOTE);
+  if (impacts.length === 0)
+    out.push("", "No changed file is a record or is claimed by a slice, so nothing was traversed.");
+  for (const item of impacts) {
+    out.push("", `### ${item.start}: ${item.title}`, "", ...item.because.map((reason) => `- Changed: ${reason}`), "");
+    out.push(`Direct (${item.direct.length}), one link away:`);
+    if (item.direct.length === 0) out.push("- none");
+    for (const hit of item.direct) out.push(`- ${hit.id} (${hit.type}): \`${pathText(item.start, hit)}\``);
+    out.push("", `Candidates (${item.candidates.length}), reachable beyond, for review:`);
+    if (item.candidates.length === 0) out.push("- none");
+    for (const hit of item.candidates) out.push(`- ${hit.id} (${hit.type}): \`${pathText(item.start, hit)}\``);
+  }
+  out.push("", `## Changed files no artifact accounts for (${unattributed.length})`, "");
+  if (unattributed.length === 0) out.push("None.");
+  else out.push(...unattributed.map((path) => `- ${path}`));
+  io.stdout(`${out.join("\n")}\n`);
+  return session.errors > 0 ? 1 : 0;
+}

package/src/commands/serve.ts

@@ -0,0 +1,261 @@
+/**
+ * `intentset serve` (Core §10): the Atlas over HTTP on this machine. The
+ * level pipeline runs as validate's does, at the highest level the inputs
+ * allow, and the Atlas is built from what it found. Requests are answered
+ * from that in-memory build and nothing else: GET only, the Atlas's own
+ * paths and atlas.css, 404 for any other path, so there is no file system
+ * behind the server to traverse. Before answering, any file the build read
+ * that has changed since is noticed and the Atlas rebuilt, so an edited
+ * record shows on reload.
+ *
+ * `--out <dir>` writes the same files to a new or empty directory outside
+ * the documents' scope and exits. The Atlas carries internal and restricted
+ * records, and says so: it is a review surface, never a publication.
+ */
+import { mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { dirname, join, resolve } from "node:path";
+import { ARCHITECTURE_CONFIG_PATH } from "@intentset/architecture";
+import { buildAtlas } from "@intentset/atlas";
+import { count, type Io, snapshotLine } from "../output.ts";
+import { outputDirProblem, outputProblem } from "../outputs.ts";
+import { CONFIG_PATH } from "../repository.ts";
+import { EVIDENCE_DIR, evidenceFiles, openSession, type Session, type SessionOptions } from "../session.ts";
+import { TEXT_EXTENSIONS } from "../tree.ts";
+
+export const NOT_FOR_PUBLICATION =
+  "The Atlas shows internal and restricted records: it is a review surface and is not for publication.";
+
+export interface ServeOptions {
+  port: number;
+  host: string;
+  out?: string;
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+};
+
+/** The Atlas built from a session. */
+export function atlasOf(session: Session): Map<string, string> {
+  return buildAtlas({
+    graph: session.result.graph,
+    registries: session.repo.registries,
+    diagnostics: session.diagnostics,
+    snapshot: {
+      commit: session.snapshot.commit,
+      graphHash: session.snapshot.graphHash,
+      scope: session.repo.config.scope,
+      level: session.level,
+    },
+    evidence:
+      session.evidence === undefined
+        ? null
+        : { classification: session.evidence.check.classification, coverage: session.evidence.check.coverage },
+    architecture:
+      session.architecture === undefined
+        ? null
+        : {
+            diagnostics: session.architecture.diagnostics,
+            summary: session.architecture.summary as unknown as Record<string, unknown>,
+          },
+  });
+}
+
+/**
+ * Every file a build read as text, and the directories holding them, absolute:
+ * a newer modification time on any of them means rebuild. A directory's time
+ * changes when a file is added to it or removed, which is how a new record is
+ * noticed.
+ */
+function watched(session: Session, evidence: readonly string[]): string[] {
+  const { repo } = session;
+  const files = new Set<string>([
+    join(repo.root, CONFIG_PATH),
+    join(repo.root, ARCHITECTURE_CONFIG_PATH),
+    join(repo.root, EVIDENCE_DIR),
+    ...evidence,
+    ...repo.inputs.map((input) => join(repo.root, input.path)),
+    // Only what a check reads as text: a log or an image beside the sources cannot change the Atlas.
+    ...[...(session.tree?.paths ?? [])]
+      .filter((path) => TEXT_EXTENSIONS.some((extension) => path.endsWith(extension)))
+      .map((path) => join(repo.root, path)),
+  ]);
+  if (repo.config.registries !== null) files.add(join(repo.root, repo.config.registries));
+  // A file added to or removed from a directory changes the directory's time.
+  for (const file of [...files]) {
+    for (let dir = dirname(file); dir.startsWith(repo.root); dir = dirname(dir)) {
+      files.add(dir);
+      if (dir === repo.root) break;
+    }
+  }
+  return [...files];
+}
+
+function changedSince(paths: readonly string[], since: number): string | null {
+  for (const path of paths) {
+    try {
+      if (statSync(path).mtimeMs > since) return path;
+    } catch {
+      // Absent now: a file the build read was removed, or an optional file never existed.
+    }
+  }
+  return null;
+}
+
+/** The atlas path a request names, or null when it names none. Nothing here touches the file system. */
+export function requestPath(url: string | undefined): string | null {
+  let pathname: string;
+  try {
+    pathname = decodeURIComponent(new URL(url ?? "/", "http://localhost").pathname);
+  } catch {
+    return null;
+  }
+  const path = pathname.replace(/^\/+/, "");
+  return path === "" || path.endsWith("/") ? `${path}index.html` : path;
+}
+
+export async function serveCommand(options: ServeOptions, sessionOptions: SessionOptions, io: Io): Promise<number> {
+  const given = sessionOptions.evidence;
+  let builtAt = Date.now();
+  const first = openSession("serve", sessionOptions, io);
+  if (typeof first === "number") return first;
+  let session: Session = first;
+  let atlas: Map<string, string>;
+  try {
+    atlas = atlasOf(session);
+  } catch (error) {
+    io.stderr(`intentset serve: the Atlas could not be built: ${(error as Error).message}\n`);
+    return 2;
+  }
+  const evidence = () => evidenceFiles(session.repo.root, io.cwd, given);
+  let paths = watched(session, evidence());
+  const levelLine = `${count(session.result.graph.artifacts.size, "artifact")}, ${count(session.errors, "error")}, ${count(session.warnings, "warning")} at ${session.level}${
+    session.evidence === undefined
+      ? `; no run records were given or found in ${EVIDENCE_DIR}/, so L3 was not checked`
+      : ""
+  }`;
+
+  if (options.out !== undefined) return writeAtlas(session, atlas, options.out, levelLine, io);
+
+  /** Rebuild when a file the last build read has changed; keep serving the last good build if a rebuild fails. */
+  const refresh = (): string | null => {
+    const changed = changedSince(paths, builtAt);
+    if (changed === null) return null;
+    const started = Date.now();
+    const next = openSession("serve", sessionOptions, io);
+    if (typeof next === "number") return "the repository could not be read; the terminal says why";
+    try {
+      atlas = atlasOf(next);
+    } catch (error) {
+      return `the Atlas could not be built: ${(error as Error).message}`;
+    }
+    session = next;
+    builtAt = started;
+    paths = watched(session, evidence());
+    io.stdout(
+      `rebuilt: ${changed.slice(session.repo.root.length + 1) || "."} changed. ${snapshotLine(session.snapshot)}\n`,
+    );
+    return null;
+  };
+
+  const handle = (request: IncomingMessage, response: ServerResponse) => {
+    const headers = {
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+      "Content-Security-Policy":
+        "default-src 'none'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; base-uri 'none'; form-action 'none'",
+    };
+    if (request.method !== "GET") {
+      response.writeHead(405, { ...headers, Allow: "GET", "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Only GET is served.\n");
+      return;
+    }
+    const failure = refresh();
+    if (failure !== null) {
+      response.writeHead(500, { ...headers, "Content-Type": "text/plain; charset=utf-8" });
+      response.end(`The Atlas was not rebuilt: ${failure}.\n`);
+      return;
+    }
+    const path = requestPath(request.url);
+    const body = path === null ? undefined : atlas.get(path);
+    if (path === null || body === undefined) {
+      response.writeHead(404, { ...headers, "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Not an Atlas page.\n");
+      return;
+    }
+    const type = TYPES[path.slice(path.lastIndexOf("."))] ?? "application/octet-stream";
+    response.writeHead(200, { ...headers, "Content-Type": type });
+    response.end(body);
+  };
+
+  const server = createServer(handle);
+  return new Promise<number>((done) => {
+    server.once("error", (error) => {
+      io.stderr(`intentset serve: could not listen on ${options.host}:${options.port}: ${error.message}\n`);
+      done(2);
+    });
+    server.listen(options.port, options.host, () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : options.port;
+      const host = options.host.includes(":") ? `[${options.host}]` : options.host;
+      io.stdout(
+        [
+          `Intentset Atlas for ${session.repo.config.repository} at http://${host}:${port}/`,
+          snapshotLine(session.snapshot),
+          levelLine,
+          NOT_FOR_PUBLICATION,
+          "Pages are rebuilt when a file they were built from changes: edit a record and reload. Interrupt to stop.",
+          "",
+        ].join("\n"),
+      );
+      const stop = () => {
+        server.close(() => done(0));
+        server.closeIdleConnections();
+      };
+      if (io.signal?.aborted) stop();
+      else io.signal?.addEventListener("abort", stop, { once: true });
+    });
+  });
+}
+
+function writeAtlas(session: Session, atlas: Map<string, string>, out: string, levelLine: string, io: Io): number {
+  const dir = resolve(io.cwd, out);
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    // Absent: it will be created.
+  }
+  if (entries.length > 0) {
+    io.stderr(`intentset serve: --out ${out} is not empty; write the Atlas into a new or empty directory.\n`);
+    return 2;
+  }
+  const where = outputDirProblem(session.repo, dir);
+  if (where !== null) {
+    io.stderr(`intentset serve: --out ${out} ${where}.\n`);
+    return 2;
+  }
+  for (const path of atlas.keys()) {
+    const problem = outputProblem(session.repo, join(dir, path));
+    if (problem !== null) {
+      io.stderr(`intentset serve: --out ${out}: ${path} ${problem}; nothing was written.\n`);
+      return 2;
+    }
+  }
+  for (const [path, text] of atlas) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text, { flag: "wx" });
+  }
+  io.stdout(
+    [
+      `Wrote the Atlas, ${count(atlas.size, "file")}, to ${out}`,
+      snapshotLine(session.snapshot),
+      levelLine,
+      NOT_FOR_PUBLICATION,
+      "",
+    ].join("\n"),
+  );
+  return session.errors > 0 ? 1 : 0;
+}

package/src/commands/shared.ts

@@ -0,0 +1,46 @@
+/**
+ * What impact and context say before their answer: which snapshot, whether
+ * the graph validated, and the CORE003-style refusal for an ID the graph does
+ * not hold.
+ */
+import { type Diagnostic, ID_PATTERN } from "@intentset/core";
+import { count } from "../output.ts";
+import type { Session } from "../session.ts";
+
+/** The validation state a query ran over, so a reader knows whether the graph was whole. */
+export function validationSummary(session: Session, level: string) {
+  return {
+    level,
+    status: session.result.ok ? ("pass" as const) : ("fail" as const),
+    artifacts: session.result.graph.artifacts.size,
+    errors: session.errors,
+    warnings: session.warnings,
+  };
+}
+
+export function validationLine(session: Session, level: string): string {
+  const v = validationSummary(session, level);
+  const line = `Validation: ${v.status} at ${level}, ${count(v.artifacts, "artifact")}, ${count(v.errors, "error")}, ${count(v.warnings, "warning")}`;
+  return v.status === "pass"
+    ? line
+    : `${line}. The graph may be incomplete; run \`intentset validate\` and fix the errors first.`;
+}
+
+/** Core §5 and §11: an ID that resolves to nothing, reported as CORE003 would report an unresolved link. */
+export function unresolved(id: string, session: Session): Diagnostic {
+  const scope = session.repo.config.scope.join(", ");
+  const malformed = !ID_PATTERN.test(id);
+  return {
+    code: "CORE003",
+    severity: "error",
+    origin: "graph",
+    artifact: null,
+    path: null,
+    message: malformed
+      ? `${id} is not an artifact ID; IDs are upper case, such as BEH-ASMT-SCHEDULE (Core §4).`
+      : `${id} does not resolve to an artifact in this graph (${count(session.result.graph.artifacts.size, "artifact")}, scope: ${scope}).`,
+    remediation: malformed
+      ? "Give the ID as written in the record's frontmatter; IDs are case-sensitive."
+      : "Check the spelling and case, and that the record's file is inside the configured scope.",
+  };
+}

package/src/commands/validate.ts

@@ -0,0 +1,39 @@
+/**
+ * `intentset validate` (Core §11): the documents in scope through every check
+ * the requested level asks for. Diagnostics in `compareDiagnostics` order,
+ * then a summary naming the denominator, the level and the scope, then what
+ * each level above L1 adds: the architecture summary, coverage, publication
+ * readiness. Warnings never fail; errors exit 1. Never writes.
+ */
+import { count, formatDiagnostic, type Io, json, TOOL } from "../output.ts";
+import { levelJson, levelSections } from "../reports.ts";
+import type { Session } from "../session.ts";
+
+export function validateCommand(session: Session, asJson: boolean, io: Io): number {
+  const { repo, diagnostics, errors, warnings, snapshot, level } = session;
+  const artifacts = session.result.graph.artifacts.size;
+  if (asJson) {
+    io.stdout(
+      json({
+        tool: TOOL,
+        level,
+        scope: repo.config.scope,
+        commit: snapshot.commit,
+        ...(snapshot.commitUnavailable === undefined ? {} : { commitUnavailable: snapshot.commitUnavailable }),
+        graphHash: snapshot.graphHash,
+        summary: { documents: repo.inputs.length, artifacts, errors, warnings },
+        diagnostics,
+        ...levelJson(session),
+      }),
+    );
+  } else {
+    for (const d of diagnostics) io.stdout(formatDiagnostic(d));
+    const lines = [
+      `${count(artifacts, "artifact")}, ${count(errors, "error")}, ${count(warnings, "warning")} ` +
+        `(level ${level}, scope: ${repo.config.scope.join(", ")})`,
+      ...levelSections(session),
+    ];
+    io.stdout(`${lines.join("\n")}\n`);
+  }
+  return errors > 0 ? 1 : 0;
+}