rcf-lite 0.0.1 → 0.7.1

package/src/cli/ui-classify.js

@@ -0,0 +1,108 @@
+// `rcf ui-classify <fbs-id>` subcommand handler
+// (ui-design-gate-0.7.0-spec §4.2).
+//
+// Runs the UI-bearing classifier on demand and prints the verdict. No
+// side effects: the classifier does not write to the FBS document; the
+// operator ratifies via `rcf update <fbs-id> --set uiBearing=true|false`
+// when they want the verdict recorded (§4.4).
+
+import { parseArgs } from 'node:util';
+import process from 'node:process';
+
+import { walkTree } from '#core/store';
+
+import { findProjectRoot } from '../view/index.js';
+import { classifyFbs } from '../ui-detection/classifier.js';
+
+const OPTION_SPEC = {
+  json: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf ui-classify <fbs-id> [options]
+
+Run the UI-bearing classifier on one FBS and print the verdict. Does
+not write to the FBS document; ratify with:
+  rcf update <fbs-id> --set uiBearing=true
+
+Options:
+  --json                    Emit the uiClassification block as JSON.
+  --help                    Print this help.
+
+Exit codes:
+  0  classified (verdict printed)
+  1  IO / unexpected runtime failure
+  2  usage error
+  3  tree validation failure
+`;
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (parsed.positionals.length !== 1) {
+    stderr.write('[error] usage ui-classify: expected exactly one <fbs-id> positional\n');
+    return 2;
+  }
+  const fbsId = parsed.positionals[0];
+  if (!/^FBS-\d{3,}$/.test(fbsId)) {
+    stderr.write(`[error] usage ui-classify: expected an FBS id like FBS-011, got '${fbsId}'\n`);
+    return 2;
+  }
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `rcf init` first.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    stderr.write(`[warn] tree has ${errors.length} pre-existing issue(s); classification proceeds against what could be loaded\n`);
+  }
+  if (!tree.byId.has(fbsId) || tree.kindById.get(fbsId) !== 'fbs') {
+    stderr.write(`[error] usage ui-classify: ${fbsId} not found or not an FBS\n`);
+    return 2;
+  }
+
+  const now = deps.now ? new Date(deps.now()) : new Date();
+  const block = classifyFbs(tree, fbsId, { now });
+
+  if (flags.json) {
+    stdout.write(`${JSON.stringify(block, null, 2)}\n`);
+    return 0;
+  }
+
+  stdout.write(`ui-classify ${fbsId}: verdict=${block.verdict} reason=${block.reason}\n`);
+  const signals = Array.isArray(block.signals) ? block.signals : [];
+  if (signals.length > 0) {
+    stdout.write(`  signals (${signals.length}):\n`);
+    for (const s of signals) {
+      const anchor = s.acId ? `${s.source}[${s.acId}]` : s.source;
+      stdout.write(`    - ${anchor}: ${s.match}\n`);
+    }
+  }
+  if (block.verdict === 'ui') {
+    stdout.write('  Ratify with: rcf update ' + fbsId + ' --set uiBearing=true\n');
+  } else if (block.verdict === 'notUi' && signals.length === 0) {
+    stdout.write('  No UI signals detected. Override with: rcf update ' + fbsId + ' --set uiBearing=true\n');
+  } else if (block.verdict === 'operatorOverride') {
+    stdout.write('  Operator ruling recorded on FBS.uiBearing wins over the classifier.\n');
+  }
+  return 0;
+}

package/src/cli/update.js

@@ -0,0 +1,197 @@
+// `rcf update <id>` subcommand handler. Parses --set dot-path lists into
+// a patch array, optionally deep-merges a --from-file body, and calls
+// writer.updateDocument. Phase 4 §D8 (with inline-id + root-singleton
+// support).
+
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+import { isRcfError, writeUnexpectedFailure } from '#core/errors';
+import { splitCnPath, updateDocument, walkTree } from '#core/store';
+import { deriveFileDeps, mapDerivedDepsToCnIds } from '#core/store/derive-deps.js';
+import { findProjectRoot } from '../view/index.js';
+// Track C+D §4.4: reclassify a REQ when its description-carrying fields
+// change so downstream tooling sees a fresh shapeClassification.
+import { classifyAndPersistReq } from '../req-detection/index.js';
+
+const OPTION_SPEC = {
+  set: { type: 'string', multiple: true },
+  'from-file': { type: 'string' },
+  json: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+  // Phase 10 (X2 CodeNode bridge, D5): re-derive a CN's file-level
+  // dependencies via dependency-cruiser, merged into dependencies[].
+  'derive-deps': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf update <id> [options]
+
+Options:
+  --set <dotPath>=<value>   Set a field; repeatable
+  --from-file <path>        Merge body fields from a JSON file
+                            (deep merge; arrays replace)
+  --json                    Parse --set values as JSON (default: string)
+  --dry-run                 Print intended writes without executing
+  --quiet                   Suppress non-error stdout
+  --derive-deps             CN only: re-derive file-level dependencies via
+                            dependency-cruiser and merge into dependencies[]
+                            (dev-time assist; never a runtime dependency)
+  --help                    Print this help
+`;
+
+/**
+ * @param {string[]} argv - argv slice after `update`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  const positionals = parsed.positionals;
+  if (flags.help) { stdout.write(HELP); return 0; }
+  if (positionals.length !== 1) {
+    stderr.write('[error] usage update: expected exactly one <id>\n');
+    stderr.write(HELP);
+    return 2;
+  }
+  const id = positionals[0];
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+
+  const walkResult = await walkTree({ projectRoot });
+  // B5: pre-existing tree breakage no longer blocks write verbs - the
+  // update is gated on the POST-write tree state inside the writer, so
+  // repairing a broken doc is exactly what this verb is now for.
+  if (walkResult.errors.length > 0) {
+    stderr.write(`[warn] tree has ${walkResult.errors.length} pre-existing issue(s); proceeding - writes are validated against the post-write state (run 'rcf validate' for details)\n`);
+  }
+
+  const sets = [];
+  const useJson = Boolean(flags.json);
+  for (const rawSet of flags.set ?? []) {
+    const eq = rawSet.indexOf('=');
+    if (eq < 0) {
+      stderr.write(`[error] usage update: bad --set '${rawSet}' (expected <path>=<value>)\n`);
+      return 2;
+    }
+    const path = rawSet.slice(0, eq);
+    const raw = rawSet.slice(eq + 1);
+    let value = raw;
+    if (useJson) {
+      try { value = JSON.parse(raw); } catch (err) {
+        stderr.write(`[error] usage update: --json parse failed on '${raw}': ${err.message}\n`);
+        return 2;
+      }
+    }
+    sets.push({ path, value });
+  }
+  let patch = null;
+  if (flags['from-file']) {
+    try {
+      patch = JSON.parse(await readFile(flags['from-file'], 'utf8'));
+    } catch (err) {
+      stderr.write(`[error] usage update: cannot read --from-file: ${err.message}\n`);
+      return 2;
+    }
+  }
+  if (flags['derive-deps']) {
+    if (walkResult.tree.kindById.get(id) !== 'codeNode') {
+      stderr.write('[error] usage update: --derive-deps only applies to cn ids\n');
+      return 2;
+    }
+    const setPath = sets.find((s) => s.path === 'path')?.value;
+    const currentPath = typeof setPath === 'string' ? setPath : walkResult.tree.byId.get(id)?.path;
+    const { file } = splitCnPath(currentPath ?? '');
+    const derived = await deriveFileDeps({ projectRoot, filePath: file });
+    if (!derived.ok) {
+      stderr.write(`[error] usage update: --derive-deps: ${derived.message}\n`);
+      return 2;
+    }
+    const { cnIds, unmatched } = mapDerivedDepsToCnIds(walkResult.tree, derived.deps);
+    const existing = walkResult.tree.byId.get(id)?.dependencies ?? [];
+    const merged = [...new Set([...existing, ...cnIds])].filter((d) => d !== id).sort();
+    sets.push({ path: 'dependencies', value: merged });
+    if (unmatched.length > 0 && !flags.quiet) {
+      stdout.write(`[info] --derive-deps: ${unmatched.length} file-level import(s) have no matching CN yet, skipped: ${unmatched.join(', ')}\n`);
+    }
+  }
+  if (sets.length === 0 && !patch) {
+    stderr.write('[error] usage update: at least one --set or --from-file is required\n');
+    return 2;
+  }
+  const result = await updateDocument({
+    projectRoot, tree: walkResult.tree, id, patch, sets,
+    options: { dryRun: Boolean(flags['dry-run']) },
+    walkErrors: walkResult.errors,
+  });
+  if (isRcfError(result)) return handleWriterError(result, stderr);
+  if (flags['dry-run']) {
+    if (!flags.quiet) stdout.write(`[dry-run] would update ${result.id} at ${result.filePath}\n`);
+    return 0;
+  }
+  if (!flags.quiet) stdout.write(`${result.id} updated at ${result.filePath}\n`);
+
+  // Track C+D §4.4: reclassify a REQ when the update touched a
+  // shape-signal-carrying field (title / description / rationale).
+  const touched = new Set();
+  for (const s of sets) {
+    const head = String(s.path ?? '').split('.')[0];
+    if (head) touched.add(head);
+  }
+  if (patch && typeof patch === 'object') {
+    for (const key of Object.keys(patch)) touched.add(key);
+  }
+  const kindOfDoc = walkResult.tree.kindById.get(id);
+  const shouldReclassify = kindOfDoc === 'requirement'
+    && (touched.has('title') || touched.has('description') || touched.has('rationale'));
+  if (shouldReclassify) {
+    try {
+      const postWalk = await walkTree({ projectRoot });
+      const classifyOutcome = await classifyAndPersistReq({
+        projectRoot,
+        tree: postWalk.tree,
+        reqId: id,
+      });
+      if (classifyOutcome && classifyOutcome.ok === false) {
+        stderr.write(`[warn] ${classifyOutcome.message}\n`);
+      } else if (!flags.quiet && classifyOutcome?.changed && classifyOutcome.block?.shapes?.length > 0) {
+        const shapes = classifyOutcome.block.shapes.join(', ');
+        stdout.write(`${id} shapeClassification: [${shapes}] (${classifyOutcome.block.reason})\n`);
+      }
+    } catch (err) {
+      stderr.write(`[warn] req-classify (post-update): ${err.message}\n`);
+    }
+  }
+  return 0;
+}
+
+function handleWriterError(err, stderr) {
+  const kind = err.kind;
+  // BUG-007 fix: spec §D15 mandates exit-1 emit
+  // `[rcf] unexpected failure: <msg>\n<stack>` — even under --quiet.
+  if (kind === 'ioFailure') {
+    writeUnexpectedFailure(err, stderr);
+    return 1;
+  }
+  stderr.write(`[error] ${kind} ${err.message}\n`);
+  if (kind === 'usage') return 2;
+  if (kind === 'validation' || kind === 'brokenReference') return 3;
+  return 1;
+}

package/src/cli/validate.js

@@ -0,0 +1,168 @@
+// `rcf validate` subcommand handler. Wraps walker + validator + broken-
+// reference machinery. Exits 0 clean, 2 on usage failure, 3 on validation
+// or broken-references. Phase 4 §D3.
+
+import { parseArgs } from 'node:util';
+
+import { formatErrors } from '#core/errors';
+import { checkCodeNodeResolution, walkTree } from '#core/store';
+import { findProjectRoot } from '../view/index.js';
+
+const OPTION_SPEC = {
+  quiet: { type: 'boolean' },
+  json: { type: 'boolean' },
+  help: { type: 'boolean' },
+  // Phase 10 (X2 CodeNode bridge, spec D8): skip the Code Node staleness
+  // pass (spec-graph checks only). The default remains full validation -
+  // the staleCode floor is only a floor if it runs by default.
+  'no-code': { type: 'boolean' },
+};
+
+export const HELP = `Usage: rcf validate [options]
+
+Walk the rcf/ tree and report schema-validation and broken-reference
+issues. Exits 0 when clean, 3 on issues.
+
+Options:
+  --quiet                   Only summary line + first 3 issues
+  --json                    Emit machine-readable envelope
+  --no-code                 Skip the Code Node staleness pass (spec-graph
+                            checks only; the default runs full validation)
+  --help                    Print this help
+`;
+
+// Case-insensitive whole-word TODO match. Word-bounded so incidental
+// substrings (e.g. "autodoc") do not trip the scan.
+const TODO_RE = /\btodo\b/i;
+
+/**
+ * Recursively collect dot-paths of string fields containing TODO
+ * placeholder text.
+ * @param {unknown} value
+ * @param {string} path
+ * @param {string[]} out
+ */
+function findTodoFields(value, path, out) {
+  if (typeof value === 'string') {
+    if (TODO_RE.test(value)) out.push(path);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => findTodoFields(v, `${path}[${i}]`, out));
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) {
+      findTodoFields(v, path ? `${path}.${k}` : k, out);
+    }
+  }
+}
+
+/**
+ * Scan every loaded document (roots + children; inline ACs / TCs ride
+ * inside their parent doc's fields) for TODO placeholder text left over
+ * from `rcf init` scaffolding. Cheap by design (B4): one string sweep,
+ * one entry per affected doc.
+ * @param {object} tree - walker TreeModel
+ * @returns {Array<{ id: string, fields: string[] }>}
+ */
+function collectTodoNotices(tree) {
+  const docs = [
+    ...(tree.prd ? [{ id: tree.prd.prdId, doc: tree.prd }] : []),
+    ...(tree.tad ? [{ id: tree.tad.tadId, doc: tree.tad }] : []),
+    ...(tree.bs ? [{ id: tree.bs.bsId, doc: tree.bs }] : []),
+    ...tree.requirements.map((d) => ({ id: d.reqId, doc: d })),
+    ...tree.userStories.map((d) => ({ id: d.usId, doc: d })),
+    ...tree.tacs.map((d) => ({ id: d.tacId, doc: d })),
+    ...tree.adrs.map((d) => ({ id: d.adrId, doc: d })),
+    ...tree.fbsItems.map((d) => ({ id: d.fbsId, doc: d })),
+    ...tree.testSuites.map((d) => ({ id: d.id, doc: d })),
+  ];
+  const notices = [];
+  for (const { id, doc } of docs) {
+    /** @type {string[]} */
+    const fields = [];
+    findTodoFields(doc, '', fields);
+    if (fields.length > 0) notices.push({ id: id ?? '(unknown id)', fields });
+  }
+  return notices;
+}
+
+/**
+ * @param {string[]} argv - argv slice after `validate`
+ * @param {object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true });
+  } catch (err) {
+    stderr.write(`[error] usage ${err.message}\n`);
+    stderr.write(HELP);
+    return 2;
+  }
+  const flags = parsed.values;
+  if (flags.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] usage no project root found (no rcf/manifest.json in this directory or any ancestor). Run `npx rcf init` to create and wire a project.\n');
+    return 2;
+  }
+  const { tree, errors } = await walkTree({ projectRoot });
+  // Phase 10 (X2 CodeNode bridge, spec D6): staleness pass. Every Code
+  // Node's declared path/symbol is checked against the working tree;
+  // unresolved ones surface as `staleCode` errors folded into the same
+  // exit path as schema / referential-integrity errors. This is the X2
+  // detection claim: links that break visibly.
+  if (!flags['no-code']) {
+    const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
+    errors.push(...staleErrors);
+  }
+  if (flags.json) {
+    const issues = errors.map((e) => ({
+      id: e.documentId ?? null,
+      kind: e.kind,
+      rule: e.rule ?? null,
+      filePath: e.filePath ?? null,
+      field: e.field ?? null,
+      message: e.message,
+    }));
+    stdout.write(`${JSON.stringify({ ok: errors.length === 0, issues }, null, 2)}\n`);
+    return errors.length === 0 ? 0 : 3;
+  }
+  if (errors.length === 0) {
+    if (!flags.quiet) {
+      stdout.write('rcf validate: tree is clean.\n');
+      // B4 (E2E matrix 2026-07-06-003): scaffold TODO placeholders were
+      // surviving to otherwise-valid trees unflagged. Non-blocking notice
+      // only - the exit code is unchanged.
+      const notices = collectTodoNotices(tree);
+      if (notices.length > 0) {
+        stdout.write(`notice: ${notices.length} document(s) still carry scaffold TODO placeholder text (informational; exit code unaffected):\n`);
+        for (const n of notices) {
+          stdout.write(`  ${n.id}: ${n.fields.join(', ')}\n`);
+        }
+      }
+    }
+    return 0;
+  }
+  if (flags.quiet) {
+    const first = errors.slice(0, 3);
+    // BUG-004 fix: `--quiet` used to render `errors.length` (== 3) as the
+    // summary count. Pass the true total through so the summary reads
+    // "N errors found" for the whole tree, not just the shown subset.
+    stderr.write(`${formatErrors(first, { verbose: false, strict: false, total: errors.length })}\n`);
+    if (errors.length > 3) stderr.write(`... ${errors.length - 3} more issue(s) suppressed by --quiet\n`);
+  } else {
+    stderr.write(`${formatErrors(errors, { verbose: false, strict: false })}\n`);
+  }
+  return 3;
+}