@intentset/publisher 0.1.0

package/src/project.ts

@@ -0,0 +1,254 @@
+/**
+ * The audience and release projection (Core §9, catalog P01, P03-P06).
+ *
+ * Deny by default: an artifact is eligible only when every check passes, and
+ * the first that fails is recorded as the reason it was excluded, so a report
+ * can count exclusions by kind. The checks, in order:
+ *
+ *   not-requested         the request names ids and this is not one of them
+ *   not-knowledge         only knowledge is ever published as a document
+ *   draft, retired        Core §7: neither is current publication
+ *   visibility            outside what the projection admits
+ *   audience              the request's audience is not one the knowledge is written for
+ *   availability-missing  no availability block: fails closed (Core §4, §7)
+ *   product ... edition   the request's value is not in that dimension's list (AND across, OR within)
+ *   flag                  the knowledge needs a flag the request does not name (all named flags required)
+ *   needs-review          a source changed since review, a pin is missing, or no reviewer (review.ts)
+ *
+ * An explicitly requested ID that is not eligible is CORE008. Its message
+ * names the reason class, and nothing about the artifact beyond its ID. When
+ * the artifact's visibility is outside the projection, or no artifact has the
+ * ID, the message is the same in both cases and carries no path: a caller
+ * without the authorization cannot learn whether an internal ID exists.
+ */
+import { type Artifact, type Diagnostic, type Graph, type Registries, graphHash } from "@intentset/core";
+import { compareStrings, publicationDiagnostic } from "./diagnostic.ts";
+import { type PublicationRequest, admits, checkRequest } from "./request.ts";
+import { type ReviewStatus, reviewStatus } from "./review.ts";
+
+export const EXCLUSION_REASONS = [
+  "not-requested",
+  "not-knowledge",
+  "draft",
+  "retired",
+  "visibility",
+  "audience",
+  "availability-missing",
+  "product",
+  "release",
+  "role",
+  "edition",
+  "flag",
+  "needs-review",
+] as const;
+export type ExclusionReason = (typeof EXCLUSION_REASONS)[number];
+
+/** The snapshot a publication is made from (Core §7): the commit, or null when none could be read, and the graph hash. */
+export interface Snapshot {
+  commit: string | null;
+  graphHash: string;
+}
+
+export interface ProjectOptions {
+  snapshot: Snapshot;
+  /** Review statuses already computed, by knowledge ID; `reviewStatus` is used for any not given. */
+  reviews?: ReadonlyMap<string, ReviewStatus>;
+}
+
+export interface Exclusion {
+  id: string;
+  reason: ExclusionReason;
+}
+
+export interface Projection {
+  /** Eligible knowledge, sorted by ID. */
+  eligible: Artifact[];
+  /** Every other artifact in the graph with the first check it failed, sorted by ID. Empty when the request was refused. */
+  excluded: Exclusion[];
+  diagnostics: Diagnostic[];
+  /** The checked request, or null when it was refused (PUB001). */
+  request: PublicationRequest | null;
+}
+
+const PUBLISHABLE_STATUSES = new Set(["approved", "implemented", "released", "deprecated"]);
+
+/** Core §9: select what this request may publish, before any text is sent to a renderer. */
+export function project(
+  graph: Graph,
+  registries: Registries,
+  request: PublicationRequest,
+  options: ProjectOptions,
+): Projection {
+  const checked = checkRequest(request, graph, registries);
+  const diagnostics = [...checked.diagnostics];
+  if (graphHash(graph) !== options.snapshot.graphHash) {
+    diagnostics.push(
+      publicationDiagnostic({
+        code: "PUB001",
+        artifact: null,
+        path: null,
+        message: "The snapshot's graph hash is not the hash of the graph being published.",
+        remediation:
+          "Publish from the graph the snapshot names; provenance must identify the exact snapshot (Core §7, §9).",
+      }),
+    );
+  }
+  if (checked.request === null || diagnostics.length > 0) {
+    return { eligible: [], excluded: [], diagnostics, request: null };
+  }
+  const req = checked.request;
+  const requested = req.ids === undefined ? null : new Set(req.ids);
+  const reviews = new Map<string, ReviewStatus>(options.reviews ?? []);
+  const review = (artifact: Artifact): ReviewStatus => {
+    let status = reviews.get(artifact.meta.id);
+    if (status === undefined) {
+      status = reviewStatus(graph, artifact);
+      reviews.set(artifact.meta.id, status);
+    }
+    return status;
+  };
+
+  const eligible: Artifact[] = [];
+  const excluded: Exclusion[] = [];
+  const reasons = new Map<string, ExclusionReason>();
+  for (const id of [...graph.artifacts.keys()].sort(compareStrings)) {
+    const artifact = graph.artifacts.get(id) as Artifact;
+    const reason = requested !== null && !requested.has(id) ? "not-requested" : exclusionReason(artifact, req, review);
+    if (reason === null) eligible.push(artifact);
+    else {
+      excluded.push({ id, reason });
+      reasons.set(id, reason);
+    }
+  }
+
+  for (const id of req.ids ?? []) {
+    const reason = reasons.get(id);
+    const artifact = graph.artifacts.get(id);
+    if (artifact !== undefined && reason === undefined) continue;
+    diagnostics.push(refusal(id, artifact, reason ?? null, req, artifact === undefined ? null : review(artifact)));
+  }
+  return { eligible, excluded, diagnostics, request: req };
+}
+
+/** The first check an artifact fails for this request, or null when it is eligible. Requested-ness is the caller's. */
+export function exclusionReason(
+  artifact: Artifact,
+  request: PublicationRequest,
+  review: (artifact: Artifact) => ReviewStatus,
+): Exclude<ExclusionReason, "not-requested"> | null {
+  const { meta } = artifact;
+  if (meta.type !== "knowledge") return "not-knowledge";
+  if (meta.status === "draft") return "draft";
+  if (meta.status === "retired") return "retired";
+  if (!PUBLISHABLE_STATUSES.has(meta.status)) return "draft";
+  if (!admits(request, meta.visibility)) return "visibility";
+  if (!meta.audiences.includes(request.audience)) return "audience";
+  const availability = meta.availability;
+  if (availability === undefined) return "availability-missing";
+  if (!availability.products.includes(request.product)) return "product";
+  if (!availability.releases.includes(request.release)) return "release";
+  if (!availability.roles.includes(request.role)) return "role";
+  if (!availability.editions.includes(request.edition)) return "edition";
+  if (!availability.flags.every((flag) => request.flags.includes(flag))) return "flag";
+  if (review(artifact).status !== "current") return "needs-review";
+  return null;
+}
+
+/** CORE008 for one requested ID. */
+function refusal(
+  id: string,
+  artifact: Artifact | undefined,
+  reason: ExclusionReason | null,
+  request: PublicationRequest,
+  review: ReviewStatus | null,
+): Diagnostic {
+  if (artifact === undefined || !admits(request, artifact.meta.visibility)) {
+    return publicationDiagnostic({
+      code: "CORE008",
+      artifact: id,
+      path: null,
+      message: `${id} was requested but is not publishable (visibility): no artifact with that ID is visible to a ${request.visibility} projection.`,
+      remediation:
+        "Request only knowledge this projection admits; anything else needs a separately authorized projection (Core §9).",
+    });
+  }
+  const { meta } = artifact;
+  const at = { artifact: id, path: artifact.path };
+  const refuse = (field: string | undefined, detail: string, remediation: string) =>
+    publicationDiagnostic({
+      code: "CORE008",
+      ...at,
+      field,
+      message: `${id} was requested but is not publishable (${reason}): ${detail}.`,
+      remediation,
+    });
+  switch (reason) {
+    case "not-knowledge":
+      return refuse(
+        "/intentset/type",
+        `it is a ${meta.type}, and only knowledge is published`,
+        "Request the knowledge that explains it; engineering artifacts are never published as documents (Core §9).",
+      );
+    case "draft":
+      return refuse(
+        "/intentset/status",
+        `its status is ${meta.status}, and drafts are never published`,
+        "Review the knowledge and set its status to approved or later before publishing it (Core §7, §9).",
+      );
+    case "retired":
+      return refuse(
+        "/intentset/status",
+        "it is retired, which is excluded from current publication",
+        "Publish the successor named in replacedBy instead (Core §7).",
+      );
+    case "audience":
+      return refuse(
+        "/intentset/audiences",
+        `it is not written for the ${request.audience} audience`,
+        "Request an audience the knowledge lists, or add this one after reviewing the text for it (Core §9).",
+      );
+    case "availability-missing":
+      return refuse(
+        "/intentset/availability",
+        "it declares no availability, so publication fails closed",
+        "Add availability with products, releases, roles, editions and flags (Core §7).",
+      );
+    case "product":
+    case "release":
+    case "role":
+    case "edition":
+      return refuse(
+        `/intentset/availability/${reason}s`,
+        `it is not available for ${reason} ${request[reason]}`,
+        `Request a ${reason} the knowledge lists, or extend its availability after review; values match exactly (Core §7).`,
+      );
+    case "flag": {
+      const needed = (meta.availability?.flags ?? [])
+        .filter((flag) => !request.flags.includes(flag))
+        .sort(compareStrings);
+      return refuse(
+        "/intentset/availability/flags",
+        `it requires flag${needed.length === 1 ? "" : "s"} ${needed.join(", ")}, which the request does not name`,
+        "Request every flag the knowledge names; all named flags are required (Core §7).",
+      );
+    }
+    default:
+      return refuse(
+        review !== null && review.reviewer === null
+          ? "/intentset/reviewedBy"
+          : `/intentset/extensions/intentset.org~1review`,
+        `it needs review because ${describeReview(review)}`,
+        "Review the knowledge against its current sources, then update reviewedBy, reviewedAt and the intentset.org/review pins (Core §9).",
+      );
+  }
+}
+
+function describeReview(review: ReviewStatus | null): string {
+  if (review === null) return "its review could not be read";
+  const parts: string[] = [];
+  if (review.changed.length > 0) parts.push(`${review.changed.join(", ")} changed since it was reviewed`);
+  if (review.missing.length > 0) parts.push(`its review pins nothing for ${review.missing.join(", ")}`);
+  if (review.reviewer === null) parts.push("it names no reviewer");
+  if (review.reviewedAt === null) parts.push("it gives no review date");
+  return parts.length === 0 ? "its review is not current" : parts.join(", and ");
+}

package/src/publish.ts

@@ -0,0 +1,177 @@
+/**
+ * Publication (Core §9): project, check references, generate, render.
+ *
+ *   canonical files -> validated graph -> exact snapshot
+ *     -> authorized audience projection (project.ts)
+ *     -> reviewed knowledge (review.ts)
+ *     -> references and titles checked (references.ts)
+ *     -> generated Markset (generate.ts) -> HTML
+ *
+ * Selection happens before any text reaches a renderer. A document whose
+ * references, titles or Markset fail is not emitted. Links are checked against
+ * what is actually being published, so a document that links to one refused
+ * here is refused in turn; this repeats until nothing more is refused.
+ *
+ * The index is what a customer-facing tool may read (Core §10): the snapshot,
+ * the request without its authorization flags, the published IDs, and the
+ * number of artifacts excluded for each reason. It names nothing that was not
+ * published.
+ *
+ * Deterministic: the same graph, request, snapshot and `publishedAt` give the
+ * same bytes.
+ */
+import { readFileSync } from "node:fs";
+import {
+  type Artifact,
+  type Diagnostic,
+  type Graph,
+  type Registries,
+  canonicalJson,
+  hasErrors,
+  sortDiagnostics,
+} from "@intentset/core";
+import { parseDocument } from "@markset-lang/parser";
+import { defaultStylesheetPath, renderPage } from "@markset-lang/render-html";
+import { compareStrings } from "./diagnostic.ts";
+import { type GeneratedDocument, type PublicationMeta, generateDocument } from "./generate.ts";
+import { type ExclusionReason, type Snapshot, project } from "./project.ts";
+import { checkReferences, checkTitles } from "./references.ts";
+import { type IndexedRequest, type PublicationRequest, admits, indexedRequest } from "./request.ts";
+import type { ReviewStatus } from "./review.ts";
+
+/** Why a document that passed the projection was still not published. */
+export const REFUSAL_REASONS = ["reference", "title", "directive", "markset"] as const;
+export type RefusalReason = (typeof REFUSAL_REASONS)[number];
+
+export interface PublishOptions {
+  snapshot: Snapshot;
+  /** The publication timestamp written into every document; an input, so output is reproducible. */
+  publishedAt: string;
+  /** Also render each document as a complete HTML page with Markset's default stylesheet inlined. */
+  renderHtml?: boolean;
+  reviews?: ReadonlyMap<string, ReviewStatus>;
+}
+
+export interface PublishedDocument extends GeneratedDocument {
+  html?: string;
+}
+
+export interface PublicationIndex {
+  snapshot: Snapshot;
+  /** The request without authorization flags, or null when it was refused. */
+  request: IndexedRequest | null;
+  published: string[];
+  /** Exclusions by reason, keys sorted, zero counts left out. */
+  excludedCounts: Record<string, number>;
+}
+
+export interface PublishResult {
+  documents: PublishedDocument[];
+  index: PublicationIndex;
+  diagnostics: Diagnostic[];
+  ok: boolean;
+}
+
+export function publish(
+  graph: Graph,
+  registries: Registries,
+  request: PublicationRequest,
+  options: PublishOptions,
+): PublishResult {
+  const projection = project(graph, registries, request, { snapshot: options.snapshot, reviews: options.reviews });
+  const diagnostics = [...projection.diagnostics];
+  const counts = new Map<string, number>();
+  const count = (reason: ExclusionReason | RefusalReason) => counts.set(reason, (counts.get(reason) ?? 0) + 1);
+  // Only what the projection could see is counted: a customer index that said
+  // "not-knowledge: 12" would tell its reader how many internal records exist.
+  // A refused request admits nothing, so it counts nothing (invariant 4).
+  for (const exclusion of projection.excluded) {
+    const visibility = graph.artifacts.get(exclusion.id)?.meta.visibility;
+    if (projection.request !== null && visibility !== undefined && admits(projection.request, visibility)) {
+      count(exclusion.reason);
+    }
+  }
+
+  const req = projection.request;
+  const documents: PublishedDocument[] = [];
+  if (req !== null) {
+    const candidates = projection.eligible;
+    const allowedTitles = new Set(candidates.map((artifact) => artifact.meta.title.trim()));
+    const refused = new Map<string, RefusalReason>();
+    const generated = new Map<string, GeneratedDocument>();
+
+    for (const artifact of candidates) {
+      const titles = checkTitles(artifact, graph, req, allowedTitles);
+      const result = generateDocument(graph, artifact, req, options);
+      diagnostics.push(...titles, ...result.diagnostics);
+      if (result.document !== null) generated.set(artifact.meta.id, result.document);
+      if (titles.length > 0) refused.set(artifact.meta.id, "title");
+      else if (result.diagnostics.some((d) => d.code === "PUB004")) refused.set(artifact.meta.id, "directive");
+      else if (result.document === null) refused.set(artifact.meta.id, "markset");
+    }
+
+    let published = new Set(candidates.map((artifact) => artifact.meta.id).filter((id) => !refused.has(id)));
+    let round: Artifact[] = candidates;
+    while (round.length > 0) {
+      const failed: string[] = [];
+      for (const artifact of round) {
+        const found = checkReferences(artifact, graph, req, published);
+        if (found.length === 0) continue;
+        diagnostics.push(...found);
+        failed.push(artifact.meta.id);
+        refused.set(artifact.meta.id, "reference");
+      }
+      published = new Set([...published].filter((id) => !failed.includes(id)));
+      round = failed.length === 0 ? [] : candidates.filter((artifact) => published.has(artifact.meta.id));
+    }
+
+    for (const reason of refused.values()) count(reason);
+    for (const id of [...published].sort(compareStrings)) {
+      const document: PublishedDocument = { ...(generated.get(id) as GeneratedDocument) };
+      if (options.renderHtml === true) document.html = renderDocument(document.markset, document.publication);
+      documents.push(document);
+    }
+  }
+
+  const excludedCounts: Record<string, number> = {};
+  for (const reason of [...counts.keys()].sort(compareStrings)) excludedCounts[reason] = counts.get(reason) as number;
+  const sorted = sortDiagnostics(diagnostics);
+  return {
+    documents,
+    index: {
+      snapshot: { commit: options.snapshot.commit, graphHash: options.snapshot.graphHash },
+      request: req === null ? null : indexedRequest(req),
+      published: documents.map((document) => document.id),
+      excludedCounts,
+    },
+    diagnostics: sorted,
+    ok: !hasErrors(sorted),
+  };
+}
+
+let stylesheet: string | null = null;
+
+/** Markset's default stylesheet, read once. */
+function defaultStylesheet(): string {
+  stylesheet ??= readFileSync(defaultStylesheetPath, "utf8");
+  return stylesheet;
+}
+
+/**
+ * A complete page through render-html, with the provenance block carried into
+ * the head, after the charset, as one `<meta name="intentset-publication">`
+ * whose content is the block's canonical JSON, so the HTML keeps what the
+ * Markset source keeps.
+ */
+export function renderDocument(markset: string, publication: PublicationMeta): string {
+  const page = renderPage(parseDocument(markset).ast, { stylesheet: { inline: defaultStylesheet() } });
+  const meta = `<meta name="intentset-publication" content="${escapeAttribute(canonicalJson(publication))}">\n`;
+  const anchor = '<meta charset="utf-8">\n';
+  const at = page.indexOf(anchor);
+  if (at === -1) throw new Error("render-html returned a page without a charset declaration");
+  return page.slice(0, at + anchor.length) + meta + page.slice(at + anchor.length);
+}
+
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/src/references.ts

@@ -0,0 +1,226 @@
+/**
+ * References out of a knowledge body (Core §9, catalog P02).
+ *
+ * A published document may refer only to what its projection may show. Three
+ * kinds of reference are found:
+ *
+ *   id    a bare artifact ID in the text, word-bounded, code included
+ *   link  a Markdown link, image or definition, or an href/src in raw HTML,
+ *         whose destination resolves to an artifact's file
+ *   path  an artifact's repository path written out in the text
+ *
+ * An ID reference fails when the artifact's visibility is outside the
+ * projection: the ID itself is then something this audience is not shown. A
+ * link or path reference fails when the artifact is not published in this
+ * projection, since the reader would be sent to, or told of, a canonical
+ * file. The product the request names is not a leak when mentioned by ID.
+ *
+ * Separately, the text may not contain the title of an artifact the
+ * projection does not admit (three or more words, case-sensitive, any run of
+ * whitespace between words), unless that title is also the title of
+ * something being published. That is PUB002.
+ *
+ * Every message names the referencing document and the referenced ID, and
+ * never the referenced artifact's title or path.
+ */
+import { posix } from "node:path";
+import { type Artifact, type Diagnostic, type Graph, ID_PATTERN } from "@intentset/core";
+import { parseDocument } from "@markset-lang/parser";
+import { bodyLineOffset, fileLocation, lineAt } from "./body.ts";
+import { compareStrings, publicationDiagnostic } from "./diagnostic.ts";
+import { type PublicationRequest, admits } from "./request.ts";
+
+export type ReferenceKind = "id" | "link" | "path";
+
+export interface Reference {
+  /** The referenced artifact's ID. */
+  id: string;
+  via: ReferenceKind;
+  /** 1-based line in the body. */
+  line: number;
+}
+
+/** ID_PATTERN, unanchored and bounded so it does not match inside a longer token. */
+const VIA_WORDS: Record<ReferenceKind, string> = { id: "ID", link: "link", path: "path" };
+
+/** "ID", "ID and link", "ID, link and path". */
+function listing(words: readonly string[]): string {
+  return words.length < 2 ? words.join("") : `${words.slice(0, -1).join(", ")} and ${words[words.length - 1]}`;
+}
+
+const ID_IN_TEXT = new RegExp(`(?<![A-Za-z0-9_-])${ID_PATTERN.source.slice(1, -1)}(?![A-Za-z0-9_-])`, "g");
+const HTML_TARGET = /\b(?:href|src)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+
+/** Every reference from a knowledge body to another artifact in the graph, sorted by ID, kind, line. */
+export function findReferences(artifact: Artifact, graph: Graph): Reference[] {
+  const self = artifact.meta.id;
+  const body = artifact.body;
+  const found: Reference[] = [];
+  const add = (id: string, via: ReferenceKind, line: number) => {
+    if (id !== self && graph.artifacts.has(id)) found.push({ id, via, line });
+  };
+
+  for (const match of body.matchAll(ID_IN_TEXT)) add(match[0], "id", lineAt(body, match.index));
+
+  const byPath = new Map<string, string>();
+  for (const [id, other] of graph.artifacts) byPath.set(other.path, id);
+  const visit = (node: unknown): void => {
+    if (typeof node !== "object" || node === null) return;
+    const n = node as {
+      type?: string;
+      url?: unknown;
+      value?: unknown;
+      position?: { start: { line: number } };
+      children?: unknown[];
+    };
+    const line = n.position?.start.line ?? 1;
+    const targets: string[] = [];
+    if ((n.type === "link" || n.type === "image" || n.type === "definition") && typeof n.url === "string")
+      targets.push(n.url);
+    if (n.type === "html" && typeof n.value === "string") {
+      for (const match of n.value.matchAll(HTML_TARGET)) targets.push(match[1] ?? match[2] ?? "");
+    }
+    for (const url of targets) {
+      const path = resolveTarget(url, artifact.path);
+      const id = path === null ? undefined : byPath.get(path);
+      if (id !== undefined) add(id, "link", line);
+    }
+    for (const child of n.children ?? []) visit(child);
+  };
+  visit(parseDocument(body).ast);
+
+  for (const [id, other] of graph.artifacts) {
+    let from = 0;
+    for (;;) {
+      const index = body.indexOf(other.path, from);
+      if (index === -1) break;
+      const before = index === 0 ? "" : body[index - 1];
+      const after = body[index + other.path.length] ?? "";
+      if (!/[A-Za-z0-9_./-]/.test(before) && !/[A-Za-z0-9_/-]/.test(after)) {
+        add(id, "path", lineAt(body, index));
+        break;
+      }
+      from = index + 1;
+    }
+  }
+
+  return found.sort((a, b) => compareStrings(a.id, b.id) || compareStrings(a.via, b.via) || a.line - b.line);
+}
+
+/**
+ * Resolve a link destination against the linking document to a repository
+ * path. Null for anything that is not a repository file: a URL with a scheme,
+ * a protocol-relative URL, a fragment, or a path that leaves the repository.
+ */
+export function resolveTarget(url: string, fromPath: string): string | null {
+  const trimmed = url.trim();
+  if (
+    trimmed === "" ||
+    trimmed.startsWith("#") ||
+    trimmed.startsWith("//") ||
+    /^[A-Za-z][A-Za-z0-9+.-]*:/.test(trimmed)
+  ) {
+    return null;
+  }
+  let target = trimmed.split("#")[0].split("?")[0];
+  try {
+    target = decodeURIComponent(target);
+  } catch {
+    // A malformed escape is compared as written.
+  }
+  if (target === "") return null;
+  const joined = target.startsWith("/") ? target.replace(/^\/+/, "") : posix.join(posix.dirname(fromPath), target);
+  const normal = posix.normalize(joined);
+  if (normal === ".." || normal.startsWith("../")) return null;
+  return normal.replace(/^\.\//, "");
+}
+
+/**
+ * CORE008 for each referenced artifact this projection may not show: one
+ * diagnostic per referenced ID, at the first failing reference's line.
+ */
+export function checkReferences(
+  artifact: Artifact,
+  graph: Graph,
+  request: PublicationRequest,
+  published: ReadonlySet<string>,
+): Diagnostic[] {
+  const offset = bodyLineOffset(artifact);
+  const failing = new Map<string, Reference[]>();
+  for (const ref of findReferences(artifact, graph)) {
+    const target = graph.artifacts.get(ref.id) as Artifact;
+    const fails =
+      ref.via === "id"
+        ? ref.id !== request.product && !admits(request, target.meta.visibility)
+        : !published.has(ref.id);
+    if (!fails) continue;
+    const list = failing.get(ref.id);
+    if (list === undefined) failing.set(ref.id, [ref]);
+    else list.push(ref);
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const id of [...failing.keys()].sort(compareStrings)) {
+    const refs = failing.get(id) as Reference[];
+    const vias = [...new Set(refs.map((ref) => VIA_WORDS[ref.via]))];
+    const first = Math.min(...refs.map((ref) => ref.line));
+    diagnostics.push(
+      publicationDiagnostic({
+        code: "CORE008",
+        artifact: artifact.meta.id,
+        path: artifact.path,
+        location: fileLocation(offset, first),
+        message: `${artifact.meta.id} refers to ${id} by ${listing(vias)}, which this ${request.visibility} projection does not publish.`,
+        remediation:
+          "Remove the reference, or replace it with reviewed wording safe for this audience; a published document may refer only to what its projection shows (Core §9).",
+      }),
+    );
+  }
+  return diagnostics;
+}
+
+/**
+ * PUB002 for each artifact outside the projection whose title (three or more
+ * words) the body contains, unless that title is in `allowedTitles` (the
+ * document's own and those of what is being published).
+ */
+export function checkTitles(
+  artifact: Artifact,
+  graph: Graph,
+  request: PublicationRequest,
+  allowedTitles: ReadonlySet<string>,
+): Diagnostic[] {
+  const offset = bodyLineOffset(artifact);
+  const diagnostics: Diagnostic[] = [];
+  for (const id of [...graph.artifacts.keys()].sort(compareStrings)) {
+    const other = graph.artifacts.get(id) as Artifact;
+    if (id === artifact.meta.id || admits(request, other.meta.visibility)) continue;
+    const title = other.meta.title.trim();
+    if (title.split(/\s+/).length < 3 || allowedTitles.has(title)) continue;
+    const match = titlePattern(title).exec(artifact.body);
+    if (match === null) continue;
+    diagnostics.push(
+      publicationDiagnostic({
+        code: "PUB002",
+        artifact: artifact.meta.id,
+        path: artifact.path,
+        location: fileLocation(offset, lineAt(artifact.body, match.index)),
+        message: `${artifact.meta.id} contains the title of ${id}, which this ${request.visibility} projection does not admit.`,
+        remediation:
+          "Reword the guidance so it does not repeat the title of an artifact this audience may not see (Core §9).",
+      }),
+    );
+  }
+  return diagnostics;
+}
+
+/** The title as a case-sensitive pattern: any whitespace between words, word-bounded at either end that is a word character. */
+export function titlePattern(title: string): RegExp {
+  const words = title.trim().split(/\s+/).map(escapeRegExp);
+  const start = /^[\p{L}\p{N}_]/u.test(title.trim()) ? "(?<![\\p{L}\\p{N}_])" : "";
+  const end = /[\p{L}\p{N}_]$/u.test(title.trim()) ? "(?![\\p{L}\\p{N}_])" : "";
+  return new RegExp(`${start}${words.join("\\s+")}${end}`, "u");
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}