rcf-lite 0.8.0 → 0.9.0

package/src/blueprint/namespace.js

@@ -0,0 +1,145 @@
+// Namespacing rules for blueprint-contributed doc ids.
+//
+// THE id grammar (family membership, regex shapes, filename inversion)
+// lives in `../core/store/ids.js` -- one implementation shared by the
+// blueprint stamper, the walker (idFromFilenameStem) and the loader
+// (pathForId). This module carries the blueprint-facing helpers on top
+// of that grammar (stampId / isNamespacedFor / namespaceStyleFor) and
+// re-exports parseIdParts so the public blueprint surface stays stable.
+//
+// Two families, per the 0.4.4 schemas grammar (see docs/id-conventions.md
+// in @stravica-ai/rcf-schemas):
+//
+// - Prefix families (REQ, US, PRD, BS, TAD, TS): the blueprint slug is
+//   attached as a lowercase kebab-slug PREFIX joined by `-` to the
+//   family prefix. `REQ-001` under blueprint `spa` becomes `spa-REQ-001`.
+//
+// - Suffix families (ADR, TAC, FBS, CN): the blueprint slug is attached
+//   as a lowercase kebab-slug SUFFIX joined by `-` to the numeric tail.
+//   `ADR-005` under blueprint `spa` becomes `ADR-005-spa`; a longer slug
+//   segment (`spa-theme`) becomes `ADR-005-spa-theme`.
+//
+// - AC and TC: not namespaced. AC ids are anchored to their parent US
+//   (whose id is prefix-namespaced) and TC ids are anchored to their
+//   parent TS (ditto). The 0.4.4 schemas intentionally left AC/TC
+//   patterns unchanged.
+//
+// Ownership determination is NOT a grammar concern. String grammar is
+// only used here to STAMP a bare id at first apply; ownership of an
+// already-written contribution is answered by the manifest's
+// appliedBlueprintRecord.contributions[] list -- the authoritative
+// record of exactly which ids a given applied blueprint owns. See
+// `apply.js` (overwrite guard, cross-claim check) and `remove.js`
+// (referring-doc scan) for the record-consulting call-sites.
+//
+// This module is pure: no I/O, no wall clock.
+
+import {
+  PREFIX_FAMILY_SET,
+  SLUG_PATTERN,
+  SUFFIX_FAMILY_SET,
+  UNNAMESPACED_FAMILY_SET,
+  parseIdParts,
+} from '../core/store/ids.js';
+
+// Re-exported so `import { parseIdParts } from '../blueprint/namespace.js'`
+// (and the transitive `blueprint/index.js` re-export) keep working. The
+// implementation lives in core.
+export { parseIdParts };
+
+/**
+ * Which namespacing style applies to a given id.
+ *
+ * @param {string} id
+ * @returns {'prefix' | 'suffix' | 'none' | null}
+ */
+export function namespaceStyleFor(id) {
+  const parts = parseIdParts(id);
+  if (!parts) return null;
+  if (PREFIX_FAMILY_SET.has(parts.family)) return 'prefix';
+  if (SUFFIX_FAMILY_SET.has(parts.family)) return 'suffix';
+  return 'none';
+}
+
+/**
+ * Stamp an id with a blueprint namespace at FIRST APPLY.
+ *
+ * Contract:
+ *   - Bare family+digits ids (`REQ-001`, `ADR-005`) get the slug written
+ *     as prefix (prefix families) or suffix (suffix families).
+ *   - Ids that already carry a slug segment are accepted VERBATIM: the
+ *     blueprint author's declared contribution list is the truth for
+ *     what that blueprint owns. String grammar does not veto (`stampId`
+ *     used to refuse `ADR-201-spa-theme` under slug `spa` on the basis
+ *     that `spa-theme` != `spa`, which broke every blueprint whose
+ *     suffix-family ids carried a semantic tail after the slug).
+ *   - AC and TC pass through unchanged (no namespacing family).
+ *   - An id that matches no family pattern, or a slug that is not a
+ *     valid kebab, is refused.
+ *
+ * Cross-blueprint claims (`spa-theme-REQ-001` declared under blueprint
+ * `spa` where `spa-theme` is also applied) are caught by the manifest-
+ * record consulted at write time (`apply.js` overwrite guard +
+ * cross-claim detector). String parsing here is deliberately not a
+ * trust surface.
+ *
+ * @param {string} id - canonical id (either bare `REQ-001` or already
+ *                      namespaced `spa-REQ-001` / `ADR-201-spa-theme`)
+ * @param {string} slug - blueprint slug (must be well-formed kebab)
+ * @returns {{ id: string } | { error: string }}
+ */
+export function stampId(id, slug) {
+  if (!SLUG_PATTERN.test(slug)) {
+    return { error: `stampId: slug '${slug}' is not a valid kebab slug` };
+  }
+  const parts = parseIdParts(id);
+  if (!parts) return { error: `stampId: id '${id}' does not match any known family pattern` };
+  const style = namespaceStyleFor(id);
+  if (style === 'none') return { id };
+  if (style === 'prefix') {
+    if (parts.prefixSlug === null) return { id: `${slug}-${parts.family}-${parts.digits}` };
+    // Already carries a prefix segment. Trust the declaration -- see
+    // module doc block. Any resulting cross-claim will surface at the
+    // manifest-record check in apply.js, not here.
+    return { id };
+  }
+  // suffix
+  if (parts.suffixSlug === null) return { id: `${parts.family}-${parts.digits}-${slug}` };
+  // Already carries a suffix segment. Trust the declaration (same
+  // reasoning as the prefix branch above).
+  return { id };
+}
+
+/**
+ * GRAMMAR predicate: does the id's parsed slug segment equal `slug`?
+ *
+ * This is NOT an ownership check. Ownership of an applied contribution
+ * is answered by the manifest's appliedBlueprintRecord.contributions[]
+ * list (see `apply.js` overwrite guard and `remove.js` referring-doc
+ * scan). `isNamespacedFor` retains exact-slug grammar semantics for
+ * external consumers (docs generators, id-audit tooling) but must NOT
+ * be used to authorise a write or a delete -- for slug+tail ids like
+ * `ADR-201-spa-theme` the parsed suffix is `spa-theme`, which returns
+ * false for a legitimate `spa`-owned contribution whose author put a
+ * semantic tail after the slug. That misread is the exact reason the
+ * ownership call-sites were routed off this predicate.
+ *
+ * @param {string} id
+ * @param {string} slug
+ * @returns {boolean}
+ */
+export function isNamespacedFor(id, slug) {
+  const parts = parseIdParts(id);
+  if (!parts) return false;
+  const style = namespaceStyleFor(id);
+  if (style === 'prefix') return parts.prefixSlug === slug;
+  if (style === 'suffix') return parts.suffixSlug === slug;
+  return false;
+}
+
+export const _internal = {
+  PREFIX_FAMILIES: PREFIX_FAMILY_SET,
+  SUFFIX_FAMILIES: SUFFIX_FAMILY_SET,
+  UNNAMESPACED_FAMILIES: UNNAMESPACED_FAMILY_SET,
+  SLUG_PATTERN,
+};

package/src/blueprint/remove.js

@@ -0,0 +1,105 @@
+// Blueprint remove. Referring-doc scan + manifest patch + contribution
+// file unlink.
+//
+// Refuses when any project-authored doc references any of the removed
+// blueprint's contribution ids. `--force` is a Phase 3 concern (see
+// design brief §Verbs); Phase 1 declines the override and returns the
+// referring-doc list so the operator can see what needs unbinding.
+
+import { unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+import { updateManifest } from './manifest-writer.js';
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.slug
+ * @param {boolean} [args.dryRun]
+ * @returns {Promise<{
+ *   removed: boolean,
+ *   slug: string,
+ *   deletedPaths?: string[],
+ *   referringDocs?: Array<{ docId: string, matchedId: string }>
+ * } | import('../core/errors/index.js').RcfError>}
+ */
+export async function removeBlueprint({ projectRoot, tree, slug, dryRun = false }) {
+  const applied = tree.manifest?.blueprints ?? [];
+  const entry = applied.find((b) => b.slug === slug);
+  if (!entry) {
+    return rcfError({ kind: 'usage', message: `blueprint remove: no blueprint '${slug}' is applied on this project.` });
+  }
+  const contributionIds = new Set((entry.contributions ?? []).map((c) => c.id));
+  const referring = scanReferringDocs(tree, contributionIds, slug);
+  if (referring.length > 0) {
+    return { removed: false, slug, referringDocs: referring };
+  }
+  const deletedPaths = [];
+  for (const c of entry.contributions ?? []) {
+    if (dryRun) { deletedPaths.push(c.path); continue; }
+    try {
+      await unlink(join(projectRoot, c.path));
+      deletedPaths.push(c.path);
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        return rcfError({ kind: 'ioFailure', message: `blueprint remove: unlink failed for ${c.path}: ${err.message}`, filePath: c.path });
+      }
+    }
+  }
+  const result = await updateManifest({
+    projectRoot,
+    manifest: tree.manifest,
+    mutate: (next) => {
+      const list = Array.isArray(next.blueprints) ? next.blueprints : [];
+      next.blueprints = list.filter((b) => b.slug !== slug);
+      if (next.blueprints.length === 0) delete next.blueprints;
+    },
+    dryRun,
+  });
+  if (result.kind) return result;
+  return { removed: true, slug, deletedPaths };
+}
+
+/**
+ * Walk every non-blueprint doc's string-shaped fields (including nested
+ * arrays / objects) and report any occurrence of a contribution id.
+ * A referring-doc match INCLUDES the blueprint's own contributions when
+ * one contribution refers to another — we filter those out by checking
+ * the referring doc id itself against `contributionIds`.
+ */
+function scanReferringDocs(tree, contributionIds, slug) {
+  const hits = [];
+  const contributionPaths = new Set();
+  for (const entry of tree.manifest?.blueprints ?? []) {
+    if (entry.slug !== slug) continue;
+    for (const c of entry.contributions ?? []) contributionPaths.add(c.path);
+  }
+  for (const [id, doc] of tree.byId ?? new Map()) {
+    if (contributionIds.has(id)) continue; // the blueprint's own contributions cross-refer each other
+    for (const matchedId of findIdReferences(doc, contributionIds)) {
+      hits.push({ docId: id, matchedId });
+    }
+  }
+  return hits;
+}
+
+function findIdReferences(node, contributionIds, seen = new WeakSet()) {
+  const out = [];
+  if (typeof node === 'string') {
+    if (contributionIds.has(node)) out.push(node);
+    return out;
+  }
+  if (Array.isArray(node)) {
+    for (const item of node) out.push(...findIdReferences(item, contributionIds, seen));
+    return out;
+  }
+  if (typeof node === 'object' && node !== null && !seen.has(node)) {
+    seen.add(node);
+    for (const value of Object.values(node)) {
+      out.push(...findIdReferences(value, contributionIds, seen));
+    }
+  }
+  return out;
+}

package/src/blueprint/resolutions.js

@@ -0,0 +1,83 @@
+// Blueprint conflict-resolution helpers.
+//
+// A resolution record (schema $defs/blueprintConflictResolution, added
+// in @stravica-ai/rcf-schemas 0.4.5) captures an operator ruling that
+// resolves a globalAdrTopic conflict: two applied blueprints each
+// contributing a scope:global ADR on the same topic, resolved by a
+// project-level ADR that supersedes both.
+//
+// This module owns:
+//   - `nextResolutionId(manifest, now)`: monotonic `res-YYYY-MM-DD-NNN`
+//     id-mint, mirroring the pattern used for pfc / boo / ic / rc ids
+//     elsewhere in the tree.
+//   - `matchingResolution(manifest, { topic, incoming, existing })`: the
+//     lookup the conflict detector calls to see whether a would-be
+//     globalAdrTopic conflict has already been resolved. Match rule:
+//     kind = globalAdrTopic, topic matches, AND supersedes[] lists both
+//     the incoming and the existing { slug, adrId } pairs. Superset OK
+//     (a resolution recorded for three blueprints on the same topic still
+//     resolves the two-blueprint conflict in front of us); subset not (a
+//     resolution that only lists one of the two would leave the other's
+//     ADR unaccounted for).
+//
+// Pure functions. No I/O, no wall clock beyond the `now` a caller hands
+// in.
+
+/**
+ * Compute the next resolution id for today: monotonic
+ * `res-YYYY-MM-DD-NNN`. Reads `manifest.resolutions[]` for the highest
+ * NNN under today's date prefix and returns that + 1, zero-padded.
+ *
+ * @param {object|null} manifest
+ * @param {Date} now
+ * @returns {string}
+ */
+export function nextResolutionId(manifest, now) {
+  const y = now.getUTCFullYear().toString().padStart(4, '0');
+  const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = now.getUTCDate().toString().padStart(2, '0');
+  const prefix = `res-${y}-${m}-${d}-`;
+  const existing = Array.isArray(manifest?.resolutions) ? manifest.resolutions : [];
+  let maxN = 0;
+  for (const rec of existing) {
+    if (typeof rec?.id !== 'string' || !rec.id.startsWith(prefix)) continue;
+    const n = Number.parseInt(rec.id.slice(prefix.length), 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return `${prefix}${(maxN + 1).toString().padStart(3, '0')}`;
+}
+
+/**
+ * Find a resolution on the manifest that resolves a specific
+ * globalAdrTopic conflict pair. Returns the resolution record if a
+ * match exists, `null` otherwise.
+ *
+ * A match requires:
+ *   - `kind === 'globalAdrTopic'` on the resolution
+ *   - `topic` matches
+ *   - `supersedes[]` contains an entry matching the incoming
+ *     `{ slug, adrId }` AND an entry matching the existing
+ *     `{ slug, adrId }`
+ *
+ * The `adrId` comparison is exact. The `slug` comparison is exact. A
+ * resolution that lists a superset of blueprints on the same topic still
+ * resolves the pair-conflict in front of us (blueprint 3 landing later
+ * on the same topic just needs to be listed too, which is a fresh
+ * resolution write, not a re-resolve).
+ *
+ * @param {object|null} manifest
+ * @param {{ topic: string, incoming: { slug: string, adrId: string }, existing: { slug: string, adrId: string } }} conflict
+ * @returns {object|null}
+ */
+export function matchingResolution(manifest, { topic, incoming, existing }) {
+  const list = Array.isArray(manifest?.resolutions) ? manifest.resolutions : [];
+  for (const rec of list) {
+    if (rec?.kind !== 'globalAdrTopic') continue;
+    if (rec.topic !== topic) continue;
+    const supers = Array.isArray(rec.supersedes) ? rec.supersedes : [];
+    const hasIncoming = supers.some((s) => s?.slug === incoming.slug && s?.adrId === incoming.adrId);
+    const hasExisting = supers.some((s) => s?.slug === existing.slug && s?.adrId === existing.adrId);
+    if (hasIncoming && hasExisting) return rec;
+  }
+  return null;
+}

package/src/blueprint/standards.js

@@ -0,0 +1,148 @@
+// Standards-pack registration. Reference-by-default when the source
+// lives inside the project root; copy into rcf/standards/<slug>/ only
+// when the source lives outside.
+//
+// Manifest registration is authoritative (design-brief.md v2 §Corporate
+// standards and personal patterns).
+
+import { cp, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+import { updateManifest } from './manifest-writer.js';
+
+const SLUG_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.sourcePath - the standards folder path (absolute or repo-relative)
+ * @param {string} args.slug
+ * @param {string[]} args.tags
+ * @param {'standard' | 'agent' | 'none'} args.testsProvidedBy
+ * @param {'personal' | 'corporate'} args.provenance
+ * @param {string} [args.summary]
+ * @param {boolean} [args.dryRun]
+ * @returns {Promise<{
+ *   registered: boolean,
+ *   entry: object,
+ *   copied: boolean,
+ *   copyPath?: string,
+ *   alreadyRegistered?: boolean
+ * } | import('../core/errors/index.js').RcfError>}
+ */
+export async function registerStandardsPack({
+  projectRoot, tree, sourcePath, slug, tags, testsProvidedBy, provenance, summary, dryRun = false,
+}) {
+  if (!SLUG_PATTERN.test(slug)) {
+    return rcfError({ kind: 'usage', message: `standards add: slug '${slug}' is not a valid kebab slug` });
+  }
+  if (!['standard', 'agent', 'none'].includes(testsProvidedBy)) {
+    return rcfError({ kind: 'usage', message: `standards add: testsProvidedBy must be one of standard|agent|none` });
+  }
+  if (!['personal', 'corporate'].includes(provenance)) {
+    return rcfError({ kind: 'usage', message: `standards add: provenance must be one of personal|corporate` });
+  }
+  if (!Array.isArray(tags) || tags.length === 0) {
+    return rcfError({ kind: 'usage', message: `standards add: at least one tag is required` });
+  }
+
+  const abs = resolve(sourcePath);
+  try { await stat(abs); }
+  catch (err) {
+    return rcfError({ kind: 'missingFile', message: `standards add: source path does not exist: ${abs}`, filePath: abs });
+  }
+
+  const projectAbs = resolve(projectRoot);
+  const rel = relative(projectAbs, abs);
+  const isInsideRoot = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+
+  let entry;
+  let copied = false;
+  let copyPath;
+  if (isInsideRoot) {
+    entry = {
+      id: `std-${slug}`,
+      slug,
+      sourcePath: rel.split('\\').join('/'),
+      tags,
+      ...(summary ? { summary } : {}),
+      testsProvidedBy,
+      provenance,
+    };
+  } else {
+    copyPath = `rcf/standards/${slug}`;
+    const absCopy = join(projectRoot, copyPath);
+    if (!dryRun) {
+      try {
+        await cp(abs, absCopy, { recursive: true, force: true });
+        copied = true;
+      } catch (err) {
+        return rcfError({ kind: 'ioFailure', message: `standards add: copy failed: ${err.message}`, filePath: absCopy });
+      }
+    } else {
+      copied = true; // reported to caller so dry-run output is coherent
+    }
+    entry = {
+      id: `std-${slug}`,
+      slug,
+      sourcePath: abs,
+      copyPath,
+      tags,
+      ...(summary ? { summary } : {}),
+      testsProvidedBy,
+      provenance,
+    };
+  }
+
+  const existing = (tree.manifest?.standards ?? []).find((s) => s.slug === slug);
+  const alreadyRegistered = existing && JSON.stringify(existing) === JSON.stringify(entry);
+  if (alreadyRegistered) {
+    // Short-circuit before rewriting the manifest -- mirrors
+    // applyBlueprint's `alreadyApplied` fast-path (apply.js). Re-writing
+    // the same bytes churns the manifest's mtime and forces every
+    // consumer that watches it to re-load, so a truly idempotent call
+    // stays a no-op end-to-end.
+    return {
+      registered: false,
+      alreadyRegistered: true,
+      entry,
+      copied,
+      ...(copyPath ? { copyPath } : {}),
+    };
+  }
+  const manifestResult = await updateManifest({
+    projectRoot,
+    manifest: tree.manifest,
+    mutate: (next) => {
+      const list = Array.isArray(next.standards) ? next.standards : [];
+      const filtered = list.filter((s) => s.slug !== slug);
+      filtered.push(entry);
+      next.standards = filtered;
+    },
+    dryRun,
+  });
+  if (manifestResult.kind) return manifestResult;
+
+  return {
+    registered: true,
+    alreadyRegistered: false,
+    entry,
+    copied,
+    ...(copyPath ? { copyPath } : {}),
+  };
+}
+
+/**
+ * @param {import('#core/store/walker.js').TreeModel} tree
+ * @returns {object[]}
+ */
+export function listStandards(tree) {
+  const list = tree.manifest?.standards ?? [];
+  return [...list];
+}
+
+function isAbsolute(p) {
+  return p.startsWith('/') || /^[A-Za-z]:/.test(p);
+}