@intentset/core 0.10.0 → 0.13.0

package/src/artifact.ts

@@ -18,6 +18,7 @@
 import { closingFenceIndex } from "./carrier.ts";
 import type { Diagnostic, Location } from "./diagnostics.ts";
 import { sha256Hex } from "./hash.ts";
+import { contentHashOf } from "./content-hash.ts";
 import { type Locate, NO_LOCATION, aType, capitalize, compareStrings, isRecord, makeDiagnostic } from "./report.ts";
 import {
   ARTIFACT_TYPES,
@@ -28,6 +29,9 @@ import {
   BASELINE_UNKNOWN,
   CLAIM_KINDS,
   type Claim,
+  DELIVERIES,
+  DELIVERY_TYPES,
+  type Delivery,
   type DocumentInput,
   ID_PATTERN,
   LINK_KINDS,
@@ -79,6 +83,7 @@ const OPTIONAL_COMMON = [
   "revision",
   "reviewedAt",
   "reviewedBy",
+  "delivery",
   "extensions",
   "tips",
   "slice",
@@ -206,6 +211,7 @@ export function readDocument(input: DocumentInput): ReadDocument {
       meta,
       path: input.path,
       sourceHash: sha256Hex(input.source),
+      contentHash: contentHashOf(root, bodyOf(input.source)),
       body: bodyOf(input.source),
       headings: input.headings,
       foreign,
@@ -383,6 +389,24 @@ function readMeta(s: Record<string, unknown>, problem: Problem): ArtifactMeta |
     if (typeof s.reviewedBy === "string") reviewedBy = s.reviewedBy;
     else problem(`${base}/reviewedBy`, "`reviewedBy` must be a string.", "Name the reviewer or review record.");
   }
+  let delivery: Delivery | undefined;
+  if (Object.hasOwn(s, "delivery") && s.delivery !== null) {
+    if (type !== null && !(DELIVERY_TYPES as readonly string[]).includes(type)) {
+      problem(
+        `${base}/delivery`,
+        `\`delivery\` is written on ${aType(type)}; only ${DELIVERY_TYPES.slice(0, -1).join(", ")} and ${DELIVERY_TYPES[DELIVERY_TYPES.length - 1]} records say whether their work is built.`,
+        "Remove `delivery`; it states whether the code a record describes exists (Core §7).",
+      );
+    } else if (typeof s.delivery === "string" && (DELIVERIES as readonly string[]).includes(s.delivery)) {
+      delivery = s.delivery as Delivery;
+    } else {
+      problem(
+        `${base}/delivery`,
+        "`delivery` must be planned or built.",
+        "Write `delivery: built` when the code the record describes exists, `delivery: planned` when it does not yet, or leave it out (Core §7).",
+      );
+    }
+  }
   let extensions: Record<string, unknown> | undefined;
   if (Object.hasOwn(s, "extensions") && s.extensions !== null) {
     if (!isRecord(s.extensions)) {
@@ -462,6 +486,7 @@ function readMeta(s: Record<string, unknown>, problem: Problem): ArtifactMeta |
   if (revision !== undefined) meta.revision = revision;
   if (reviewedAt !== undefined) meta.reviewedAt = reviewedAt;
   if (reviewedBy !== undefined) meta.reviewedBy = reviewedBy;
+  if (delivery !== undefined) meta.delivery = delivery;
   if (extensions !== undefined) meta.extensions = extensions;
   if (tips !== undefined) meta.tips = tips;
   if (slice !== undefined) meta.slice = slice;
@@ -472,6 +497,8 @@ function readMeta(s: Record<string, unknown>, problem: Problem): ArtifactMeta |
 
 interface ListOptions {
   minItems?: number;
+  /** What to do about a list shorter than `minItems`, when "add a value" is not enough of an answer. */
+  minItemsRemediation?: string;
   pattern?: RegExp;
   /** Code for a repeated entry; CORE001 unless the list is a relationship. */
   duplicateCode?: string;
@@ -529,7 +556,7 @@ function stringList(
       problem(
         field,
         `\`${name}\` must list at least ${options.minItems} entr${options.minItems === 1 ? "y" : "ies"}.`,
-        `Add at least one value to ${name}.`,
+        options.minItemsRemediation ?? `Add at least one value to ${name}.`,
       );
     }
     return null;
@@ -601,7 +628,15 @@ function readAvailability(value: unknown, field: string, problem: Problem): Avai
       ok = false;
       continue;
     }
-    const list = stringList(value[key], `${field}/${key}`, key, problem, { minItems: key === "flags" ? 0 : 1 });
+    // Availability intersects on every dimension (Core §7), so an empty one would apply the artifact nowhere; a
+    // product with no roles or editions of its own still names one of each, and registers it.
+    const list = stringList(value[key], `${field}/${key}`, key, problem, {
+      minItems: key === "flags" ? 0 : 1,
+      minItemsRemediation:
+        key === "products"
+          ? "Name the product the artifact belongs to."
+          : `List at least one of the ${key} the artifact applies to, from the registries; a product with no ${key} of its own still names one (such as ${key === "roles" ? "user" : key === "editions" ? "standard" : "v1"}) and registers it.`,
+    });
     if (list === null) ok = false;
     else out[key] = list;
   }

package/src/content-hash.ts

@@ -0,0 +1,56 @@
+/**
+ * A record's content hash (publication §3, ADR 0018): what a review pins
+ * when it pins `content-v1`. It covers what the record promises, and leaves
+ * out where the record stands in its lifecycle and who reviewed it, so that
+ * approving, implementing or marking delivery does not send every guide that
+ * explains the record back to review.
+ *
+ * The hash is SHA-256 over the canonical JSON (ADR 0005) of
+ * `{ body, frontmatter, ending }`:
+ *
+ * - `frontmatter` is the whole parsed frontmatter, `markset` and unknown
+ *   top-level keys included, without `status`, `delivery`, `reviewedBy` and
+ *   `reviewedAt` under `intentset`, and without the `intentset.org/review`
+ *   extension (and `extensions` itself when nothing else is in it);
+ * - `body` is everything after the frontmatter, as written;
+ * - `ending` is the status when it is `deprecated` or `retired`, and absent
+ *   otherwise, so a record that is going away still moves the hash: what a
+ *   guide explains is ending, and its reader needs to know.
+ *
+ * Because it is taken over parsed values, a change of key order, quoting or
+ * indentation in the frontmatter does not move it.
+ */
+import { canonicalJson, sha256Hex } from "./hash.ts";
+
+/** The `intentset` fields a content hash leaves out: lifecycle and review, not promise. */
+export const CONTENT_HASH_OMITS = ["status", "delivery", "reviewedBy", "reviewedAt"] as const;
+/** The extension a content hash leaves out: the review's own pins. */
+export const CONTENT_HASH_OMITS_EXTENSION = "intentset.org/review";
+/** The statuses a content hash names, because a record in them is going away. */
+export const ENDING_STATUSES = ["deprecated", "retired"] as const;
+
+/** The content hash of a record from its parsed frontmatter and its body (publication §3, ADR 0018). */
+export function contentHashOf(frontmatter: Record<string, unknown>, body: string): string {
+  const copy: Record<string, unknown> = { ...frontmatter };
+  const section = frontmatter.intentset;
+  let ending: string | undefined;
+  if (isRecord(section)) {
+    const intentset: Record<string, unknown> = { ...section };
+    if (typeof section.status === "string" && (ENDING_STATUSES as readonly string[]).includes(section.status)) {
+      ending = section.status;
+    }
+    for (const key of CONTENT_HASH_OMITS) delete intentset[key];
+    if (isRecord(section.extensions)) {
+      const extensions: Record<string, unknown> = { ...section.extensions };
+      delete extensions[CONTENT_HASH_OMITS_EXTENSION];
+      if (Object.keys(extensions).length === 0) delete intentset.extensions;
+      else intentset.extensions = extensions;
+    }
+    copy.intentset = intentset;
+  }
+  return sha256Hex(canonicalJson({ body, frontmatter: copy, ending }));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/delivery.ts

@@ -0,0 +1,11 @@
+/**
+ * Core §7, ADR 0017: a record's effective delivery. Its `delivery` when it states one; otherwise `built` when its
+ * status claims an implementation (`implemented`, `released`, `deprecated`); otherwise null, not stated. `approved`
+ * claims nothing about the code, so an approved record without the field is not stated.
+ */
+import { BUILT_STATUSES, type Delivery, type Status } from "./types.ts";
+
+export function deliveryOf(meta: { delivery?: Delivery | null; status: Status }): Delivery | null {
+  if (meta.delivery !== undefined && meta.delivery !== null) return meta.delivery;
+  return (BUILT_STATUSES as readonly string[]).includes(meta.status) ? "built" : null;
+}

package/src/export.ts

@@ -20,6 +20,7 @@ import {
   type ExportEnvelope,
   type ExportImpactHit,
   type ExportReports,
+  type Graph,
   LINK_KINDS,
   type Level,
   type LinkKind,
@@ -60,7 +61,7 @@ export interface ExportMeta {
 /** spec/export.md: the `intentset/export/0.3` envelope over a validation result. */
 export function exportGraph(result: ValidationResult, registries: Registries, meta: ExportMeta): ExportEnvelope {
   const { graph } = result;
-  const withheld = withheldIds(result, meta.includeRestricted === true);
+  const withheld = withheldIds(graph, meta.includeRestricted === true);
   const ids = [...graph.artifacts.keys()].filter((id) => !withheld.ids.has(id)).sort(compareStrings);
   const errors = result.diagnostics.filter((d) => d.severity === "error").length;
   const warnings = result.diagnostics.length - errors;
@@ -95,11 +96,24 @@ export function exportGraph(result: ValidationResult, registries: Registries, me
       diagnostics: result.diagnostics.length - diagnostics.length,
     },
     registries: exportRegistries(registries, withheld.ids),
-    artifacts: ids.map((id) => exportArtifact(result, id, meta.includeBodies === true, withheld.ids)),
+    artifacts: ids.map((id) => exportArtifact(graph, id, meta.includeBodies === true, withheld.ids)),
     reports: withholdReports(meta.reports ?? {}, withheld),
   };
 }
 
+/**
+ * The artifacts an export of `graph` would carry, without bodies, and how many it would withhold: the projection
+ * `select` reads a graph through (spec/list.md §2), so a list from the tree and a list from its export agree.
+ */
+export function projectArtifacts(
+  graph: Graph,
+  includeRestricted: boolean,
+): { artifacts: ExportArtifact[]; withheld: number } {
+  const withheld = withheldIds(graph, includeRestricted);
+  const ids = [...graph.artifacts.keys()].filter((id) => !withheld.ids.has(id)).sort(compareStrings);
+  return { artifacts: ids.map((id) => exportArtifact(graph, id, false, withheld.ids)), withheld: withheld.ids.size };
+}
+
 interface Withheld {
   ids: Set<string>;
   /** Source paths of the withheld artifacts, for diagnostics that name a file but no artifact. */
@@ -110,11 +124,11 @@ interface Withheld {
 
 const WITHHELD_VISIBILITIES: readonly Visibility[] = ["restricted"];
 
-function withheldIds(result: ValidationResult, includeRestricted: boolean): Withheld {
+function withheldIds(graph: Graph, includeRestricted: boolean): Withheld {
   const ids = new Set<string>();
   const paths = new Set<string>();
   if (!includeRestricted) {
-    for (const [id, artifact] of result.graph.artifacts) {
+    for (const [id, artifact] of graph.artifacts) {
       if (WITHHELD_VISIBILITIES.includes(artifact.meta.visibility)) {
         ids.add(id);
         paths.add(artifact.path);
@@ -158,13 +172,7 @@ function withholdDiagnostics(diagnostics: readonly Diagnostic[], withheld: Withh
   return out;
 }
 
-function exportArtifact(
-  result: ValidationResult,
-  id: string,
-  includeBody: boolean,
-  withheld: ReadonlySet<string>,
-): ExportArtifact {
-  const { graph } = result;
+function exportArtifact(graph: Graph, id: string, includeBody: boolean, withheld: ReadonlySet<string>): ExportArtifact {
   const artifact = graph.artifacts.get(id);
   if (artifact === undefined) throw new Error(`graph has no artifact ${id}`);
   const { meta } = artifact;
@@ -211,6 +219,7 @@ function exportArtifact(
     type: meta.type,
     title: meta.title,
     status: meta.status,
+    delivery: meta.delivery ?? null,
     owner: meta.owner,
     visibility: meta.visibility,
     audiences: [...meta.audiences].sort(compareStrings),

package/src/glob.ts

@@ -0,0 +1,60 @@
+/**
+ * The pattern language of `.intentset/config.yaml` scope and ignore lists,
+ * which is VSA §3's: repository-relative POSIX paths made of literal segments,
+ * `*` within one segment, and `**` across zero or more segments. Nothing else
+ * is special: no `?`, no classes, no braces, no negation, so there is no
+ * precedence to explain. A pattern and a path match segment by segment, and
+ * `*` never crosses a `/`.
+ *
+ * Core holds it because what a slice claims is part of the model's own
+ * definitions (Core §10, ADR 0016): `claimingSlices` and `select` match claims
+ * with it, and the CLI re-exports it. The architecture package keeps its own
+ * copy for claims, as it did before the move.
+ */
+
+/** VSA §3: true when the repository-relative POSIX `path` matches `pattern`. */
+export function matchGlob(pattern: string, path: string): boolean {
+  const p = normalize(pattern).split("/");
+  const s = path.split("/");
+  // Memo of (pattern index, path index) pairs already known not to match, so
+  // several `**` in one pattern stay polynomial rather than exponential.
+  const failed = new Set<number>();
+  const width = s.length + 1;
+  const match = (i: number, j: number): boolean => {
+    if (failed.has(i * width + j)) return false;
+    let ok: boolean;
+    if (i === p.length) ok = j === s.length;
+    else if (p[i] === "**") ok = match(i + 1, j) || (j < s.length && match(i, j + 1));
+    else ok = j < s.length && matchSegment(p[i], s[j]) && match(i + 1, j + 1);
+    if (!ok) failed.add(i * width + j);
+    return ok;
+  };
+  return match(0, 0);
+}
+
+/** True when any of `patterns` matches `path`. */
+export function matchAny(patterns: readonly string[], path: string): boolean {
+  return patterns.some((pattern) => matchGlob(pattern, path));
+}
+
+/** A leading `./` names the same path; repeated `/` separate nothing. */
+function normalize(pattern: string): string {
+  return pattern.replace(/^(?:\.\/)+/, "").replace(/\/{2,}/g, "/");
+}
+
+const SEGMENTS = new Map<string, RegExp>();
+
+/** One segment: literal text, with each `*` standing for any run of characters other than `/`. */
+function matchSegment(pattern: string, name: string): boolean {
+  if (!pattern.includes("*")) return pattern === name;
+  let regex = SEGMENTS.get(pattern);
+  if (regex === undefined) {
+    const body = pattern
+      .split("*")
+      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+      .join("[^/]*");
+    regex = new RegExp(`^${body}$`);
+    SEGMENTS.set(pattern, regex);
+  }
+  return regex.test(name);
+}

package/src/index.ts

@@ -2,13 +2,18 @@ export * from "./artifact.ts";
 export * from "./carrier.ts";
 export * from "./config.ts";
 export * from "./context.ts";
+export * from "./delivery.ts";
 export * from "./diagnostics.ts";
 export * from "./export.ts";
+export * from "./glob.ts";
 export * from "./graph.ts";
+export * from "./content-hash.ts";
 export * from "./hash.ts";
 export * from "./impact.ts";
 export * from "./read-export.ts";
 export * from "./registries.ts";
+export * from "./select.ts";
+export * from "./slices.ts";
 export * from "./types.ts";
 export * from "./validate.ts";
 export * from "./yaml.ts";

package/src/read-export.ts

@@ -23,6 +23,8 @@ import {
   EVIDENCE_BINDINGS,
   EXPORT_EVIDENCE_STATUSES,
   EXPORT_REPORTS,
+  DELIVERIES,
+  DELIVERY_TYPES,
   type ExportEnvelope,
   type ExportReportName,
   ID_PATTERN,
@@ -414,6 +416,7 @@ class Shape {
         "type",
         "title",
         "status",
+        "delivery",
         "owner",
         "visibility",
         "audiences",
@@ -439,6 +442,12 @@ class Shape {
     this.oneOf(a.type, `${at}/type`, ARTIFACT_TYPES);
     this.string(a.title, `${at}/title`);
     this.oneOf(a.status, `${at}/status`, STATUSES);
+    this.nullable(a.delivery, `${at}/delivery`, (d, p) => {
+      this.oneOf(d, p, DELIVERIES);
+      if (typeof a.type === "string" && !(DELIVERY_TYPES as readonly string[]).includes(a.type)) {
+        this.fail(p, `Expected null: ${a.type} records do not carry delivery.`);
+      }
+    });
     this.string(a.owner, `${at}/owner`);
     this.oneOf(a.visibility, `${at}/visibility`, VISIBILITIES);
     this.strings(a.audiences, `${at}/audiences`, { minItems: 1 });