@norskvideo/ctl-dev-kit 0.2.111 → 0.2.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.111",
+  "version": "0.2.112",
   "type": "module",
   "repository": {
     "type": "git",

package/testing/INVARIANTS.template.md

@@ -47,3 +47,11 @@ runtime-only invariant the emitted graph can't show (e.g. a timing guarantee)
 still gets a table row — declare its ID in the guard's `untestableIds` option;
 the guard rejects unknown entries and flags the marker as stale once a test
 does cite the ID.
+
+An existing product whose doc lists invariants as bullets
+(`- **P01** — rule text`) and proves them with a table of rules rather than
+cited IDs can keep that shape: pass `format: "bold-bullet"` and
+`coveredIds: RULES.map((r) => r.id)` (`testDirs` is then unneeded). Only a
+bullet that starts a line defines an ID, so prose like "see rule **P01**"
+never counts; every bullet needs a covering rule or an `untestableIds` entry,
+and a rule ID the doc lacks fails the guard. New products should use the table.

package/testing/invariants.ts

@@ -29,6 +29,23 @@ export function parseInvariants(markdown: string): Invariant[] {
   return invariants;
 }
 
+// The older doc shape some products keep (commentary, playout): one bullet per
+// invariant, `- **P01** — rule text`, with the IDs proven by a rule sweep rather
+// than cited in test text. Anchored to the line start so a prose mention like
+// "rule **IN02** (below)" never counts as a definition.
+const BOLD_BULLET = /^\s*[-*]\s+\*\*([A-Z]+[0-9]+[a-z]?)\*\*\s*(?:[—–-]\s*)?(.*)$/;
+
+export function parseBoldBulletInvariants(markdown: string): Invariant[] {
+  const invariants: Invariant[] = [];
+  markdown.split("\n").forEach((text, i) => {
+    const bullet = text.match(BOLD_BULLET);
+    if (bullet?.[1] !== undefined && bullet[2] !== undefined) {
+      invariants.push({ id: bullet[1], rule: bullet[2], line: i + 1 });
+    }
+  });
+  return invariants;
+}
+
 export interface ParityReport {
   ok: boolean;
   problems: string[];
@@ -38,20 +55,35 @@ export interface ParityOptions {
   // Runtime-only invariants no emitted-graph test can show (e.g. a timing
   // guarantee). Still parity-checked: each must exist in the table, and a
   // citing test appearing later flags the marker as stale.
-  untestableIds?: string[];
+  untestableIds?: Iterable<string>;
+  format?: "table" | "bold-bullet";
+  // The IDs a rule sweep covers, when coverage is data rather than test text.
+  // Given, it replaces the scan of test sources entirely.
+  coveredIds?: Iterable<string>;
 }
 
+const EXPECTED_SHAPE = {
+  table: "rows must look like `| INV-AREA-001 | rule text | guarded-by |`",
+  "bold-bullet": "bullets must look like `- **AREA01** — rule text`",
+};
+
 export function invariantParity(
   markdown: string,
   testSources: Record<string, string>,
   opts: ParityOptions = {},
 ): ParityReport {
   const problems: string[] = [];
-  const invariants = parseInvariants(markdown);
+  const format = opts.format ?? "table";
+  const invariants = format === "bold-bullet" ? parseBoldBulletInvariants(markdown) : parseInvariants(markdown);
   const untestable = new Set(opts.untestableIds ?? []);
+  const covered = opts.coveredIds === undefined ? undefined : new Set(opts.coveredIds);
 
+  if (format === "bold-bullet" && covered === undefined) {
+    // Bullet IDs are too short to scan test text for safely, so coverage has to be given.
+    return { ok: false, problems: ["bold-bullet format needs coveredIds — pass the IDs your rule sweep covers."] };
+  }
   if (invariants.length === 0) {
-    problems.push("no invariants parsed — rows must look like `| INV-AREA-001 | rule text | guarded-by |`.");
+    problems.push(`no invariants parsed — ${EXPECTED_SHAPE[format]}.`);
   }
 
   const seen = new Set<string>();
@@ -60,25 +92,35 @@ export function invariantParity(
     seen.add(inv.id);
   }
 
-  const referenced = new Set<string>();
-  for (const [file, source] of Object.entries(testSources)) {
-    for (const token of source.match(ID_TOKEN) ?? []) {
-      referenced.add(token);
-      if (invariants.length > 0 && !seen.has(token)) {
-        problems.push(`${file} references ${token}, which is not in the invariants table — add the row or fix the ID.`);
+  const referenced = covered ?? new Set<string>();
+  if (covered !== undefined) {
+    for (const id of covered) {
+      if (invariants.length > 0 && !seen.has(id)) {
+        problems.push(`covered ID ${id} is not in the invariants doc — add the entry or fix the ID.`);
+      }
+    }
+  } else {
+    for (const [file, source] of Object.entries(testSources)) {
+      for (const token of source.match(ID_TOKEN) ?? []) {
+        referenced.add(token);
+        if (invariants.length > 0 && !seen.has(token)) {
+          problems.push(
+            `${file} references ${token}, which is not in the invariants table — add the row or fix the ID.`,
+          );
+        }
       }
     }
   }
 
   for (const inv of invariants) {
     if (referenced.has(inv.id) && untestable.has(inv.id)) {
-      problems.push(
-        `invariant ${inv.id} is declared untestable but a test cites it — remove the stale untestableIds entry.`,
-      );
+      const why = covered ? "is in coveredIds" : "a test cites it";
+      problems.push(`invariant ${inv.id} is declared untestable but ${why} — remove the stale untestableIds entry.`);
     }
     if (!referenced.has(inv.id) && !untestable.has(inv.id)) {
+      const fix = covered ? "add a rule for it (coveredIds)" : "cite its ID in the test that guards it,";
       problems.push(
-        `invariant ${inv.id} (${inv.rule}) has no referencing test — cite its ID in the test that guards it, or declare it in untestableIds.`,
+        `invariant ${inv.id} (${inv.rule}) has no referencing test — ${fix} or declare it in untestableIds.`,
       );
     }
   }
@@ -105,13 +147,16 @@ function collectTestFiles(dir: string, out: string[]): void {
   }
 }
 
+// testDirs is only read when coverage comes from test text (no coveredIds).
 export function invariantParityFromDisk(
-  opts: { invariantsPath: string; testDirs: string[] } & ParityOptions,
+  opts: { invariantsPath: string; testDirs?: string[] } & ParityOptions,
 ): ParityReport {
   const markdown = readFileSync(opts.invariantsPath, "utf8");
-  const files: string[] = [];
-  for (const dir of opts.testDirs) collectTestFiles(dir, files);
   const sources: Record<string, string> = {};
-  for (const file of files) sources[file] = readFileSync(file, "utf8");
-  return invariantParity(markdown, sources, { untestableIds: opts.untestableIds });
+  if (opts.coveredIds === undefined) {
+    const files: string[] = [];
+    for (const dir of opts.testDirs ?? []) collectTestFiles(dir, files);
+    for (const file of files) sources[file] = readFileSync(file, "utf8");
+  }
+  return invariantParity(markdown, sources, opts);
 }