@intentset/architecture 0.1.0

package/src/dependencies.ts

@@ -0,0 +1,211 @@
+/**
+ * Declared against observed dependencies (VSA004) and cycles (VSA005).
+ *
+ * VSA004: an observed import from one slice into another that the importer
+ * does not list in `dependsOn`, one finding per pair of slices at the first
+ * import; a consumed contract that no slice exposes, or that more than one
+ * exposes; a consumed contract whose one exposing slice is not depended on.
+ *
+ * VSA005: strongly connected components (Tarjan) over the union of observed
+ * slice edges and declared `dependsOn` edges, type-only imports included
+ * (profile §3: they still count for cycles). One finding per component of
+ * two or more slices, naming them along one concrete cycle.
+ */
+import type { Graph } from "@intentset/core";
+import type { SliceEdge } from "./boundaries.ts";
+import { type Finding, finding, plural } from "./finding.ts";
+import { compareStrings } from "./patterns.ts";
+import type { Model } from "./regions.ts";
+
+export function checkDependencies(
+  model: Model,
+  graph: Graph,
+  sliceEdges: ReadonlyMap<string, SliceEdge>,
+): { findings: Finding[]; cycles: number } {
+  const findings: Finding[] = [];
+
+  for (const key of [...sliceEdges.keys()].sort(compareStrings)) {
+    const { from, to, imports } = sliceEdges.get(key)!;
+    const importer = model.sliceById.get(from)!;
+    if (importer.dependsOn.includes(to)) continue;
+    const first = imports[0];
+    findings.push(
+      finding({
+        code: "VSA004",
+        artifact: from,
+        path: first.from,
+        location: { line: first.line },
+        message: `${from} imports ${to} (${plural(imports.length, "import")}, the first here) but does not declare ${to} in dependsOn.`,
+        remediation: `Add ${to} to links.dependsOn in ${importer.path}, or remove the import (VSA004).`,
+        paths: [...new Set(imports.map((edge) => edge.from)), importer.path],
+        edges: [{ from, to }, ...imports.map((edge) => ({ from: edge.from, to: edge.to as string }))],
+      }),
+    );
+  }
+
+  const exposers = new Map<string, string[]>();
+  for (const slice of model.slices) {
+    for (const contract of slice.exposes) {
+      const list = exposers.get(contract) ?? [];
+      list.push(slice.id);
+      exposers.set(contract, list);
+    }
+  }
+  for (const slice of model.slices) {
+    const consumes = slice.artifact.meta.links.consumes ?? [];
+    consumes.forEach((contract, i) => {
+      const field = `/intentset/links/consumes/${i}`;
+      const owners = (exposers.get(contract) ?? []).sort(compareStrings);
+      const base = { artifact: slice.id, path: slice.path, field, edges: [{ from: slice.id, to: contract }] };
+      if (owners.length === 0) {
+        if (graph.artifacts.get(contract)?.meta.type !== "contract") return; // An unresolved reference is core's CORE003.
+        findings.push(
+          finding({
+            ...base,
+            code: "VSA004",
+            message: `${slice.id} consumes ${contract}, which no slice exposes.`,
+            remediation: `Add ${contract} to the exposes of the slice that maintains it, or stop consuming it (VSA004).`,
+          }),
+        );
+      } else if (owners.length > 1) {
+        findings.push(
+          finding({
+            ...base,
+            code: "VSA004",
+            message: `${slice.id} consumes ${contract}, which ${owners.length} slices expose: ${owners.join(", ")}.`,
+            remediation: `Keep ${contract} in the exposes of the one slice that maintains it (VSA004).`,
+          }),
+        );
+      } else if (owners[0] !== slice.id && !slice.dependsOn.includes(owners[0])) {
+        findings.push(
+          finding({
+            ...base,
+            code: "VSA004",
+            message: `${slice.id} consumes ${contract}, exposed by ${owners[0]}, but does not declare ${owners[0]} in dependsOn.`,
+            remediation: `Add ${owners[0]} to links.dependsOn of ${slice.id}; a consumer lists both consumes and dependsOn (VSA §4).`,
+          }),
+        );
+      }
+    });
+  }
+
+  // Cycles over observed and declared slice edges.
+  const nodes = model.slices.map((slice) => slice.id);
+  const adjacency = new Map<string, Set<string>>(nodes.map((id) => [id, new Set<string>()]));
+  const declared = new Set<string>();
+  for (const slice of model.slices) {
+    for (const target of slice.dependsOn) {
+      if (!adjacency.has(target) || target === slice.id) continue;
+      adjacency.get(slice.id)!.add(target);
+      declared.add(`${slice.id}->${target}`);
+    }
+  }
+  for (const { from, to } of sliceEdges.values()) adjacency.get(from)?.add(to);
+  const successors = new Map([...adjacency].map(([id, set]) => [id, [...set].sort(compareStrings)]));
+  const components = stronglyConnected(nodes, successors).filter((component) => component.length > 1);
+  for (const component of components) {
+    const members = new Set(component);
+    const cycle = shortestCycle(component[0], successors, members);
+    const internal: { from: string; to: string }[] = [];
+    let observed = 0;
+    let written = 0;
+    for (const from of component) {
+      for (const to of successors.get(from) ?? []) {
+        if (!members.has(to)) continue;
+        internal.push({ from, to });
+        if (sliceEdges.has(`${from}->${to}`)) observed++;
+        if (declared.has(`${from}->${to}`)) written++;
+      }
+    }
+    const first = model.sliceById.get(component[0])!;
+    findings.push(
+      finding({
+        code: "VSA005",
+        artifact: first.id,
+        path: first.path,
+        message: `Slices ${component.join(", ")} form a compile-time dependency cycle, ${cycle.join(" -> ")}, from ${plural(observed, "observed import edge")} and ${plural(written, "declared dependsOn edge")}.`,
+        remediation:
+          "Break the cycle: move the shared rule to one owner's contract, invert one dependency, or decouple it through an event contract (VSA005).",
+        paths: component.map((id) => model.sliceById.get(id)!.path),
+        edges: internal,
+      }),
+    );
+  }
+
+  return { findings, cycles: components.length };
+}
+
+/**
+ * Tarjan's strongly connected components. Nodes and successors are visited in
+ * sorted order and each component comes back sorted, components ordered by
+ * their first member, so the output is the same for the same graph.
+ */
+export function stronglyConnected(
+  nodes: readonly string[],
+  successors: ReadonlyMap<string, readonly string[]>,
+): string[][] {
+  let counter = 0;
+  const index = new Map<string, number>();
+  const low = new Map<string, number>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const components: string[][] = [];
+
+  const visit = (node: string): void => {
+    index.set(node, counter);
+    low.set(node, counter);
+    counter++;
+    stack.push(node);
+    onStack.add(node);
+    for (const next of successors.get(node) ?? []) {
+      if (!index.has(next)) {
+        visit(next);
+        low.set(node, Math.min(low.get(node)!, low.get(next)!));
+      } else if (onStack.has(next)) {
+        low.set(node, Math.min(low.get(node)!, index.get(next)!));
+      }
+    }
+    if (low.get(node) === index.get(node)) {
+      const component: string[] = [];
+      let member: string;
+      do {
+        member = stack.pop()!;
+        onStack.delete(member);
+        component.push(member);
+      } while (member !== node);
+      components.push(component.sort(compareStrings));
+    }
+  };
+
+  for (const node of [...nodes].sort(compareStrings)) if (!index.has(node)) visit(node);
+  return components.sort((a, b) => compareStrings(a[0], b[0]));
+}
+
+/** The shortest cycle through `start` inside the component, as a closed path: A -> B -> A. */
+export function shortestCycle(
+  start: string,
+  successors: ReadonlyMap<string, readonly string[]>,
+  members: ReadonlySet<string>,
+): string[] {
+  const previous = new Map<string, string>();
+  const queue: string[] = [start];
+  const seen = new Set<string>([start]);
+  while (queue.length > 0) {
+    const node = queue.shift()!;
+    for (const next of successors.get(node) ?? []) {
+      if (!members.has(next)) continue;
+      if (next === start) {
+        const path = [start];
+        for (let at: string | undefined = node; at !== undefined && at !== start; at = previous.get(at))
+          path.splice(1, 0, at);
+        path.push(start);
+        return path;
+      }
+      if (seen.has(next)) continue;
+      seen.add(next);
+      previous.set(next, node);
+      queue.push(next);
+    }
+  }
+  return [start];
+}

package/src/exceptions.ts

@@ -0,0 +1,269 @@
+/**
+ * Exception records (VSA §9). A record names one rule and the exact paths or
+ * edges it tolerates, with rationale, accountable owner, approver, creation
+ * and expiry dates and a remediation issue. Records live one per file in
+ * `architecture/exceptions/*.yaml` (profile §1), or are handed in.
+ *
+ * A diagnostic a current record covers is kept, never hidden: it becomes a
+ * warning whose message says which exception covers it and until when, so a
+ * report built on it reads "with exceptions" rather than as a pass (Core
+ * §11). An expired record is itself an error, VSA013, and what it covered
+ * stays an error. A record that is malformed is VSA013 and covers nothing; a
+ * current record that covers nothing is a VSA013 warning, so retired
+ * violations retire their exceptions too.
+ */
+import { ID_PATTERN, parseYamlDetailed } from "@intentset/core";
+import { type Finding, finding, type SubjectEdge } from "./finding.ts";
+import { compareStrings, matchPattern, validatePattern } from "./patterns.ts";
+
+export const EXCEPTIONS_PATTERNS = ["architecture/exceptions/*.yaml", "architecture/exceptions/*.yml"];
+
+export interface ExceptionRecord {
+  id: string;
+  rule: string;
+  paths: string[];
+  edges: SubjectEdge[];
+  rationale: string;
+  owner: string;
+  approver: string;
+  /** YYYY-MM-DD. */
+  created: string;
+  /** YYYY-MM-DD, the last day the exception holds. */
+  expires: string;
+  remediation: string;
+  /** The file it was read from, or null when it was handed in. */
+  source: string | null;
+}
+
+const TEXT_FIELDS = ["id", "rule", "rationale", "owner", "approver", "created", "expires", "remediation"] as const;
+const KNOWN_FIELDS = [...TEXT_FIELDS, "paths", "edges"];
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const CODE = /^[A-Z]+[0-9]{3}$/;
+
+function isDate(text: string): boolean {
+  const match = DATE.exec(text);
+  if (match === null) return false;
+  const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  return date.toISOString().slice(0, 10) === text;
+}
+
+/** Validate one record. Returns the record, or the problems that keep it from covering anything. */
+export function readExceptionRecord(
+  value: unknown,
+  source: string | null,
+  lines: ReadonlyMap<string, number> = new Map(),
+): { record: ExceptionRecord | null; findings: Finding[] } {
+  const findings: Finding[] = [];
+  const fail = (field: string | undefined, message: string) => {
+    const line = field === undefined ? undefined : lines.get(field);
+    findings.push(
+      finding({
+        code: "VSA013",
+        artifact: null,
+        path: source,
+        ...(line !== undefined ? { location: { line } } : {}),
+        ...(field !== undefined ? { field } : {}),
+        message,
+        remediation:
+          "An exception records id, rule, paths or edges, rationale, owner, approver, created, expires and remediation (VSA §9).",
+      }),
+    );
+  };
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    fail(undefined, "The exception record is not a mapping.");
+    return { record: null, findings };
+  }
+  const map = value as Record<string, unknown>;
+  for (const key of Object.keys(map).sort(compareStrings)) {
+    if (!KNOWN_FIELDS.includes(key)) fail(`/${key}`, `The exception record has the unknown key \`${key}\`.`);
+  }
+  for (const key of TEXT_FIELDS) {
+    if (typeof map[key] !== "string" || (map[key] as string).trim() === "") {
+      fail(`/${key}`, `The exception record has no \`${key}\`.`);
+    }
+  }
+  const text = (key: (typeof TEXT_FIELDS)[number]) => (typeof map[key] === "string" ? (map[key] as string) : "");
+  if (text("id") !== "" && !ID_PATTERN.test(text("id")))
+    fail("/id", `The exception id ${text("id")} does not match the ID pattern.`);
+  if (text("rule") !== "" && !CODE.test(text("rule")))
+    fail("/rule", `The exception rule ${text("rule")} is not a diagnostic code.`);
+  for (const key of ["created", "expires"] as const) {
+    if (text(key) !== "" && !isDate(text(key)))
+      fail(`/${key}`, `The exception's ${key} date ${text(key)} is not a quoted YYYY-MM-DD date.`);
+  }
+  if (isDate(text("created")) && isDate(text("expires")) && text("expires") < text("created")) {
+    fail("/expires", `The exception expires on ${text("expires")}, before it was created on ${text("created")}.`);
+  }
+
+  const paths: string[] = [];
+  if (map.paths !== undefined && map.paths !== null) {
+    if (!Array.isArray(map.paths)) fail("/paths", "The exception's paths is not a list.");
+    else
+      map.paths.forEach((item, i) => {
+        const why = typeof item === "string" ? validatePattern(item) : "is not a string";
+        if (why !== null) fail(`/paths/${i}`, `Exception path ${i} ${why}.`);
+        else paths.push(item as string);
+      });
+  }
+  const edges: SubjectEdge[] = [];
+  if (map.edges !== undefined && map.edges !== null) {
+    if (!Array.isArray(map.edges)) fail("/edges", "The exception's edges is not a list.");
+    else
+      map.edges.forEach((item, i) => {
+        const edge = item as Record<string, unknown> | null;
+        if (typeof edge !== "object" || edge === null || typeof edge.from !== "string" || typeof edge.to !== "string") {
+          fail(`/edges/${i}`, `Exception edge ${i} is not a mapping with from and to.`);
+        } else edges.push({ from: edge.from, to: edge.to });
+      });
+  }
+  if (paths.length === 0 && edges.length === 0) {
+    fail("/paths", "The exception names no exact paths or edges, and an exception is never a blanket waiver.");
+  }
+  if (findings.length > 0) return { record: null, findings };
+  return {
+    record: {
+      id: text("id"),
+      rule: text("rule"),
+      paths,
+      edges,
+      rationale: text("rationale"),
+      owner: text("owner"),
+      approver: text("approver"),
+      created: text("created"),
+      expires: text("expires"),
+      remediation: text("remediation"),
+      source,
+    },
+    findings,
+  };
+}
+
+/** Every exception file in the tree, read with core's strict YAML reader. */
+export function readExceptions(files: ReadonlyMap<string, string>): {
+  records: ExceptionRecord[];
+  findings: Finding[];
+} {
+  const records: ExceptionRecord[] = [];
+  const findings: Finding[] = [];
+  for (const path of [...files.keys()].sort(compareStrings)) {
+    if (!EXCEPTIONS_PATTERNS.some((pattern) => matchPattern(pattern, path))) continue;
+    const parsed = parseYamlDetailed(files.get(path) as string);
+    if (parsed.error !== null) {
+      findings.push(
+        finding({
+          code: "VSA013",
+          artifact: null,
+          path,
+          location: { line: parsed.error.line },
+          message: `The exception file does not parse: ${parsed.error.message}`,
+          remediation: "Write the exception as one block mapping (VSA §9).",
+        }),
+      );
+      continue;
+    }
+    const read = readExceptionRecord(parsed.value, path, parsed.lines);
+    findings.push(...read.findings);
+    if (read.record !== null) records.push(read.record);
+  }
+  return { records, findings };
+}
+
+/** Does the record name this finding's rule and one of its exact paths or edges? */
+export function covers(record: ExceptionRecord, target: Finding): boolean {
+  if (record.rule !== target.diagnostic.code) return false;
+  if (record.paths.some((pattern) => target.paths.some((path) => matchPattern(pattern, path)))) return true;
+  return record.edges.some((edge) => target.edges.some((other) => other.from === edge.from && other.to === edge.to));
+}
+
+/** Put a note in parentheses before a message's final period. */
+export function annotate(message: string, note: string): string {
+  return message.endsWith(".") ? `${message.slice(0, -1)} (${note}).` : `${message} (${note})`;
+}
+
+/**
+ * Apply exceptions on a given date (YYYY-MM-DD). Returns the findings with
+ * covered ones rewritten, the VSA013 findings about the records themselves,
+ * and how many diagnostics a current exception covers.
+ */
+export function applyExceptions(
+  findings: readonly Finding[],
+  records: readonly ExceptionRecord[],
+  today: string,
+): { findings: Finding[]; excepted: number; recordFindings: Finding[] } {
+  const recordFindings: Finding[] = [];
+  const seen = new Map<string, ExceptionRecord>();
+  const usable: ExceptionRecord[] = [];
+  for (const record of [...records].sort(
+    (a, b) => compareStrings(a.id, b.id) || compareStrings(a.source ?? "", b.source ?? ""),
+  )) {
+    const earlier = seen.get(record.id);
+    if (earlier !== undefined) {
+      recordFindings.push(
+        finding({
+          code: "VSA013",
+          artifact: null,
+          path: record.source,
+          field: "/id",
+          message: `Exception ${record.id} is recorded twice, here and in ${earlier.source ?? "the records handed in"}.`,
+          remediation: "Keep one record per exception ID; IDs are never reused (VSA §9).",
+        }),
+      );
+      continue;
+    }
+    seen.set(record.id, record);
+    usable.push(record);
+  }
+
+  let excepted = 0;
+  const used = new Set<string>();
+  const out = findings.map((item) => {
+    const record = usable.find((candidate) => covers(candidate, item));
+    if (record === undefined) return item;
+    used.add(record.id);
+    if (record.expires < today) {
+      return {
+        ...item,
+        diagnostic: {
+          ...item.diagnostic,
+          message: annotate(item.diagnostic.message, `exception ${record.id} expired ${record.expires}`),
+        },
+      };
+    }
+    excepted++;
+    return {
+      ...item,
+      diagnostic: {
+        ...item.diagnostic,
+        severity: "warning" as const,
+        message: annotate(item.diagnostic.message, `excepted by ${record.id} until ${record.expires}`),
+      },
+    };
+  });
+
+  for (const record of usable) {
+    if (record.expires < today) {
+      recordFindings.push(
+        finding({
+          code: "VSA013",
+          artifact: null,
+          path: record.source,
+          field: "/expires",
+          message: `Exception ${record.id} for ${record.rule} expired on ${record.expires}, so what it covered is an error again.`,
+          remediation: `Fix the violation tracked by ${record.remediation}, or have ${record.approver} renew the exception with a new expiry (VSA §9).`,
+        }),
+      );
+    } else if (!used.has(record.id)) {
+      recordFindings.push(
+        finding({
+          code: "VSA013",
+          severity: "warning",
+          artifact: null,
+          path: record.source,
+          message: `Exception ${record.id} for ${record.rule} covers no current diagnostic.`,
+          remediation: "Remove the record; the violation it tolerated is gone (VSA §9).",
+        }),
+      );
+    }
+  }
+  return { findings: out, excepted, recordFindings };
+}