rcf-lite 0.0.1 → 0.8.0

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;
+}

package/src/browser-verify/auth-smoke.js

@@ -0,0 +1,109 @@
+// Auth-REQ smoke checks (ui-design-gate-0.7.0-spec §9).
+//
+// A small pack of curl-shape checks that run at Finalise for any FBS
+// binding an auth REQ. Composes with Track A's preflight rec 3
+// (`uiBaseline.defaults.authFlow.htmlLoginPageRequired`); when the
+// baseline says API-only, the pack is skipped.
+//
+// Directly addresses the cold-run defect where `/login` returned 404
+// for the full run. Implemented as fetch-shaped checks against a
+// runtime URL; the runner (injectable) is the ambient `fetch` by
+// default. Callers pass `runtimeUrl` (e.g. http://127.0.0.1:3000).
+
+/**
+ * @typedef {object} AuthSmokeResult
+ * @property {string} check
+ * @property {number} [status]
+ * @property {string} [contentType]
+ * @property {'pass'|'warn'|'fail'} verdict
+ * @property {string} [detail]
+ */
+
+/**
+ * @typedef {object} AuthSmokeRunnerInput
+ * @property {(url: string, init?: object) => Promise<{ status: number, headers: { get: (name: string) => string|null } }>} fetch
+ * @property {string} runtimeUrl
+ */
+
+const HTML_CONTENT_TYPE_RE = /^text\/html\b/i;
+
+/**
+ * True when a FBS should run the auth smoke pack. Reads (in priority
+ * order) the FBS's own dependsOnServices auth categories, then falls
+ * back to the manifest's uiBaseline.defaults.authFlow.smokeChecksRequired.
+ *
+ * @param {object} fbs
+ * @param {object|null} uiBaseline
+ * @returns {boolean}
+ */
+export function shouldRunAuthSmokeChecks(fbs, uiBaseline) {
+  const services = Array.isArray(fbs?.dependsOnServices) ? fbs.dependsOnServices : [];
+  const authCategories = new Set(['auth', 'oauth', 'identityProvider', 'emailAuth']);
+  const bindsAuth = services.some((s) => authCategories.has(String(s?.serviceCategory ?? '')));
+  const baselineRequires = uiBaseline?.defaults?.authFlow?.htmlLoginPageRequired === true
+    && uiBaseline?.defaults?.authFlow?.smokeChecksRequired !== false;
+  return bindsAuth || baselineRequires;
+}
+
+/**
+ * Run the smoke pack against `runtimeUrl`. Returns one result per check.
+ *
+ * @param {AuthSmokeRunnerInput} args
+ * @returns {Promise<AuthSmokeResult[]>}
+ */
+export async function runAuthSmokeChecks({ fetch, runtimeUrl }) {
+  /** @type {AuthSmokeResult[]} */
+  const results = [];
+  results.push(await runOne({
+    check: 'GET /login', fetch,
+    request: () => fetch(joinUrl(runtimeUrl, '/login')),
+    accept: (status, contentType) => {
+      if (status !== 200) return { verdict: 'fail', detail: `status ${status} (expected 200)` };
+      if (!HTML_CONTENT_TYPE_RE.test(contentType ?? '')) return { verdict: 'fail', detail: `content-type '${contentType ?? '(missing)'}' (expected text/html)` };
+      return { verdict: 'pass' };
+    },
+  }));
+  results.push(await runOne({
+    check: 'POST /logout', fetch,
+    request: () => fetch(joinUrl(runtimeUrl, '/logout'), { method: 'POST', redirect: 'manual' }),
+    accept: (status) => {
+      if (status === 200 || status === 302 || status === 303) return { verdict: 'pass' };
+      return { verdict: 'fail', detail: `status ${status} (expected 200 | 302 | 303)` };
+    },
+  }));
+  results.push(await runOne({
+    check: 'GET /login/verify?token=',
+    fetch,
+    request: () => fetch(joinUrl(runtimeUrl, '/login/verify?token='), { redirect: 'manual' }),
+    accept: (status) => {
+      if (status === 400 || status === 401 || status === 403) return { verdict: 'pass' };
+      if (status === 302 || status === 303) return { verdict: 'pass' };
+      if (status === 200) return { verdict: 'fail', detail: 'status 200 (empty-token accepted; regression on the empty-token vuln)' };
+      return { verdict: 'fail', detail: `status ${status} (expected 400 | 401 | 403 | 302 | 303)` };
+    },
+  }));
+  return results;
+}
+
+async function runOne({ check, request, accept }) {
+  try {
+    const response = await request();
+    const status = response?.status;
+    const contentType = response?.headers?.get ? response.headers.get('content-type') : null;
+    const outcome = accept(status, contentType);
+    return {
+      check,
+      status,
+      ...(contentType ? { contentType } : {}),
+      verdict: outcome.verdict,
+      ...(outcome.detail ? { detail: outcome.detail } : {}),
+    };
+  } catch (err) {
+    return { check, verdict: 'fail', detail: `request failed: ${err.message}` };
+  }
+}
+
+function joinUrl(base, path) {
+  const trimmed = base.replace(/\/+$/, '');
+  return `${trimmed}${path.startsWith('/') ? path : `/${path}`}`;
+}

package/src/browser-verify/index.js

@@ -0,0 +1,29 @@
+// Public surface for the browser-verify module
+// (ui-design-gate-0.7.0-spec §8, §9). CLI handler at
+// `src/cli/browser-verify.js`.
+
+export {
+  UI_INVARIANTS_V1,
+  compareTopLevelStructure,
+  foldInvariantsForRecord,
+  runInvariantsForCapture,
+} from './invariants.js';
+
+export {
+  runAuthSmokeChecks,
+  shouldRunAuthSmokeChecks,
+} from './auth-smoke.js';
+
+export {
+  aggregateVerdict,
+  composeBrowserVerificationRecord,
+  nextBrowserVerificationId,
+  writeBrowserVerificationAck,
+  writeBrowserVerificationRecord,
+} from './manifest-writer.js';
+
+export {
+  composeOperatorSessionRecord,
+  runAgentScreenshotCritique,
+  stubBrowserDriver,
+} from './runner.js';