rcf-lite 0.0.1 → 0.8.0

package/src/core/store/tp-resolve.js

@@ -0,0 +1,176 @@
+// Test-pointer working-tree resolution (w-2026-07-28-005).
+//
+// This is the test-axis twin of `cn-resolve.js`. Every Test Case declares a
+// `testPointer` (`filePath::testName`). This module checks each pointer
+// against the CHECKED-OUT WORKING TREE: the file must exist AND a
+// declaration-anchor regex must find the named test inside it. Coverage
+// (`rcf coverage`) consumes the result: a TC whose pointer does not resolve
+// is never counted as covering its AC - it surfaces as `covered-unresolved`
+// instead. Without this, a tree full of stub TC rows reports full coverage
+// while pointing at nothing.
+//
+// Determinism (same posture as cn-resolve): file existence is `fs.stat`;
+// test presence is a fixed set of declaration-anchor regexes per language.
+// No LLM, no test execution, no parsing beyond regex. Fully reproducible
+// given a working tree.
+//
+// Language support is an anchor TABLE, keyed by file extension: adding a
+// language is one entry (id, extensions, anchorsFor). JS/TS ships now, with
+// anchors derived from this repo's own corpus (1022 x `test('name', ...)`
+// plus template-literal names) widened to the common `test` / `it` /
+// `describe` declaration forms and their `.only` / `.skip` / `.each`
+// modifier chains, across all three quote styles (', ", `).
+//
+// HONEST LIMITATION (inherited from cn-resolve, same register as
+// docs/code-nodes.md): the anchor check proves a test DECLARATION with that
+// name exists - not that the test still asserts what the AC says. A renamed
+// test is caught; a gutted-but-same-named test is NOT caught (semantic drift
+// is out of reach for a deterministic check). A test name built from a
+// template-literal interpolation cannot be anchored statically and reports
+// unresolved unless the pointer carries the literal source text.
+
+import { readFile, stat } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+
+/**
+ * Split a test pointer into its file part and test-name part.
+ * The separator is the FIRST `::`; test names may themselves contain `::`.
+ * @param {string} pointer e.g. "test/store/loader.test.js::loads a document"
+ * @returns {{ file: string, testName: string | null }}
+ */
+export function splitTestPointer(pointer) {
+  const sep = pointer.indexOf('::');
+  if (sep < 0) return { file: pointer, testName: null };
+  const testName = pointer.slice(sep + 2);
+  return { file: pointer.slice(0, sep), testName: testName.length > 0 ? testName : null };
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// The anchor table. One entry per supported language; adding a language is
+// adding an entry (nothing else changes). `anchorsFor` returns the
+// deterministic declaration-anchor matchers for a test name; a test is
+// considered PRESENT if any anchor matches the file text.
+const ANCHOR_LANGUAGES = [
+  {
+    id: 'javascript',
+    extensions: ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx'],
+    anchorsFor(testName) {
+      const n = escapeRegExp(testName);
+      // `test('name'` / `it("name"` / `describe(`name`` plus modifier
+      // chains (`test.skip(`, `it.only(`, `test.each(...)(` is NOT chased -
+      // parameterised names are dynamic and out of deterministic reach).
+      const head = String.raw`\b(?:test|it|describe)(?:\.\w+)*\s*\(\s*`;
+      return [
+        new RegExp(`${head}'${n}'`),
+        new RegExp(`${head}"${n}"`),
+        new RegExp(`${head}\`${n}\``),
+      ];
+    },
+  },
+];
+
+function languageForFile(file) {
+  const ext = extname(file).toLowerCase();
+  return ANCHOR_LANGUAGES.find((lang) => lang.extensions.includes(ext)) ?? null;
+}
+
+/**
+ * @typedef {object} TestPointerResolution
+ * @property {boolean} resolved
+ * @property {'ok'|'missing-pointer'|'malformed-pointer'|'unsupported-file-type'|'file-missing'|'test-missing'} reason
+ * @property {string|null} testPointer - the raw pointer (null when absent)
+ * @property {string} tsId
+ * @property {string} tcId
+ */
+
+/**
+ * Key for the per-TC resolution map. Exported so consumers (coverage) and
+ * this module agree on one spelling.
+ * @param {string} tsId
+ * @param {string} tcId
+ * @returns {string}
+ */
+export function testCaseKey(tsId, tcId) {
+  return `${tsId}::${tcId}`;
+}
+
+/**
+ * Resolve every Test Case's `testPointer` in the tree against the working
+ * tree. Returns a Map keyed by `testCaseKey(tsId, tcId)`; every TC in the
+ * tree gets an entry, resolved or not. A per-file read cache avoids
+ * re-reading a file that multiple TCs point into (same posture as
+ * cn-resolve's cache).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot - absolute path to project root
+ * @param {object} args.tree - walker TreeModel (carries tree.testSuites)
+ * @returns {Promise<Map<string, TestPointerResolution>>}
+ */
+export async function resolveTestPointers({ projectRoot, tree }) {
+  /** @type {Map<string, TestPointerResolution>} */
+  const results = new Map();
+  const fileCache = new Map();
+
+  const readFileCached = async (absFile) => {
+    if (fileCache.has(absFile)) return fileCache.get(absFile);
+    let text = null;
+    try {
+      text = await readFile(absFile, 'utf8');
+    } catch {
+      text = null;
+    }
+    fileCache.set(absFile, text);
+    return text;
+  };
+
+  for (const ts of tree.testSuites ?? []) {
+    for (const tc of ts.testCases ?? []) {
+      if (!tc?.id) continue;
+      const key = testCaseKey(ts.id, tc.id);
+      const record = (resolved, reason, pointer = null) => {
+        results.set(key, { resolved, reason, testPointer: pointer, tsId: ts.id, tcId: tc.id });
+      };
+
+      const pointer = tc.testPointer;
+      if (typeof pointer !== 'string' || pointer.length === 0) {
+        record(false, 'missing-pointer');
+        continue;
+      }
+      const { file, testName } = splitTestPointer(pointer);
+      if (!testName || file.length === 0) {
+        record(false, 'malformed-pointer', pointer);
+        continue;
+      }
+      const language = languageForFile(file);
+      if (!language) {
+        record(false, 'unsupported-file-type', pointer);
+        continue;
+      }
+
+      const absFile = join(projectRoot, file);
+      let fileOk = false;
+      try {
+        const st = await stat(absFile);
+        fileOk = st.isFile();
+      } catch {
+        fileOk = false;
+      }
+      if (!fileOk) {
+        record(false, 'file-missing', pointer);
+        continue;
+      }
+
+      const text = await readFileCached(absFile);
+      const present = text != null && language.anchorsFor(testName).some((re) => re.test(text));
+      if (!present) {
+        record(false, 'test-missing', pointer);
+        continue;
+      }
+      record(true, 'ok', pointer);
+    }
+  }
+  return results;
+}

package/src/core/store/validator.js

@@ -0,0 +1,191 @@
+// Schema validator. Registers the @stravica-ai/rcf-schemas@0.2.0 bundle once
+// at start-up and exposes a single `validateDocument` entry point. Returns
+// `null` on success or a structured `validation` error on failure.
+//
+// Validation runs on load (FBS-001 / AC-701-3): the published bundle is the
+// contract, not a local copy - with ONE documented strictness overlay
+// (`testPointer` required on every Test Case; see the overlay block below).
+// Referential-integrity checking lives in the walker (D8); this module is
+// schema-shape-only.
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import commonSchema from '@stravica-ai/rcf-schemas/schemas/common.schema.json' with { type: 'json' };
+import manifestSchema from '@stravica-ai/rcf-schemas/schemas/manifest.schema.json' with { type: 'json' };
+import prdSchema from '@stravica-ai/rcf-schemas/schemas/prd.schema.json' with { type: 'json' };
+import reqSchema from '@stravica-ai/rcf-schemas/schemas/req.schema.json' with { type: 'json' };
+import userStorySchema from '@stravica-ai/rcf-schemas/schemas/user-story.schema.json' with { type: 'json' };
+import tadSchema from '@stravica-ai/rcf-schemas/schemas/tad.schema.json' with { type: 'json' };
+import tacSchema from '@stravica-ai/rcf-schemas/schemas/tac.schema.json' with { type: 'json' };
+import adrSchema from '@stravica-ai/rcf-schemas/schemas/adr.schema.json' with { type: 'json' };
+import buildSequenceSchema from '@stravica-ai/rcf-schemas/schemas/build-sequence.schema.json' with { type: 'json' };
+import fbsSchema from '@stravica-ai/rcf-schemas/schemas/fbs.schema.json' with { type: 'json' };
+import testSuiteSchema from '@stravica-ai/rcf-schemas/schemas/test-suite.schema.json' with { type: 'json' };
+// Phase 10 (X2 CodeNode bridge): 11th document kind, delivered in
+// @stravica-ai/rcf-schemas@0.3.0.
+import cnSchema from '@stravica-ai/rcf-schemas/schemas/cn.schema.json' with { type: 'json' };
+
+import { rcfError } from '../errors/index.js';
+
+// w-2026-07-28-005: strictness overlay - `testPointer` is REQUIRED on every
+// Test Case. The published bundle (0.3.1) still declares it optional; an
+// optional pointer is how 76 stub TC rows can claim coverage while pointing
+// at nothing, so Build Lite refuses the shape at the schema layer. This is
+// the ONLY local divergence from the published bundle, it is a pure
+// tightening (every document valid here is valid upstream), and it is
+// registered under the bundle's own $id so every validation path (walker
+// load, post-write gate, write verbs) inherits it. Durable home: making
+// testPointer required in @stravica-ai/rcf-schemas itself; drop this block
+// when that ships.
+const testSuiteSchemaStrict = structuredClone(testSuiteSchema);
+{
+  const testCase = testSuiteSchemaStrict.$defs.testCase;
+  testCase.required = [...testCase.required, 'testPointer'];
+  testCase.properties.testPointer = {
+    ...testCase.properties.testPointer,
+    minLength: 1,
+    description: 'Required pointer to the executable test, format: filePath::testName.',
+  };
+}
+
+/**
+ * @typedef {('manifest'|'prd'|'req'|'userStory'|'tad'|'tac'|'adr'|'buildSequence'|'fbs'|'testSuite'|'codeNode')} DocKind
+ */
+
+const SCHEMAS = {
+  manifest: manifestSchema,
+  prd: prdSchema,
+  req: reqSchema,
+  userStory: userStorySchema,
+  tad: tadSchema,
+  tac: tacSchema,
+  adr: adrSchema,
+  buildSequence: buildSequenceSchema,
+  fbs: fbsSchema,
+  // w-2026-07-28-005 overlay: the tightened copy, not the raw import.
+  testSuite: testSuiteSchemaStrict,
+  // Phase 10: Code Node.
+  codeNode: cnSchema,
+};
+
+const ID_FIELD = {
+  manifest: null,
+  prd: 'prdId',
+  req: 'reqId',
+  userStory: 'usId',
+  tad: 'tadId',
+  tac: 'tacId',
+  adr: 'adrId',
+  buildSequence: 'bsId',
+  fbs: 'fbsId',
+  // Test Suite uses the plain `id` field (see @stravica-ai/rcf-schemas@0.2.0
+  // test-suite.schema.json). No `tsId` field.
+  testSuite: 'id',
+  // Phase 10: Code Node.
+  codeNode: 'cnId',
+};
+
+let cachedAjv = null;
+
+function getAjv() {
+  if (cachedAjv) return cachedAjv;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  ajv.addSchema(commonSchema);
+  for (const schema of Object.values(SCHEMAS)) {
+    ajv.addSchema(schema);
+  }
+  cachedAjv = ajv;
+  return ajv;
+}
+
+/**
+ * Returns the set of document kinds the validator knows about.
+ * @returns {DocKind[]}
+ */
+export function knownKinds() {
+  return /** @type {DocKind[]} */ (Object.keys(SCHEMAS));
+}
+
+/**
+ * Returns the property name carrying the document's id, or null for manifest.
+ *
+ * @param {DocKind} kind
+ * @returns {string|null}
+ */
+export function idFieldFor(kind) {
+  if (!(kind in ID_FIELD)) {
+    throw new TypeError(`Unknown kind: ${kind}`);
+  }
+  return ID_FIELD[kind];
+}
+
+/**
+ * Extract the document id, or null for manifest.
+ *
+ * @param {object} doc
+ * @param {DocKind} kind
+ * @returns {string|null}
+ */
+export function documentIdOf(doc, kind) {
+  const field = idFieldFor(kind);
+  if (!field) return null;
+  const value = doc?.[field];
+  return typeof value === 'string' ? value : null;
+}
+
+/**
+ * Ajv's default `enum` message is "must be equal to one of the allowed
+ * values" and never says which. The allowed set is in `params`, which
+ * we were discarding - leaving the only way to find a valid status /
+ * priority / testLevel / category / generationStrategy be reading the
+ * schema source. Append it when Ajv provides it.
+ *
+ * @param {object} e - an Ajv error object
+ * @returns {string} suffix to append to the error message ('' when none)
+ */
+function detailOf(e) {
+  const allowed = e?.params?.allowedValues;
+  if (!Array.isArray(allowed) || allowed.length === 0) return '';
+  return ` (allowed: ${allowed.join(', ')})`;
+}
+
+/**
+ * Validate a document against its schema.
+ *
+ * @param {object} args
+ * @param {object} args.doc - parsed JSON document
+ * @param {DocKind} args.kind
+ * @param {string} [args.filePath] - optional, recorded on validation errors
+ * @returns {import('../errors/index.js').RcfError | null}
+ */
+export function validateDocument({ doc, kind, filePath }) {
+  const schema = SCHEMAS[kind];
+  if (!schema) {
+    return rcfError({
+      kind: 'validation',
+      message: `Unknown document kind: ${kind}`,
+      filePath,
+    });
+  }
+  const ajv = getAjv();
+  const validate = ajv.getSchema(schema.$id) ?? ajv.compile(schema);
+  if (validate(doc)) return null;
+  const ajvErrors = validate.errors ?? [];
+  const first = ajvErrors[0] ?? {};
+  const field = first.instancePath?.replace(/^\//, '').replace(/\//g, '.') || undefined;
+  const rule = first.keyword || undefined;
+  const message = ajvErrors
+    .map((e) => `${e.instancePath || '/'} ${e.message ?? 'invalid'}${detailOf(e)}`)
+    .join('; ');
+  const documentId = documentIdOf(doc, kind) ?? undefined;
+  return rcfError({
+    kind: 'validation',
+    message,
+    documentId,
+    filePath,
+    field,
+    rule,
+  });
+}