@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.32

package/dist/decision-records.js

@@ -6,11 +6,20 @@
  * these — `decisions new` produces a dry-run preview unless
  * `--write-draft` is passed.
  *
+ * The frontmatter is read by THE parser (`splitFrontmatter` +
+ * `parseFrontmatter`, @shrkcrft/core — round 15 follow-up, F6) in its `Text`
+ * scalar mode: a decision's `id` / `title` / `status` / `date` are strings by
+ * contract, read verbatim as the old line splitter read them (`id: 0001`
+ * stays `0001`, `title: Fix #12` keeps its `#12`). A record whose frontmatter
+ * cannot be read as declared is REJECTED through the round-12 channel
+ * ({@link loadTsDecisionsWithIssues} `rejected`) — never listed from a partial
+ * reading, never dropped silently.
+ *
  * Read-only operations: list, get, link (preview).
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { formatFrontmatterScalar, FrontmatterScalarMode, importModuleViaLoader, parseFrontmatter, RejectionCause, splitFrontmatter, } from '@shrkcrft/core';
 export const DECISION_RECORD_SCHEMA = 'sharkcraft.decision/v1';
 export var DecisionStatus;
 (function (DecisionStatus) {
@@ -20,20 +29,146 @@ export var DecisionStatus;
     DecisionStatus["Superseded"] = "superseded";
 })(DecisionStatus || (DecisionStatus = {}));
 const DECISION_DIRS = ['sharkcraft/decisions', 'docs/adr'];
-function frontmatterAndBody(text) {
-    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
-    if (!m)
-        return { fm: {}, body: text };
-    const fm = {};
-    for (const line of (m[1] ?? '').split('\n')) {
-        const idx = line.indexOf(':');
-        if (idx <= 0)
+/**
+ * A decision's frontmatter values are strings by contract — read verbatim
+ * (`Text` scalars), exactly as {@link previewDecisionDraft} writes them. Only
+ * the four keys a record reads are parsed (`keys`): any other key — MADR's
+ * `decision makers:`, a `summary:` wrapped onto an indented line, a map nested
+ * two levels — is skipped unparsed. The old splitter never read those lines
+ * either, and YAML the parser does not speak under a key nobody reads must not
+ * cost the record (the Markdown knowledge loader skips a key it drops the same
+ * way). No key is read as a list (`listKeys: []`, round 15 closing A1): an
+ * inline `title: [WIP]` is the title `[WIP]`, verbatim, as the old splitter
+ * read it — it used to REJECT the record as "a list".
+ */
+const DECISION_FRONTMATTER = Object.freeze({
+    scalars: FrontmatterScalarMode.Text,
+    keys: Object.freeze(['id', 'title', 'status', 'date']),
+    listKeys: Object.freeze([]),
+});
+function shapeOf(value) {
+    if (!Array.isArray(value))
+        return 'a map';
+    return value.some((v) => v !== null && typeof v === 'object') ? 'a list of maps' : 'a list';
+}
+/**
+ * Read one Markdown decision record through THE frontmatter parser. Frontmatter
+ * the parser refuses in its top-level structure (a stray line naming no key)
+ * or under a key the record reads (`title:` wrapped onto an indented line), or
+ * an `id` / `title` / `status` / `date` that is not a single value (a block
+ * list under `title:`; an inline `title: [WIP]` is text) REJECTS the record, every reason named: the
+ * old line splitter skipped such a line silently and let an indented `  id:`
+ * under any block overwrite the record's own id. A key the record does not
+ * read is never parsed ({@link DECISION_FRONTMATTER}).
+ */
+function readMarkdownDecision(full, fileName) {
+    const split = splitFrontmatter(readFileSync(full, 'utf8'));
+    const problems = [];
+    // A decision record opening with `---` and never closing it is broken
+    // frontmatter, not a thematic break: its `id:` would silently become the
+    // file name (the old splitter did exactly that).
+    if (split.unterminated)
+        problems.push('frontmatter: an opening --- line has no closing --- line');
+    let fields = {};
+    if (split.frontmatter !== undefined) {
+        const parsed = parseFrontmatter(split.frontmatter, { ...DECISION_FRONTMATTER, lineOffset: split.lineOffset });
+        if (parsed.ok)
+            fields = parsed.value;
+        else
+            problems.push(`frontmatter: ${parsed.error.message}`);
+    }
+    const text = (key) => {
+        const v = fields[key];
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v === 'string')
+            return v;
+        if (typeof v === 'number' || typeof v === 'boolean')
+            return String(v);
+        problems.push(`${key}: must be a single value (got ${shapeOf(v)}) — quote it if it is text`);
+        return undefined;
+    };
+    const declaredId = text('id')?.trim();
+    const title = text('title');
+    const status = text('status');
+    const date = text('date');
+    if (problems.length > 0) {
+        return {
+            rejected: {
+                file: full,
+                index: -1,
+                ...(declaredId ? { entryId: declaredId } : {}),
+                reasons: problems,
+                cause: RejectionCause.Invalid,
+            },
+        };
+    }
+    // A key with no value (`id:`, `title:`, `status:`) is absent and falls back to
+    // its default — the old splitter read `id:` as the id "" and `title:` as the
+    // title "". An id that is empty after trimming falls back too: "" can never
+    // be referenced.
+    const id = declaredId || nodePath.basename(fileName, nodePath.extname(fileName)).trim();
+    const body = split.body;
+    return {
+        record: {
+            schema: DECISION_RECORD_SCHEMA,
+            id,
+            title: title ?? id,
+            status: status ?? DecisionStatus.Proposed,
+            context: sectionFromBody(body, 'Context'),
+            decision: sectionFromBody(body, 'Decision'),
+            consequences: sectionFromBody(body, 'Consequences'),
+            relatedRules: listLinesUnder(body, 'Related rules'),
+            relatedPolicies: listLinesUnder(body, 'Related policies'),
+            relatedConstructs: listLinesUnder(body, 'Related constructs'),
+            relatedFiles: listLinesUnder(body, 'Related files'),
+            date: date ?? '',
+            sourceFile: full,
+        },
+    };
+}
+/**
+ * Every Markdown decision record under {@link DECISION_DIRS}, in a
+ * deterministic order: the records read, and every file refused. THE one pass
+ * both {@link listDecisions} (records) and {@link loadTsDecisionsWithIssues}
+ * (rejected) read, so what is listed and what is reported cannot disagree.
+ */
+function scanMarkdownDecisions(projectRoot) {
+    const records = [];
+    const rejected = [];
+    for (const rel of DECISION_DIRS) {
+        const dir = nodePath.join(projectRoot, rel);
+        if (!existsSync(dir))
             continue;
-        const k = line.slice(0, idx).trim();
-        const v = line.slice(idx + 1).trim().replace(/^"(.*)"$/, '$1');
-        fm[k] = v;
+        let entries = [];
+        try {
+            // Sort so the decision-record list (and the doctor findings derived from
+            // it) is deterministic, not filesystem-order-dependent.
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const f of entries) {
+            if (!/\.(md|markdown)$/i.test(f))
+                continue;
+            const full = nodePath.join(dir, f);
+            try {
+                const st = statSync(full);
+                if (!st.isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const read = readMarkdownDecision(full, f);
+            if ('record' in read)
+                records.push(read.record);
+            else
+                rejected.push(read.rejected);
+        }
     }
-    return { fm, body: m[2] ?? '' };
+    return { records, rejected };
 }
 function sectionFromBody(body, header) {
     const lines = body.split('\n');
@@ -73,54 +208,10 @@ export function listDecisions(inspection) {
         seenIds.add(rec.id);
         out.push(rec);
     };
-    for (const rel of DECISION_DIRS) {
-        const dir = nodePath.join(inspection.projectRoot, rel);
-        if (!existsSync(dir))
-            continue;
-        let entries = [];
-        try {
-            // Sort so the decision-record list (and the doctor findings derived from
-            // it) is deterministic, not filesystem-order-dependent.
-            entries = readdirSync(dir).sort();
-        }
-        catch {
-            continue;
-        }
-        for (const f of entries) {
-            if (!/\.(md|markdown)$/i.test(f))
-                continue;
-            const full = nodePath.join(dir, f);
-            try {
-                const st = statSync(full);
-                if (!st.isFile())
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            const text = readFileSync(full, 'utf8');
-            const { fm, body } = frontmatterAndBody(text);
-            const id = (fm['id'] ?? nodePath.basename(f, nodePath.extname(f))).trim();
-            const title = fm['title'] ?? id;
-            const status = fm['status'] ?? DecisionStatus.Proposed;
-            const date = fm['date'] ?? '';
-            addMd({
-                schema: DECISION_RECORD_SCHEMA,
-                id,
-                title,
-                status,
-                context: sectionFromBody(body, 'Context'),
-                decision: sectionFromBody(body, 'Decision'),
-                consequences: sectionFromBody(body, 'Consequences'),
-                relatedRules: listLinesUnder(body, 'Related rules'),
-                relatedPolicies: listLinesUnder(body, 'Related policies'),
-                relatedConstructs: listLinesUnder(body, 'Related constructs'),
-                relatedFiles: listLinesUnder(body, 'Related files'),
-                date,
-                sourceFile: full,
-            });
-        }
-    }
+    // A Markdown record whose frontmatter cannot be read as declared is not
+    // listed — `loadTsDecisionsWithIssues` reports it rejected (same scan).
+    for (const rec of scanMarkdownDecisions(inspection.projectRoot).records)
+        addMd(rec);
     // Also include sync-cached TS decisions if present (loaded by
     // listDecisionsTsCached on prior async warm-up). Best-effort sync read.
     for (const r of getTsDecisionsCached(inspection.projectRoot)) {
@@ -135,18 +226,59 @@ const TS_DECISION_CACHE = new Map();
 function getTsDecisionsCached(projectRoot) {
     return TS_DECISION_CACHE.get(projectRoot) ?? [];
 }
+/**
+ * THE TS-decision acceptance predicate (round 12, 12.1): a non-empty string
+ * `id` — `[]` means accepted. An id-less decision used to be dropped with no
+ * signal (`if (!rec?.id) return`).
+ */
+export function decisionRejectionReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['(entry): must be an object'];
+    const id = raw.id;
+    return typeof id === 'string' && id.length > 0 ? [] : ['id: must be a non-empty string'];
+}
 /**
  * Async warm-up for `sharkcraft/decisions.ts` and pack-contributed
  * decisions. Call this before `listDecisions` if you want TS decisions
  * folded in.
  */
 export async function loadTsDecisions(inspection) {
+    return (await loadTsDecisionsWithIssues(inspection)).decisions;
+}
+/**
+ * {@link loadTsDecisions} with what did not take effect (round 12, 12.1): a
+ * decision file that failed to import (it used to be swallowed to `[]`), and
+ * every declared decision the loader refused — invalid, or a duplicate id.
+ * `rejected` also carries every Markdown record (`sharkcraft/decisions/*.md`,
+ * `docs/adr/*.md`) whose frontmatter THE parser cannot read as declared (round
+ * 15 follow-up, F6) — the same scan {@link listDecisions} reads, so a record is
+ * either listed or reported here, never neither.
+ */
+export async function loadTsDecisionsWithIssues(inspection) {
     const out = [];
-    const seen = new Set();
-    const addInput = (rec, source) => {
-        if (!rec?.id || seen.has(rec.id))
+    const issues = [];
+    const rejected = [...scanMarkdownDecisions(inspection.projectRoot).rejected];
+    const seen = new Map();
+    const addInput = (raw, source, index) => {
+        const reasons = decisionRejectionReasons(raw);
+        if (reasons.length > 0) {
+            rejected.push({ file: source, index, exportName: 'default', reasons, cause: RejectionCause.Invalid });
             return;
-        seen.add(rec.id);
+        }
+        const rec = raw;
+        const prev = seen.get(rec.id);
+        if (prev !== undefined) {
+            rejected.push({
+                file: source,
+                index,
+                exportName: 'default',
+                entryId: rec.id,
+                reasons: [`id: "${rec.id}" is already declared in ${prev}`],
+                cause: RejectionCause.DuplicateId,
+            });
+            return;
+        }
+        seen.set(rec.id, source);
         out.push({
             schema: DECISION_RECORD_SCHEMA,
             id: rec.id,
@@ -159,40 +291,51 @@ export async function loadTsDecisions(inspection) {
             relatedPolicies: rec.relatedPolicies ?? [],
             relatedConstructs: rec.relatedConstructs ?? [],
             relatedFiles: rec.relatedFiles ?? [],
+            ...(rec.relatedCommands && rec.relatedCommands.length > 0
+                ? { relatedCommands: rec.relatedCommands }
+                : {}),
             date: rec.date ?? '',
             sourceFile: source,
         });
     };
+    const readInto = async (file, packageName) => {
+        const r = await importDefaultArray(file);
+        if (r.error !== undefined) {
+            issues.push({
+                severity: 'warning',
+                code: 'load-failed',
+                message: `${packageName ? `Pack ${packageName} (${nodePath.relative(inspection.projectRoot, file) || file})` : `Failed to load ${nodePath.relative(inspection.projectRoot, file) || file}`}: ${r.error}`,
+                source: file,
+                ...(packageName ? { packageName } : {}),
+            });
+            return;
+        }
+        r.items.forEach((item, i) => addInput(item, file, i));
+    };
     // Local file.
     if (inspection.sharkcraftDir) {
-        const local = nodePath.join(inspection.sharkcraftDir, 'decisions.ts');
-        const arr = await importDefaultArray(local);
-        for (const r of arr)
-            addInput(r, local);
+        await readInto(nodePath.join(inspection.sharkcraftDir, 'decisions.ts'));
     }
     // Pack contributions.
     for (const pack of inspection.packs.validPacks) {
         const c = (pack.manifest?.contributions ?? {});
         for (const rel of c.decisionFiles ?? []) {
-            const full = nodePath.resolve(pack.packageRoot, rel);
-            const arr = await importDefaultArray(full);
-            for (const r of arr)
-                addInput(r, full);
+            await readInto(nodePath.resolve(pack.packageRoot, rel), pack.packageName);
         }
     }
     TS_DECISION_CACHE.set(inspection.projectRoot, out);
-    return out;
+    return { decisions: out, issues, rejected };
 }
+/** A decision file's default array; `error` (first line) when the import threw. A missing file is `[]`. */
 async function importDefaultArray(absPath) {
+    if (!existsSync(absPath))
+        return { items: [] };
     try {
-        if (!existsSync(absPath))
-            return [];
-        const { pathToFileURL } = await import('node:url');
         const mod = (await importModuleViaLoader(absPath));
-        return Array.isArray(mod.default) ? mod.default : [];
+        return { items: Array.isArray(mod.default) ? mod.default : [] };
     }
-    catch {
-        return [];
+    catch (e) {
+        return { items: [], error: (e.message ?? String(e)).split('\n')[0].trim() };
     }
 }
 export function getDecision(inspection, id) {
@@ -200,12 +343,16 @@ export function getDecision(inspection, id) {
 }
 export function previewDecisionDraft(input) {
     const id = input.id.trim();
+    // Each value is written so THE parser reads it back as written (round 15
+    // follow-up, F6): a raw `title: [WIP]` reads as a list, `title: "Quoted"` as
+    // `Quoted`. A value that already reads back stays bare.
+    const value = (v) => formatFrontmatterScalar(v, DECISION_FRONTMATTER);
     const lines = [];
     lines.push('---');
-    lines.push(`id: ${id}`);
-    lines.push(`title: ${input.title}`);
-    lines.push(`status: ${input.status ?? DecisionStatus.Proposed}`);
-    lines.push(`date: ${input.date ?? new Date().toISOString().slice(0, 10)}`);
+    lines.push(`id: ${value(id)}`);
+    lines.push(`title: ${value(input.title)}`);
+    lines.push(`status: ${value(input.status ?? DecisionStatus.Proposed)}`);
+    lines.push(`date: ${value(input.date ?? new Date().toISOString().slice(0, 10))}`);
     lines.push('---');
     lines.push('');
     lines.push(`# ${input.title}`);

package/dist/declared-cross-references.d.ts

@@ -0,0 +1,61 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import type { IKnowledgeRefResolution } from '@shrkcrft/knowledge';
+import type { IDeclaredXrefField } from './i-declared-xref-field.js';
+import type { IDeclaredXrefReport } from './i-declared-xref-report.js';
+import type { IDeclaredXrefRow } from './i-declared-xref-row.js';
+import { type ReferenceKind } from './reference-registry.js';
+import type { ISelfConfigGraph } from './self-config-doctor.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const DECLARED_XREF_SCHEMA: "sharkcraft.declared-xrefs/v1";
+/**
+ * THE table of declared fields that carry cross-reference ids.
+ *
+ * Severity: a dangling `related`-style id shrinks a result silently but does
+ * not misroute anyone, so it is a warning (`--strict` makes it fail);
+ * `supersededBy` ROUTES a reader to the current entry, so a dangling one is an
+ * error. Another cluster that validates ids inside an asset field adds a row
+ * here — it never writes its own loop.
+ */
+export declare const DECLARED_XREF_FIELDS: readonly IDeclaredXrefField[];
+/** Knowledge-backed kinds: removing a knowledge entry removes the rule / path it also is. */
+export declare const KNOWLEDGE_BACKED_KINDS: readonly ReferenceKind[];
+/**
+ * Resolve every declared cross-reference id. Synchronous: call it AFTER
+ * `warmReferenceRegistries` (or use {@link buildDeclaredXrefReport}). On a cold
+ * cache the cache-backed kinds cannot be looked up, so an id that might live
+ * in one is `unverified` — never `dangling` — and constructs are reported in
+ * `examined.unreadSources`. Never throws: a registry that will not load is its
+ * own surface's problem.
+ */
+export declare function collectDeclaredXrefs(inspection: ISharkcraftInspection): IDeclaredXrefReport;
+/** Warm the async registries, then {@link collectDeclaredXrefs}. */
+export declare function buildDeclaredXrefReport(inspection: ISharkcraftInspection): Promise<IDeclaredXrefReport>;
+/** True for a row a reader following it would find broken: dangling or wrong-kind. */
+export declare function isBrokenXref(row: IDeclaredXrefRow): boolean;
+/**
+ * Who points at `targetId` — the reverse direction. With `asKinds`, only rows
+ * whose field could mean an id of one of those kinds (a construct's
+ * `relatedTemplates: ['x']` is not a reference to a knowledge entry `x`).
+ */
+export declare function reverseXrefs(report: IDeclaredXrefReport, targetId: string, asKinds?: readonly ReferenceKind[]): readonly IDeclaredXrefRow[];
+/**
+ * The collector's coverage: every declared id must have been LOOKED UP. An
+ * unverified id (or a source that could not be enumerated) is an unexamined
+ * unit, so a verdict over it can never settle to a pass.
+ */
+export declare function declaredXrefCoverage(report: IDeclaredXrefReport): IVerdictCoverage;
+/** The one-line summary every renderer prints (`N ids across M fields · …`). */
+export declare function declaredXrefSummaryLine(report: IDeclaredXrefReport): string;
+/**
+ * The self-config graph plus one edge per declared cross-reference; dangling
+ * and wrong-kind ones are also `brokenEdges`, so `self-config broken-links`
+ * agrees with the doctor instead of printing ✓ over dead ids.
+ */
+export declare function withDeclaredXrefEdges(graph: ISelfConfigGraph, report: IDeclaredXrefReport): ISelfConfigGraph;
+/**
+ * The resolver `formatEntryFull` renders cross-references with (the knowledge
+ * package sits below this layer and cannot resolve ids itself). Warm first: on
+ * a cold cache an unresolvable id is `unverified`, never "unresolved".
+ */
+export declare function buildKnowledgeRefResolver(inspection: ISharkcraftInspection): (id: string) => IKnowledgeRefResolution;
+//# sourceMappingURL=declared-cross-references.d.ts.map

package/dist/declared-cross-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-cross-references.d.ts","sourceRoot":"","sources":["../src/declared-cross-references.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAGnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAwB,MAAM,yBAAyB,CAAC;AACtF,OAAO,KAAK,EAAE,qBAAqB,EAAe,MAAM,2BAA2B,CAAC;AAEpF,eAAO,MAAM,oBAAoB,EAAG,8BAAuC,CAAC;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,kBAAkB,EAkBpB,CAAC;AAS3C,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,EAAE,SAAS,aAAa,EAItB,CAAC;AAuYtC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,qBAAqB,GAAG,mBAAmB,CAqE3F;AAED,oEAAoE;AACpE,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAG9B;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,GACjC,SAAS,gBAAgB,EAAE,CAM7B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,CAkBlF;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAO3E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,mBAAmB,GAC1B,gBAAgB,CAalB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,qBAAqB,GAChC,CAAC,EAAE,EAAE,MAAM,KAAK,uBAAuB,CASzC"}