@intentset/core 0.1.0 → 0.2.0

package/src/export.ts

@@ -1,8 +1,15 @@
 /**
- * The export envelope (Core §12; the integration contract; spec/export.schema.json).
+ * The export envelope (spec/export.md; spec/export.schema.json; Core §12).
  * Artifacts are sorted by ID and every list inside is sorted, so the same
  * validation result with the same `generatedAt` is the same bytes. Bodies
  * are included only when asked for.
+ *
+ * Restricted artifacts are withheld unless asked for, as they are from agent
+ * context: absent from `artifacts`, `products` and every report, their IDs
+ * removed from the links of what is exported and redacted from diagnostic
+ * text, and every omission counted where it happened, so a short export never
+ * reads as a complete one. The graph hash still covers them: it names the
+ * snapshot, which evidence is bound to, not the projection.
  */
 import { graphHash, sortKeysDeep } from "./hash.ts";
 import { compareStrings } from "./report.ts";
@@ -11,6 +18,8 @@ import {
   EXPORT_CONTRACT,
   type ExportArtifact,
   type ExportEnvelope,
+  type ExportImpactHit,
+  type ExportReports,
   LINK_KINDS,
   type Level,
   type LinkKind,
@@ -18,7 +27,9 @@ import {
   SPEC_VERSION,
   type SliceMeta,
   type ValidationResult,
+  type Visibility,
 } from "./types.ts";
+import type { Diagnostic } from "./diagnostics.ts";
 
 /** What the caller knows and the validation result does not: identity, commit, scope, level, release. */
 export interface ExportMeta {
@@ -27,6 +38,8 @@ export interface ExportMeta {
   /** The commit the export describes, or null with `commitUnavailable` saying why (a default reason is written when none is given). */
   commit: string | null;
   commitUnavailable?: string;
+  /** True when tracked files differed from the commit. Ignored when the commit is null. */
+  uncommitted?: boolean;
   /** The scope globs validated; defaults to every Markdown file. */
   scope?: string[];
   /** The level the validation ran at; defaults to L1. */
@@ -35,17 +48,29 @@ export interface ExportMeta {
   /** ISO 8601; defaults to now. Fix it to make two exports comparable byte for byte. */
   generatedAt?: string;
   includeBodies?: boolean;
+  /** Export restricted artifacts too. Default false: they are withheld and counted (spec/export.md §3). */
+  includeRestricted?: boolean;
+  /**
+   * Report sections, each computed over the whole graph by the package that
+   * owns it. The export withholds inside them exactly as it does for artifacts.
+   */
+  reports?: ExportReports;
 }
 
-/** Core §12 and the integration contract: the `intentset/export/0.1` envelope over a validation result. */
+/** spec/export.md: the `intentset/export/0.2` envelope over a validation result. */
 export function exportGraph(result: ValidationResult, registries: Registries, meta: ExportMeta): ExportEnvelope {
   const { graph } = result;
-  const ids = [...graph.artifacts.keys()].sort(compareStrings);
+  const withheld = withheldIds(result, 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;
-  const source: ExportEnvelope["source"] = { commit: meta.commit };
-  if (meta.commit === null)
+  const diagnostics = withholdDiagnostics(result.diagnostics, withheld);
+  const source: ExportEnvelope["source"] = { commit: meta.commit, uncommitted: false };
+  if (meta.commit === null) {
     source.commitUnavailable = meta.commitUnavailable ?? "No commit was supplied to the export.";
+  } else {
+    source.uncommitted = meta.uncommitted === true;
+  }
 
   return {
     contract: EXPORT_CONTRACT,
@@ -62,24 +87,92 @@ export function exportGraph(result: ValidationResult, registries: Registries, me
       status: result.ok ? "pass" : "fail",
       errors,
       warnings,
-      diagnostics: [...result.diagnostics],
+      diagnostics,
+    },
+    withholding: {
+      visibilities: meta.includeRestricted === true ? [] : ["restricted"],
+      artifacts: withheld.ids.size,
+      diagnostics: result.diagnostics.length - diagnostics.length,
     },
-    registries: exportRegistries(registries),
-    artifacts: ids.map((id) => exportArtifact(result, id, meta.includeBodies === true)),
+    registries: exportRegistries(registries, withheld.ids),
+    artifacts: ids.map((id) => exportArtifact(result, id, meta.includeBodies === true, withheld.ids)),
+    reports: withholdReports(meta.reports ?? {}, withheld.ids),
   };
 }
 
-function exportArtifact(result: ValidationResult, id: string, includeBody: boolean): ExportArtifact {
+interface Withheld {
+  ids: Set<string>;
+  /** Source paths of the withheld artifacts, for diagnostics that name a file but no artifact. */
+  paths: Set<string>;
+  /** Matches any withheld ID as a whole token, or null when nothing is withheld. */
+  pattern: RegExp | null;
+}
+
+const WITHHELD_VISIBILITIES: readonly Visibility[] = ["restricted"];
+
+function withheldIds(result: ValidationResult, includeRestricted: boolean): Withheld {
+  const ids = new Set<string>();
+  const paths = new Set<string>();
+  if (!includeRestricted) {
+    for (const [id, artifact] of result.graph.artifacts) {
+      if (WITHHELD_VISIBILITIES.includes(artifact.meta.visibility)) {
+        ids.add(id);
+        paths.add(artifact.path);
+      }
+    }
+  }
+  const alternatives = [...ids].sort((a, b) => b.length - a.length || compareStrings(a, b)).map(escapeRegExp);
+  const pattern =
+    alternatives.length === 0 ? null : new RegExp(`(?<![A-Z0-9-])(?:${alternatives.join("|")})(?![A-Z0-9-])`, "g");
+  return { ids, paths, pattern };
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Diagnostics about a withheld artifact are left out; any other that names one has the ID redacted. */
+function withholdDiagnostics(diagnostics: readonly Diagnostic[], withheld: Withheld): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  for (const d of diagnostics) {
+    if (d.artifact !== null && withheld.ids.has(d.artifact)) continue;
+    if (d.path !== null && withheld.paths.has(d.path)) continue;
+    const pattern = withheld.pattern;
+    if (pattern === null) {
+      out.push(d);
+      continue;
+    }
+    const redact = (text: string) => text.replace(pattern, "a withheld artifact");
+    out.push({ ...d, message: redact(d.message), remediation: redact(d.remediation) });
+  }
+  return out;
+}
+
+function exportArtifact(
+  result: ValidationResult,
+  id: string,
+  includeBody: boolean,
+  withheld: ReadonlySet<string>,
+): ExportArtifact {
   const { graph } = result;
   const artifact = graph.artifacts.get(id);
   if (artifact === undefined) throw new Error(`graph has no artifact ${id}`);
   const { meta } = artifact;
+  let withheldLinks = 0;
+  const keep = (list: Iterable<string>): string[] => {
+    const out: string[] = [];
+    for (const target of list) {
+      if (withheld.has(target)) withheldLinks++;
+      else out.push(target);
+    }
+    return out.sort(compareStrings);
+  };
 
   const links: ExportArtifact["links"] = {};
   for (const kind of LINK_KINDS) {
     if (kind === "parent") continue;
     const list = meta.links[kind];
-    if (list !== undefined) links[kind] = [...list].sort(compareStrings);
+    if (list !== undefined) links[kind] = keep(list);
   }
   const derived: ExportArtifact["derived"] = {};
   const byKind = new Map<LinkKind, string[]>();
@@ -90,7 +183,15 @@ function exportArtifact(result: ValidationResult, id: string, includeBody: boole
   }
   for (const kind of LINK_KINDS) {
     const list = byKind.get(kind);
-    if (list !== undefined) derived[kind] = [...new Set(list)].sort(compareStrings);
+    if (list !== undefined) {
+      const kept = keep(new Set(list));
+      if (kept.length > 0) derived[kind] = kept;
+    }
+  }
+  let parent = meta.parent ?? null;
+  if (parent !== null && withheld.has(parent)) {
+    parent = null;
+    withheldLinks++;
   }
 
   const exported: ExportArtifact = {
@@ -105,9 +206,10 @@ function exportArtifact(result: ValidationResult, id: string, includeBody: boole
     revision: meta.revision ?? null,
     path: artifact.path,
     sourceHash: artifact.sourceHash,
-    parent: meta.parent ?? null,
+    parent,
     links,
     derived,
+    withheldLinks,
     availability: meta.availability === undefined ? null : sortedAvailability(meta.availability),
     slice: meta.slice === undefined ? null : sortedSlice(meta.slice),
     verification:
@@ -124,6 +226,72 @@ function exportArtifact(result: ValidationResult, id: string, includeBody: boole
   return exported;
 }
 
+/**
+ * Each report as its producer computed it, less what is withheld: entries
+ * about a withheld artifact go, lists inside an entry lose withheld IDs, and
+ * an impact hit whose path passes through a withheld artifact goes too, each
+ * counted in the `withheld` beside it.
+ */
+function withholdReports(reports: ExportReports, withheld: ReadonlySet<string>): ExportReports {
+  const out: ExportReports = {};
+  const split = (list: readonly string[]): [string[], number] => {
+    const kept = list.filter((id) => !withheld.has(id));
+    return [kept, list.length - kept.length];
+  };
+  if (reports.evidence !== undefined) {
+    const evidence = reports.evidence;
+    out.evidence = {
+      ...evidence,
+      verifications: evidence.verifications.filter((v) => !withheld.has(v.id)),
+      claims: evidence.claims
+        .filter((claim) => !withheld.has(claim.id))
+        .map((claim) => {
+          const [verifications, removed] = split(claim.verifications);
+          return { ...claim, verifications, withheld: claim.withheld + removed };
+        }),
+    };
+  }
+  if (reports.knowledge !== undefined) {
+    out.knowledge = {
+      ...reports.knowledge,
+      artifacts: reports.knowledge.artifacts
+        .filter((entry) => !withheld.has(entry.id))
+        .map((entry) => {
+          const [sources, a] = split(entry.sources);
+          const [changed, b] = split(entry.changed);
+          const [missing, c] = split(entry.missing);
+          return { ...entry, sources, changed, missing, withheld: entry.withheld + a + b + c };
+        }),
+    };
+  }
+  if (reports.impact !== undefined) {
+    const visible = (hit: ExportImpactHit) => !withheld.has(hit.id) && hit.path.every((step) => !withheld.has(step.id));
+    out.impact = {
+      ...reports.impact,
+      starts: reports.impact.starts
+        .filter((entry) => !withheld.has(entry.start))
+        .map((entry) => {
+          const direct = entry.direct.filter(visible);
+          const candidates = entry.candidates.filter(visible);
+          const context = entry.context.filter(visible);
+          const [ancestors, removed] = split(entry.ancestors);
+          const hits = entry.direct.length + entry.candidates.length + entry.context.length;
+          const kept = direct.length + candidates.length + context.length;
+          return { ...entry, direct, candidates, context, ancestors, withheld: entry.withheld + hits - kept + removed };
+        }),
+    };
+  }
+  if (reports.ownership !== undefined) {
+    const files = reports.ownership.files.filter((file) => file.owner === null || !withheld.has(file.owner));
+    out.ownership = {
+      ...reports.ownership,
+      files,
+      withheld: reports.ownership.withheld + reports.ownership.files.length - files.length,
+    };
+  }
+  return out;
+}
+
 function sortedAvailability(availability: Availability): Availability {
   return {
     products: [...availability.products].sort(compareStrings),
@@ -153,7 +321,7 @@ function sortedSlice(slice: SliceMeta): SliceMeta {
   return out;
 }
 
-function exportRegistries(registries: Registries): Registries {
+function exportRegistries(registries: Registries, withheld: ReadonlySet<string>): Registries {
   return {
     owners: [...registries.owners].sort(compareStrings),
     audiences: [...registries.audiences].sort(compareStrings),
@@ -166,7 +334,7 @@ function exportRegistries(registries: Registries): Registries {
         id: resource.id,
         path: resource.path,
         owner: resource.owner,
-        consumers: [...resource.consumers].sort(compareStrings),
+        consumers: resource.consumers.filter((id) => !withheld.has(id)).sort(compareStrings),
       }))
       .sort((a, b) => compareStrings(a.id, b.id)),
   };

package/src/impact.ts

@@ -7,8 +7,22 @@
  * reason sentence per step. Reachability is recorded, never asserted as
  * proof that runtime behavior changed.
  */
+import { graphHash } from "./hash.ts";
 import { compareStrings } from "./report.ts";
-import type { Edge, Graph, ImpactHit, ImpactReport, ImpactStep, LinkKind } from "./types.ts";
+import type {
+  Edge,
+  ExportImpactHit,
+  Graph,
+  ImpactHit,
+  ImpactReport,
+  ImpactReportSection,
+  ImpactStep,
+  LinkKind,
+} from "./types.ts";
+
+/** Said beside every impact report, because reachability is easy to read as more than it is (Core §10). */
+export const IMPACT_NOTE =
+  "Reachability through authored links marks an artifact for review; it is not proof that runtime behavior changed (Core §10).";
 
 const PHRASES: Record<LinkKind, string> = {
   parent: "has {to} as its navigation parent",
@@ -88,3 +102,30 @@ function toHit(graph: Graph, id: string, path: ImpactStep[]): ImpactHit | null {
   if (artifact === undefined) return null;
   return { id, type: artifact.meta.type, title: artifact.meta.title, path };
 }
+
+/**
+ * `reports.impact` for the export (spec/export.md §4.3): the impact report from
+ * every artifact in the graph, or from `starts` when given, with each hit
+ * reduced to its ID and path. A consumer joins hits to `artifacts` by ID.
+ */
+export function impactReport(graph: Graph, starts?: Iterable<string>): ImpactReportSection {
+  const ids = [...new Set(starts ?? graph.artifacts.keys())]
+    .filter((id) => graph.artifacts.has(id))
+    .sort(compareStrings);
+  const hit = (h: ImpactHit): ExportImpactHit => ({ id: h.id, path: h.path });
+  return {
+    graphHash: graphHash(graph),
+    note: IMPACT_NOTE,
+    starts: ids.map((id) => {
+      const report = impact(graph, id);
+      return {
+        start: id,
+        direct: report.direct.map(hit),
+        candidates: report.candidates.map(hit),
+        context: report.context.map(hit),
+        ancestors: report.ancestors,
+        withheld: 0,
+      };
+    }),
+  };
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./export.ts";
 export * from "./graph.ts";
 export * from "./hash.ts";
 export * from "./impact.ts";
+export * from "./read-export.ts";
 export * from "./registries.ts";
 export * from "./types.ts";
 export * from "./validate.ts";