@intentset/core 0.1.0

package/src/graph.ts

@@ -0,0 +1,49 @@
+/**
+ * The typed graph (Core §5, §12): authored edges in the direction they are
+ * written, and one derived inverse per authored edge, marked derived.
+ */
+import { type Artifact, type Edge, type Graph, LINK_KINDS } from "./types.ts";
+
+/**
+ * Core §5 and §12: build the graph from artifacts whose IDs are already
+ * unique. Edges follow document order (the order given) then field order
+ * (`parent`, then the Core §5 table). Edges to IDs that are not in the graph
+ * are kept as authored; the validator reports them.
+ */
+export function buildGraph(artifacts: readonly Artifact[]): Graph {
+  const map = new Map<string, Artifact>();
+  const edges: Edge[] = [];
+  for (const artifact of artifacts) {
+    const { meta } = artifact;
+    map.set(meta.id, artifact);
+    if (meta.parent !== undefined) edges.push({ kind: "parent", from: meta.id, to: meta.parent, derived: false });
+    for (const kind of LINK_KINDS) {
+      if (kind === "parent") continue;
+      for (const to of meta.links[kind] ?? []) edges.push({ kind, from: meta.id, to, derived: false });
+    }
+  }
+  const derived: Edge[] = edges.map((edge) => ({ kind: edge.kind, from: edge.to, to: edge.from, derived: true }));
+  const out = new Map<string, Edge[]>();
+  const incoming = new Map<string, Edge[]>();
+  for (const edge of edges) {
+    push(out, edge.from, edge);
+    push(incoming, edge.to, edge);
+  }
+  return { artifacts: map, edges, derived, out, in: incoming };
+}
+
+function push(map: Map<string, Edge[]>, key: string, edge: Edge): void {
+  const list = map.get(key);
+  if (list === undefined) map.set(key, [edge]);
+  else list.push(edge);
+}
+
+/** Core §5: authored edges of one kind leaving an artifact. */
+export function outgoing(graph: Graph, id: string, kind: Edge["kind"]): Edge[] {
+  return (graph.out.get(id) ?? []).filter((edge) => edge.kind === kind);
+}
+
+/** Core §5: authored edges of one kind arriving at an artifact, the authored side of a derived inverse. */
+export function incomingEdges(graph: Graph, id: string, kind: Edge["kind"]): Edge[] {
+  return (graph.in.get(id) ?? []).filter((edge) => edge.kind === kind);
+}

package/src/hash.ts

@@ -0,0 +1,53 @@
+/**
+ * Canonical JSON and SHA-256 (ADR 0005). Everything hashed goes through
+ * `canonicalJson`, so the same value is the same bytes on every machine.
+ */
+import { createHash } from "node:crypto";
+import type { Graph, LinkKind } from "./types.ts";
+
+/** ADR 0005: JSON with keys sorted recursively and no whitespace. `undefined` members are omitted, as JSON.stringify omits them. */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+/** ADR 0005: the same value with every object's keys in sorted order, arrays untouched. */
+export function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (typeof value === "object" && value !== null) {
+    const record = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(record).sort()) {
+      if (record[key] !== undefined) out[key] = sortKeysDeep(record[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** ADR 0005: lowercase hex SHA-256 of a string's UTF-8 bytes or of raw bytes. */
+export function sha256Hex(input: string | Uint8Array): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * ADR 0005: SHA-256 of the canonical JSON of the sorted list of
+ * `{ id, type, sourceHash, links }`, where `links` holds the artifact's
+ * authored edges by kind (`parent` included) with each target list sorted.
+ * Timestamps and commits stay outside, so the same files at two commits hash
+ * the same.
+ */
+export function graphHash(graph: Graph): string {
+  const entries = [...graph.artifacts.keys()].sort().map((id) => {
+    const artifact = graph.artifacts.get(id);
+    if (artifact === undefined) throw new Error(`graph has no artifact ${id}`);
+    const links: Partial<Record<LinkKind, string[]>> = {};
+    for (const edge of graph.out.get(id) ?? []) {
+      const list = links[edge.kind];
+      if (list === undefined) links[edge.kind] = [edge.to];
+      else list.push(edge.to);
+    }
+    for (const kind of Object.keys(links) as LinkKind[]) links[kind]?.sort();
+    return { id, type: artifact.meta.type, sourceHash: artifact.sourceHash, links };
+  });
+  return sha256Hex(canonicalJson(entries));
+}

package/src/impact.ts

@@ -0,0 +1,90 @@
+/**
+ * Impact traversal (Core §10). From a starting ID, the artifacts one
+ * derived edge away are direct; everything reachable beyond them by further
+ * reverse traversal, with a visited set, is a candidate; the start's own
+ * rules, contracts and decisions are review context; navigation ancestors
+ * come through `parent`. Each hit carries the path that reached it, with a
+ * reason sentence per step. Reachability is recorded, never asserted as
+ * proof that runtime behavior changed.
+ */
+import { compareStrings } from "./report.ts";
+import type { Edge, Graph, ImpactHit, ImpactReport, ImpactStep, LinkKind } from "./types.ts";
+
+const PHRASES: Record<LinkKind, string> = {
+  parent: "has {to} as its navigation parent",
+  governedBy: "is governed by {to}",
+  illustrates: "illustrates {to}",
+  implements: "implements {to}",
+  dependsOn: "depends on {to}",
+  exposes: "exposes {to}",
+  consumes: "consumes {to}",
+  verifies: "verifies {to}",
+  explains: "explains {to}",
+  informedBy: "is informed by {to}",
+  requires: "requires {to}",
+  supports: "supports {to}",
+  replacedBy: "is replaced by {to}",
+};
+
+const CONTEXT_KINDS: readonly LinkKind[] = ["governedBy", "exposes", "consumes", "informedBy"];
+
+/** Core §10: the reason recorded for one step, a sentence read from the authored edge's source. */
+export function reasonFor(edge: Edge): string {
+  return `${edge.from} ${PHRASES[edge.kind].replace("{to}", edge.to)}.`;
+}
+
+/** Core §10: the impact report for an artifact. An ID not in the graph yields an empty report. */
+export function impact(graph: Graph, id: string): ImpactReport {
+  const report: ImpactReport = { start: id, direct: [], candidates: [], context: [], ancestors: [] };
+  if (!graph.artifacts.has(id)) return report;
+
+  const paths = new Map<string, ImpactStep[]>();
+  const queue: string[] = [id];
+  paths.set(id, []);
+  while (queue.length > 0) {
+    const current = queue.shift() as string;
+    const sofar = paths.get(current) as ImpactStep[];
+    const arriving = [...(graph.in.get(current) ?? [])].sort(
+      (a, b) => compareStrings(a.from, b.from) || compareStrings(a.kind, b.kind),
+    );
+    for (const edge of arriving) {
+      if (paths.has(edge.from)) continue;
+      paths.set(edge.from, [...sofar, { id: edge.from, via: `${edge.kind}←`, reason: reasonFor(edge) }]);
+      queue.push(edge.from);
+    }
+  }
+  for (const hitId of [...paths.keys()].sort(compareStrings)) {
+    if (hitId === id) continue;
+    const path = paths.get(hitId) as ImpactStep[];
+    const hit = toHit(graph, hitId, path);
+    if (hit === null) continue;
+    if (path.length === 1) report.direct.push(hit);
+    else report.candidates.push(hit);
+  }
+
+  const contextEdges = (graph.out.get(id) ?? [])
+    .filter((edge) => CONTEXT_KINDS.includes(edge.kind) && graph.artifacts.has(edge.to))
+    .sort((a, b) => compareStrings(a.to, b.to) || compareStrings(a.kind, b.kind));
+  const seenContext = new Set<string>();
+  for (const edge of contextEdges) {
+    if (seenContext.has(edge.to)) continue;
+    seenContext.add(edge.to);
+    const hit = toHit(graph, edge.to, [{ id: edge.to, via: `${edge.kind}→`, reason: reasonFor(edge) }]);
+    if (hit !== null) report.context.push(hit);
+  }
+
+  const visited = new Set<string>([id]);
+  let cursor = graph.artifacts.get(id)?.meta.parent;
+  while (cursor !== undefined && !visited.has(cursor) && graph.artifacts.has(cursor)) {
+    visited.add(cursor);
+    report.ancestors.push(cursor);
+    cursor = graph.artifacts.get(cursor)?.meta.parent;
+  }
+  return report;
+}
+
+function toHit(graph: Graph, id: string, path: ImpactStep[]): ImpactHit | null {
+  const artifact = graph.artifacts.get(id);
+  if (artifact === undefined) return null;
+  return { id, type: artifact.meta.type, title: artifact.meta.title, path };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./artifact.ts";
+export * from "./carrier.ts";
+export * from "./config.ts";
+export * from "./context.ts";
+export * from "./diagnostics.ts";
+export * from "./export.ts";
+export * from "./graph.ts";
+export * from "./hash.ts";
+export * from "./impact.ts";
+export * from "./registries.ts";
+export * from "./types.ts";
+export * from "./validate.ts";
+export * from "./yaml.ts";
+export { compareStrings } from "./report.ts";

package/src/registries.ts

@@ -0,0 +1,171 @@
+/**
+ * The repository registries (Core §4, §7; VSA §3): owners, audiences, the
+ * four release dimensions, and the shared-resource inventory. The file is
+ * `registries.yaml` in the shape of examples/scheduling/registries.yaml.
+ * A missing or empty file is empty registries, which the validator reads as
+ * "not declared" rather than "nothing allowed".
+ */
+import type { Diagnostic } from "./diagnostics.ts";
+import { compareStrings, isRecord, makeDiagnostic } from "./report.ts";
+import { EMPTY_REGISTRIES, ID_PATTERN, type Registries, type Resource } from "./types.ts";
+import { parseYamlDetailed } from "./yaml.ts";
+
+const LIST_KEYS = ["owners", "audiences", "releases", "roles", "editions", "flags"] as const;
+const KNOWN_KEYS = new Set<string>([...LIST_KEYS, "resources"]);
+
+/**
+ * Core §4 and §7, VSA §3: read registries.yaml. Shape problems are CFG002
+ * (origin "profile"); a YAML rejection is CFG002, also with origin "profile" (origin "syntax" is Markset's alone). Every
+ * list comes back sorted. `null` text means the file is absent.
+ */
+export function readRegistries(
+  text: string | null,
+  path: string,
+): { registries: Registries; diagnostics: Diagnostic[] } {
+  const diagnostics: Diagnostic[] = [];
+  const registries: Registries = { ...EMPTY_REGISTRIES, resources: [] };
+  if (text === null || text.trim() === "") return { registries, diagnostics };
+
+  const parsed = parseYamlDetailed(text);
+  if (parsed.error) {
+    diagnostics.push(
+      makeDiagnostic({
+        code: "CFG002",
+        origin: "profile",
+        artifact: null,
+        path,
+        location: { line: parsed.error.line },
+        message: `registries.yaml does not parse: ${parsed.error.message}`,
+        remediation: "Write the registries as a block mapping of string lists and a resources list.",
+      }),
+    );
+    return { registries, diagnostics };
+  }
+  const root = parsed.value;
+  const report = (field: string, message: string, remediation: string) => {
+    const line = parsed.lines.get(field);
+    diagnostics.push(
+      makeDiagnostic({
+        code: "CFG002",
+        origin: "profile",
+        artifact: null,
+        path,
+        ...(line !== undefined ? { location: { line } } : {}),
+        field,
+        message,
+        remediation,
+      }),
+    );
+  };
+
+  for (const key of Object.keys(root).sort(compareStrings)) {
+    if (!KNOWN_KEYS.has(key)) {
+      report(`/${key}`, `Unknown registry \`${key}\`.`, `Remove it; the registries are ${[...KNOWN_KEYS].join(", ")}.`);
+    }
+  }
+  for (const key of LIST_KEYS) {
+    const value = root[key];
+    if (value === undefined || value === null) continue;
+    const list = stringList(value, `/${key}`, report);
+    if (list !== null) registries[key] = list;
+  }
+  const resources = root.resources;
+  if (resources !== undefined && resources !== null) {
+    if (!Array.isArray(resources)) {
+      report(
+        "/resources",
+        "`resources` must be a list of resource records.",
+        "Write each resource as `- id:`, `path:`, `owner:`, `consumers:`.",
+      );
+    } else {
+      const seen = new Set<string>();
+      resources.forEach((entry, i) => {
+        const resource = readResource(entry, `/resources/${i}`, report);
+        if (resource === null) return;
+        if (seen.has(resource.id)) {
+          report(`/resources/${i}/id`, `Resource ${resource.id} is declared twice.`, "Keep one record per resource.");
+          return;
+        }
+        seen.add(resource.id);
+        registries.resources.push(resource);
+      });
+      registries.resources.sort((a, b) => compareStrings(a.id, b.id));
+    }
+  }
+  return { registries, diagnostics };
+}
+
+type Report = (field: string, message: string, remediation: string) => void;
+
+function stringList(value: unknown, field: string, report: Report): string[] | null {
+  if (!Array.isArray(value)) {
+    report(
+      field,
+      `\`${field.slice(1)}\` must be a list of strings.`,
+      "Write it as a block or flow sequence of strings.",
+    );
+    return null;
+  }
+  const out: string[] = [];
+  let ok = true;
+  value.forEach((item, i) => {
+    if (typeof item !== "string" || item === "") {
+      report(
+        `${field}/${i}`,
+        `Entry ${i} of \`${field.slice(1)}\` is not a non-empty string.`,
+        "Quote the value if it reads as a number or boolean.",
+      );
+      ok = false;
+      return;
+    }
+    if (out.includes(item)) {
+      report(`${field}/${i}`, `\`${item}\` is listed twice under \`${field.slice(1)}\`.`, "Keep one entry per value.");
+      return;
+    }
+    out.push(item);
+  });
+  return ok ? out.sort(compareStrings) : null;
+}
+
+function readResource(value: unknown, field: string, report: Report): Resource | null {
+  if (!isRecord(value)) {
+    report(field, "A resource must be a mapping.", "Write it as `- id:`, `path:`, `owner:`, `consumers:`.");
+    return null;
+  }
+  let ok = true;
+  for (const key of Object.keys(value).sort(compareStrings)) {
+    if (!["id", "path", "owner", "consumers"].includes(key)) {
+      report(`${field}/${key}`, `Unknown resource key \`${key}\`.`, "A resource has id, path, owner and consumers.");
+      ok = false;
+    }
+  }
+  const { id, path, owner } = value;
+  if (typeof id !== "string" || !ID_PATTERN.test(id)) {
+    report(
+      `${field}/id`,
+      "A resource needs an `id` matching the artifact ID pattern.",
+      "Use an upper-case ID such as RES-ASSESSMENT-DATA.",
+    );
+    ok = false;
+  }
+  if (typeof path !== "string" || path === "") {
+    report(
+      `${field}/path`,
+      "A resource needs a repository-relative `path`.",
+      "Name the file that defines the resource.",
+    );
+    ok = false;
+  }
+  if (typeof owner !== "string" || owner === "") {
+    report(`${field}/owner`, "A resource needs an `owner`.", "Name the technical owner from the owner registry.");
+    ok = false;
+  }
+  let consumers: string[] = [];
+  if (value.consumers !== undefined && value.consumers !== null) {
+    const list = stringList(value.consumers, `${field}/consumers`, report);
+    if (list === null) ok = false;
+    else consumers = list;
+  }
+  if (!ok) return null;
+  return { id: id as string, path: path as string, owner: owner as string, consumers };
+}

package/src/report.ts

@@ -0,0 +1,84 @@
+/**
+ * Construction of diagnostics with one key order (ADR 0004), so two runs that
+ * report the same problem produce the same bytes. Optional members are left
+ * out rather than set to undefined, which is what keeps `location` honest:
+ * absent means unknown, never invented.
+ */
+import type { Diagnostic, Location, Origin, Severity } from "./diagnostics.ts";
+
+export interface DiagnosticFields {
+  code: string;
+  severity?: Severity;
+  origin: Origin;
+  artifact: string | null;
+  path: string | null;
+  location?: Location;
+  field?: string;
+  message: string;
+  remediation: string;
+}
+
+/** ADR 0004: one diagnostic, members in contract order, optional ones present only when known. */
+export function makeDiagnostic(fields: DiagnosticFields): Diagnostic {
+  const diagnostic: Diagnostic = {
+    code: fields.code,
+    severity: fields.severity ?? "error",
+    origin: fields.origin,
+    artifact: fields.artifact,
+    path: fields.path,
+    message: fields.message,
+    remediation: fields.remediation,
+  };
+  if (fields.location !== undefined) diagnostic.location = fields.location;
+  if (fields.field !== undefined) diagnostic.field = fields.field;
+  return orderKeys(diagnostic);
+}
+
+function orderKeys(d: Diagnostic): Diagnostic {
+  const ordered: Diagnostic = {
+    code: d.code,
+    severity: d.severity,
+    origin: d.origin,
+    artifact: d.artifact,
+    path: d.path,
+    ...(d.location !== undefined ? { location: d.location } : {}),
+    ...(d.field !== undefined ? { field: d.field } : {}),
+    message: d.message,
+    remediation: d.remediation,
+  };
+  return ordered;
+}
+
+/** A function from a frontmatter JSON pointer to its file line, when the key exists. */
+export type Locate = (pointer: string) => Location | undefined;
+
+export const NO_LOCATION: Locate = () => undefined;
+
+/** ADR 0004 helper: a plain mapping, not an array or null. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** ADR 0005: code-unit order, the one order everything iterated is sorted by. */
+export function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** ADR 0004 messages: a type with its indefinite article, "an intent", "a behavior", "a knowledge artifact". */
+export function aType(type: string): string {
+  const noun = type === "knowledge" ? "knowledge artifact" : type;
+  return `${/^[aeiou]/.test(noun) ? "an" : "a"} ${noun}`;
+}
+
+/** ADR 0004 messages: "an intent", or "a behavior, rule or scenario". */
+export function describeTypes(types: readonly string[]): string {
+  if (types.length === 1) return aType(types[0]);
+  const [first, ...rest] = types;
+  const last = rest.pop();
+  return `${[aType(first), ...rest].join(", ")} or ${last}`;
+}
+
+/** ADR 0004 messages: a sentence-initial capital. */
+export function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}