rcf-lite 0.7.1 → 0.9.0

package/src/admissibility/enforce.js

@@ -0,0 +1,142 @@
+// Chain-admissibility gate (NV-BL-ADM-05, NV-BL-ADM-06).
+//
+// Refuse-first per ratified ruling-sheet item 1 (2026-08-11): a chain
+// that fails any admissibility check is refused before build starts.
+// Explicit overrides are permitted for non-source-marker checks,
+// recorded in the chain with rule id, reason, and authoring identity,
+// and surfaced in the finalise summary. Source-comment markers
+// (NV-BL-ADM-04) fall outside this generic override channel and are
+// governed by the narrower ADR-only mechanism per ruling-sheet
+// item 16 -- callers apply that check separately.
+//
+// NV-BL-ADM-06 (build-stage refusal on ruleset-version drift):
+// composes with the scope-tag scans below so a build-time entry point
+// gets one call that returns a single verdict.
+
+import { detectRulesetDrift, getRuleset } from '#ruleset';
+
+import { scanAcScopeCoverage, scanTcScopeVsAc } from './scope-lint.js';
+
+/**
+ * @typedef {object} AdmissibilityOverride
+ * @property {string} rule - rule id being overridden (e.g. "NV-BL-ADM-02").
+ * @property {string} reason - operator-provided reason recorded on the chain.
+ * @property {string} [authoredBy] - author identity string.
+ * @property {string} [documentId] - optional pin to a specific doc id.
+ */
+
+/**
+ * @typedef {object} AdmissibilityVerdict
+ * @property {'pass' | 'refuse' | 'passWithOverrides'} verdict
+ * @property {import('#core/errors').RcfError[]} findings - all findings before override application.
+ * @property {import('#core/errors').RcfError[]} unresolved - findings not covered by a supplied override.
+ * @property {AdmissibilityOverride[]} appliedOverrides
+ * @property {object} drift - shape from detectRulesetDrift.
+ */
+
+/**
+ * Should this finding be masked by the given override? Match on rule id
+ * and, when the override pins a documentId, on documentId too.
+ */
+function overrideCovers(finding, override) {
+  if (finding.rule !== override.rule) return false;
+  if (override.documentId && finding.documentId !== override.documentId) return false;
+  return true;
+}
+
+/**
+ * Enforce admissibility across the whole chain (NV-BL-ADM-05 gate) plus
+ * ruleset-version drift (NV-BL-ADM-06). Callers pass the walker tree,
+ * the chain's declared ruleset version (per DL-REQ-VALIDATE-03), and an
+ * optional list of recorded overrides.
+ *
+ * A pure function on top of the ruleset + tree. Callers decide what to
+ * do with a `refuse` verdict (`rcf build` refuses with exit 4; a query
+ * or traceability tool refuses to surface the chain per the item 1
+ * addendum -- see `#query/refuse-on-admissibility`).
+ *
+ * @param {object} args
+ * @param {object} args.tree - walker output
+ * @param {string|null} [args.chainRulesetVersion]
+ * @param {AdmissibilityOverride[]} [args.overrides]
+ * @param {object} [args.opts]
+ * @param {boolean} [args.opts.tolerateUnclassified] - default true.
+ * @returns {Promise<AdmissibilityVerdict>}
+ */
+export async function enforceAdmissibility({
+  tree,
+  chainRulesetVersion = null,
+  overrides = [],
+  opts = {},
+} = {}) {
+  const ruleset = await getRuleset();
+  const drift = await detectRulesetDrift({ chainRulesetVersion, ruleset });
+
+  const findings = [];
+
+  // NV-BL-ADM-06: build-stage refusal on behavioural drift. Missing
+  // chain-ruleset-version is a separate class -- the chain never
+  // declared a version, so we cannot classify drift; the finding
+  // asks the operator to run the define-stage warning path
+  // (DL-REQ-VALIDATE-03) or acknowledge the omission via override.
+  if (drift.drift === 'behavioural') {
+    findings.push({
+      kind: 'validation',
+      message: `NV-BL-ADM-06: chain was authored against ruleset version ${drift.chainVersion}; shipping version is ${drift.shippingVersion}. Behaviour-changing drift refuses at build stage.`,
+      rule: 'NV-BL-ADM-06',
+    });
+  } else if (drift.drift === 'missing') {
+    findings.push({
+      kind: 'validation',
+      message: `NV-BL-ADM-06: chain does not declare a ruleset version. Run the define-stage adequacy check against ruleset ${drift.shippingVersion} (DL-REQ-VALIDATE-03) or record an override.`,
+      rule: 'NV-BL-ADM-06',
+    });
+  }
+
+  // NV-BL-ADM-02 / -03: scope-tag coverage + TC-scope-vs-AC-scope.
+  findings.push(...scanAcScopeCoverage(tree, opts));
+  findings.push(...scanTcScopeVsAc(tree, opts));
+
+  // NV-BL-ADM-05: refuse-first, override-recorded. Overrides are
+  // recorded on the chain; we apply them here to produce the
+  // unresolved-findings set. Source-comment markers (NV-BL-ADM-04) do
+  // NOT flow through this override channel; callers running that scan
+  // filter its findings only through the ADR-only channel per
+  // ruling-sheet item 16.
+  const appliedOverrides = [];
+  const unresolved = [];
+  for (const finding of findings) {
+    if (finding.rule === 'NV-BL-ADM-04') {
+      // Guardrail: source-marker findings must never be masked through
+      // the generic override channel. If a caller mistakenly threaded
+      // them into this function, leave them unresolved.
+      unresolved.push(finding);
+      continue;
+    }
+    const hit = overrides.find((o) => overrideCovers(finding, o));
+    if (hit) {
+      appliedOverrides.push(hit);
+      continue;
+    }
+    unresolved.push(finding);
+  }
+
+  let verdict;
+  if (unresolved.length === 0 && appliedOverrides.length === 0) verdict = 'pass';
+  else if (unresolved.length === 0) verdict = 'passWithOverrides';
+  else verdict = 'refuse';
+
+  return { verdict, findings, unresolved, appliedOverrides, drift };
+}
+
+/**
+ * Convenience: the ruleset's toolScope block. Query / traceability tools
+ * read this to decide whether to apply the refuse-first posture when
+ * surfacing chain data (NV-BL-SR-03 addendum on ruling-sheet item 1).
+ *
+ * @returns {Promise<{ chainAdmissibility: boolean, traceabilityAndQueryTools: boolean }>}
+ */
+export async function getRulesetToolScope() {
+  const ruleset = await getRuleset();
+  return ruleset.toolScope;
+}

package/src/admissibility/index.js

@@ -0,0 +1,8 @@
+// Public surface for the chain-admissibility gate (0.8.0 slug-train,
+// car 3). Rules consumed from the shared standards ruleset bundled
+// inside this umbrella package (`#ruleset`) per the ratified
+// requirements doc (2026-08-06 canonical since 2026-08-12).
+
+export { enforceAdmissibility, getRulesetToolScope } from './enforce.js';
+export { scanAcScopeCoverage, scanTcScopeVsAc } from './scope-lint.js';
+export { scanFilesForMarkers, scanSourceStringForMarkers } from './markers.js';

package/src/admissibility/markers.js

@@ -0,0 +1,104 @@
+// Source-comment marker scanner (NV-BL-ADM-04).
+//
+// Scans a set of source files for admission markers from the ratified
+// vocabulary carried on the shared standards ruleset
+// (`sourceCommentMarkers[]`). Any match is a finding. Per ratified
+// ruling-sheet item 16, the only permitted override channel is an ADR
+// recording the deferral for a genuine external-boundary blocker; the
+// generic recorded-override channel (NV-BL-ADM-05) does not cover
+// source markers.
+//
+// This module produces findings only. Wiring the gate into
+// `rcf build --mark complete` is a build-lite verb change that reads
+// the FBS's build-sequence files and calls `scanSourceForMarkers` for
+// each; the CLI change belongs in that verb's PR, not here.
+
+import { readFile } from 'node:fs/promises';
+
+import { rcfError } from '#core/errors';
+import { getRuleset } from '#ruleset';
+
+/**
+ * Compile the ruleset's marker vocabulary into a single case-insensitive
+ * pattern. Markers are ratified as case-insensitive per NV-BL-ADM-04, so
+ * we build the pattern with the `i` flag. Longest markers first so
+ * "v1 refinement" wins over "v1" if a shorter marker is ever added to
+ * the vocabulary in future releases.
+ *
+ * @param {Array<{ marker: string, caseInsensitive: boolean }>} markers
+ * @returns {RegExp}
+ */
+function compileMarkerPattern(markers) {
+  const sorted = [...markers].sort((a, b) => b.marker.length - a.marker.length);
+  const alternation = sorted
+    .map((m) => m.marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|');
+  // Boundary-free by design: matches a marker anywhere in a comment
+  // ("PLACEHOLDER function" matches; "// placeholder" matches; a random
+  // word like "todos" also matches, which is the trade-off named in the
+  // ruleset's NV-BL-ADM-04 notes -- false positives on unrelated tokens
+  // are cheaper than false negatives on real deferrals.
+  return new RegExp(`(${alternation})`, 'ig');
+}
+
+/**
+ * Scan a single source string for the ratified marker vocabulary.
+ * Returns one finding per match, with line + column offsets. Empty
+ * input returns an empty findings array.
+ *
+ * @param {string} source
+ * @param {object} [opts]
+ * @param {string} [opts.filePath] - decorates each finding for callers
+ * @param {Array<{ marker: string, caseInsensitive: boolean }>} [opts.markers]
+ * @returns {Promise<import('#core/errors').RcfError[]>}
+ */
+export async function scanSourceStringForMarkers(source, { filePath, markers } = {}) {
+  if (typeof source !== 'string' || source.length === 0) return [];
+  const vocab = markers ?? (await getRuleset()).sourceCommentMarkers;
+  const pattern = compileMarkerPattern(vocab);
+  const findings = [];
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const before = source.slice(0, match.index);
+    const line = before.split('\n').length;
+    const lastNewline = before.lastIndexOf('\n');
+    const column = match.index - (lastNewline === -1 ? -1 : lastNewline);
+    findings.push(rcfError({
+      kind: 'validation',
+      message: `NV-BL-ADM-04: source-comment admission marker "${match[1]}" at ${filePath ?? '<source>'}:${line}:${column}`,
+      filePath: filePath ?? null,
+      rule: 'NV-BL-ADM-04',
+    }));
+  }
+  return findings;
+}
+
+/**
+ * Scan a set of files by path for the ratified marker vocabulary. IO
+ * failures on a single file are captured as `ioFailure` findings; other
+ * files continue to scan. Order is deterministic in the input file list.
+ *
+ * @param {string[]} filePaths - absolute paths to scan
+ * @returns {Promise<import('#core/errors').RcfError[]>}
+ */
+export async function scanFilesForMarkers(filePaths) {
+  if (!Array.isArray(filePaths) || filePaths.length === 0) return [];
+  const ruleset = await getRuleset();
+  const vocab = ruleset.sourceCommentMarkers;
+  const findings = [];
+  for (const filePath of filePaths) {
+    try {
+      const source = await readFile(filePath, 'utf8');
+      const perFile = await scanSourceStringForMarkers(source, { filePath, markers: vocab });
+      findings.push(...perFile);
+    } catch (err) {
+      findings.push(rcfError({
+        kind: 'ioFailure',
+        message: `NV-BL-ADM-04: failed to read source for marker scan: ${err.message}`,
+        filePath,
+        rule: 'NV-BL-ADM-04',
+      }));
+    }
+  }
+  return findings;
+}

package/src/admissibility/scope-lint.js

@@ -0,0 +1,163 @@
+// Chain-admissibility scope checks (NV-BL-ADM-02, NV-BL-ADM-03).
+//
+// The scope-tag vocabulary itself lives on rcf-schemas 0.4.3
+// (`common.$defs.scopeTag`). This module consumes the tags off ACs
+// and TCs and enforces the admissibility rules the shared standards
+// ruleset references (`NV-BL-ADM-02` for AC scope classification and
+// `NV-BL-ADM-03` for TC scope >= AC scope).
+//
+// Refuse-first, override-recorded per NV-BL-ADM-05; source-comment
+// markers are governed separately by NV-BL-ADM-04 and its ADR-only
+// override channel.
+
+import { rcfError } from '#core/errors';
+
+/**
+ * Rank each scope so we can compare "TC scope >= AC scope" numerically.
+ * `unclassified` is the migration state; ranked -1 so a TC-scoped
+ * unclassified against a runtime-scope AC surfaces as a mismatch.
+ * @type {Record<string, number>}
+ */
+const SCOPE_RANK = Object.freeze({
+  library: 1,
+  runtime: 2,
+  deployed: 3,
+  unclassified: -1,
+});
+
+/**
+ * True when the tag is a known scope value per the shared vocabulary.
+ * @param {unknown} tag
+ * @returns {boolean}
+ */
+function isKnownScope(tag) {
+  return typeof tag === 'string' && Object.prototype.hasOwnProperty.call(SCOPE_RANK, tag);
+}
+
+/**
+ * NV-BL-ADM-02: every AC must carry a known scope tag. An AC without a
+ * scope, or with a non-vocabulary value, produces an admissibility
+ * finding. Per the ruleset's `unclassifiedMigrationTolerance` block,
+ * an AC scoped `unclassified` is currently tolerated (findings not
+ * emitted); callers who want to enforce full migration pass
+ * `tolerateUnclassified: false`.
+ *
+ * @param {object} tree - walkTree output
+ * @param {object} [opts]
+ * @param {boolean} [opts.tolerateUnclassified] - default true (migration state)
+ * @returns {import('#core/errors').RcfError[]}
+ */
+export function scanAcScopeCoverage(tree, { tolerateUnclassified = true } = {}) {
+  const findings = [];
+  for (const us of tree.userStories ?? []) {
+    for (const ac of us.acceptanceCriteria ?? []) {
+      const scope = ac?.scope;
+      if (scope === undefined) {
+        findings.push(rcfError({
+          kind: 'validation',
+          message: `NV-BL-ADM-02: AC ${ac.id} on US ${us.usId} carries no scope tag`,
+          documentId: ac.id,
+          field: 'scope',
+          rule: 'NV-BL-ADM-02',
+        }));
+        continue;
+      }
+      if (!isKnownScope(scope)) {
+        findings.push(rcfError({
+          kind: 'validation',
+          message: `NV-BL-ADM-02: AC ${ac.id} on US ${us.usId} carries an unknown scope tag "${scope}"`,
+          documentId: ac.id,
+          field: 'scope',
+          rule: 'NV-BL-ADM-02',
+        }));
+        continue;
+      }
+      if (scope === 'unclassified' && !tolerateUnclassified) {
+        findings.push(rcfError({
+          kind: 'validation',
+          message: `NV-BL-ADM-02: AC ${ac.id} on US ${us.usId} still scoped "unclassified" after the migration window`,
+          documentId: ac.id,
+          field: 'scope',
+          rule: 'NV-BL-ADM-02',
+        }));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * NV-BL-ADM-03: for each AC, every bound TC's scope must be equal to
+ * or wider than the AC's scope. A library-scope TC bound to a
+ * runtime-scope AC surfaces as a mismatch. TCs with no scope tag are
+ * flagged the same way ACs are in NV-BL-ADM-02: absent = finding
+ * (bootstrap: unclassified tolerated).
+ *
+ * @param {object} tree - walkTree output
+ * @param {object} [opts]
+ * @param {boolean} [opts.tolerateUnclassified] - default true
+ * @returns {import('#core/errors').RcfError[]}
+ */
+export function scanTcScopeVsAc(tree, { tolerateUnclassified = true } = {}) {
+  const findings = [];
+  const acScope = new Map();
+  for (const us of tree.userStories ?? []) {
+    for (const ac of us.acceptanceCriteria ?? []) {
+      if (ac?.id) acScope.set(ac.id, ac.scope);
+    }
+  }
+  for (const ts of tree.testSuites ?? []) {
+    for (const tc of ts.testCases ?? []) {
+      if (!tc?.id || !tc?.acId) continue;
+      const tcScope = tc?.scope;
+      const acTag = acScope.get(tc.acId);
+      if (acTag === undefined || !isKnownScope(acTag) || acTag === 'unclassified') {
+        // The AC's own scope problem surfaces via scanAcScopeCoverage;
+        // this scan is silent for ACs the classifier could not read.
+        continue;
+      }
+      if (tcScope === undefined) {
+        findings.push(rcfError({
+          kind: 'validation',
+          message: `NV-BL-ADM-03: TC ${tc.id} on TS ${ts.id} carries no scope tag (bound AC ${tc.acId} is scope=${acTag})`,
+          documentId: tc.id,
+          field: 'scope',
+          rule: 'NV-BL-ADM-03',
+        }));
+        continue;
+      }
+      if (!isKnownScope(tcScope)) {
+        findings.push(rcfError({
+          kind: 'validation',
+          message: `NV-BL-ADM-03: TC ${tc.id} on TS ${ts.id} carries an unknown scope tag "${tcScope}"`,
+          documentId: tc.id,
+          field: 'scope',
+          rule: 'NV-BL-ADM-03',
+        }));
+        continue;
+      }
+      if (tcScope === 'unclassified') {
+        if (!tolerateUnclassified) {
+          findings.push(rcfError({
+            kind: 'validation',
+            message: `NV-BL-ADM-03: TC ${tc.id} on TS ${ts.id} still scoped "unclassified" after the migration window`,
+            documentId: tc.id,
+            field: 'scope',
+            rule: 'NV-BL-ADM-03',
+          }));
+        }
+        continue;
+      }
+      if (SCOPE_RANK[tcScope] < SCOPE_RANK[acTag]) {
+        findings.push(rcfError({
+          kind: 'validation',
+          message: `NV-BL-ADM-03: TC ${tc.id} scope "${tcScope}" is narrower than the AC ${tc.acId} scope "${acTag}"; a bound TC must be equal to or wider than the AC scope`,
+          documentId: tc.id,
+          field: 'scope',
+          rule: 'NV-BL-ADM-03',
+        }));
+      }
+    }
+  }
+  return findings;
+}