cap-pro 1.0.0

package/cap/bin/lib/cap-anchor.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+// @cap-feature(feature:F-047, primary:true) Unified Feature Anchor Block parser.
+// Parses the new single-block syntax introduced by CAP v3:
+//
+//   /* @cap feature:F-001 acs:[AC-1,AC-3] role:primary */
+//   # @cap feature:F-001 acs:[AC-1,AC-3] role:primary
+//   <!-- @cap feature:F-001 acs:[AC-1,AC-3] role:primary -->
+//
+// The parser is language-agnostic — it is called by cap-tag-scanner AFTER comment
+// delimiter stripping, so this module only sees the inner `@cap key:value ...` content.
+//
+// @cap-decision Pure logic, zero side effects. Scanner owns the "is this a comment?" layer
+// (F-046 polylingual detection) and feeds stripped lines into parseAnchorLine(). This keeps
+// the scanner single-source-of-truth for comment detection and avoids duplicating the
+// polyglot rules here.
+// @cap-decision expandAnchorToTags() emits tags in the SAME shape as scanner.extractTags()
+// so all downstream code (buildAcFileMap, cap-deps, cap-completeness, cap-reconcile) works
+// unchanged. Legacy fragmented tags and unified anchors are indistinguishable at the tag
+// consumer layer — only the scanner layer sees the new syntax.
+
+// @cap-risk Regex-based. Does not parse nested brackets or quoted key:value pairs.
+// Limitations:
+//   - values with `[`, `]`, `,`, or whitespace must not appear unquoted (documented)
+//   - no support for multi-line anchor bodies (block must be single line inside its comment)
+//   - scanAnchorsInContent() reads raw file content, so a string literal containing
+//     `@cap feature:F-XXX` in source (e.g. inside a test fixture) can produce a false
+//     match. Callers needing strict string-literal awareness should wire in F-046's
+//     polyglot string-stripping upstream. KV_TOKEN_RE rejects most accidental text.
+// These are intentional for v1 to keep parsing unambiguous.
+
+// @cap-decision Space discriminator is load-bearing: `@cap ` (with trailing space) is the
+// unified anchor marker, `@cap-` (with hyphen) is the legacy tag family. The two formats
+// never collide because no legal tag name contains whitespace, and no legal anchor lacks
+// the space between `@cap` and the first key. Documented in docs/F-047-decision.md.
+
+// Matches `@cap <rest>` — called on an already-decommented line or the inner content of a
+// block comment. Captures `rest` which is then tokenised into key:value pairs.
+const ANCHOR_RE = /@cap\s+([^\n]+)/;
+
+// Matches `key:value` where value is either `[list,of,items]` or a bare token (no whitespace,
+// no commas, no brackets). The anchor body is split into key:value pairs by whitespace.
+const KV_TOKEN_RE = /^([a-zA-Z][a-zA-Z0-9_]*)\s*:\s*(\[[^\]]*\]|[^\s\[\]]+)$/;
+
+/**
+ * @typedef {Object} ParsedAnchor
+ * @property {string} feature - Feature ID (e.g. 'F-001'); required
+ * @property {string[]} acs    - AC IDs (e.g. ['AC-1','AC-3']); empty when not specified
+ * @property {('primary'|'secondary'|null)} role - 'primary', 'secondary', or null (unspecified)
+ * @property {string} raw      - The original `@cap …` text for error reporting
+ * @property {string[]} warnings - Soft warnings (unknown keys, malformed AC ids, …)
+ */
+
+/**
+ * Parse a single `@cap key:value …` body (the content inside the comment, already
+ * stripped of delimiters like `/*`, `*` /, `#`, `<!--`, `-->`).
+ *
+ * Returns null when no `@cap` token is present or the line is completely malformed.
+ * When the token is present but some keys are unrecognised or values are malformed,
+ * still returns a ParsedAnchor with the recognised subset plus a `warnings` array so
+ * callers can surface soft failures without losing usable information.
+ *
+ * @param {string} line
+ * @returns {ParsedAnchor|null}
+ */
+function parseAnchorLine(line) {
+  if (typeof line !== 'string') return null;
+  const m = line.match(ANCHOR_RE);
+  if (!m) return null;
+
+  const body = m[1].trim();
+  // Strip trailing comment delimiters that may have leaked through (e.g. `-->` or `*/`)
+  const cleaned = body
+    .replace(/\s*-->\s*$/, '')
+    .replace(/\s*\*\/\s*$/, '')
+    .trim();
+
+  /** @type {ParsedAnchor} */
+  const out = { feature: '', acs: [], role: null, raw: m[0], warnings: [] };
+  if (cleaned.length === 0) {
+    out.warnings.push('empty anchor body');
+    return out;
+  }
+
+  // Tokenise by whitespace; each token must match key:value.
+  const tokens = cleaned.split(/\s+/);
+  for (const tok of tokens) {
+    const km = tok.match(KV_TOKEN_RE);
+    if (!km) {
+      out.warnings.push(`unparseable token: ${tok}`);
+      continue;
+    }
+    const key = km[1];
+    const value = km[2];
+    switch (key) {
+      case 'feature':
+        if (!/^F-\d{3,}$/.test(value)) {
+          out.warnings.push(`feature value must match /^F-\\d{3,}$/ (got ${value})`);
+        }
+        out.feature = value;
+        break;
+      case 'acs': {
+        if (!value.startsWith('[') || !value.endsWith(']')) {
+          out.warnings.push(`acs must be [bracketed,list] (got ${value})`);
+          break;
+        }
+        const inner = value.slice(1, -1).trim();
+        const items = inner.length === 0 ? [] : inner.split(',').map((s) => s.trim()).filter(Boolean);
+        for (const ac of items) {
+          if (!/^AC-\d+$/.test(ac)) {
+            out.warnings.push(`acs item must match /^AC-\\d+$/ (got ${ac})`);
+          }
+        }
+        out.acs = items;
+        break;
+      }
+      case 'role':
+        if (value !== 'primary' && value !== 'secondary') {
+          out.warnings.push(`role must be 'primary' or 'secondary' (got ${value})`);
+        }
+        out.role = value;
+        break;
+      default:
+        out.warnings.push(`unknown key: ${key}`);
+        break;
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Expand a parsed anchor into the CapTag[] shape used elsewhere in CAP.
+ * Emits:
+ *   - one @cap-feature tag (primary:true flag when role === 'primary')
+ *   - one @cap-todo tag per AC listed in `anchor.acs`, with `ac: F-XXX/AC-N`
+ *
+ * When anchor.feature is empty (parse error), returns [] — the caller can still
+ * inspect anchor.warnings for diagnostics.
+ *
+ * @param {ParsedAnchor} anchor
+ * @param {string} filePath - Relative file path (for tag.file)
+ * @param {number} lineNumber - 1-based line number of the anchor in the source
+ * @returns {CapTag[]}
+ */
+function expandAnchorToTags(anchor, filePath, lineNumber) {
+  if (!anchor || !anchor.feature) return [];
+  /** @type {CapTag[]} */
+  const tags = [];
+  const metadata = { feature: anchor.feature };
+  if (anchor.role === 'primary') metadata.primary = true;
+  tags.push({
+    type: 'feature',
+    file: filePath,
+    line: lineNumber,
+    metadata,
+    description: `unified anchor for ${anchor.feature}`,
+    raw: anchor.raw,
+  });
+  for (const ac of anchor.acs || []) {
+    tags.push({
+      type: 'todo',
+      file: filePath,
+      line: lineNumber,
+      metadata: { ac: `${anchor.feature}/${ac}` },
+      description: `AC reference expanded from unified anchor`,
+      raw: anchor.raw,
+    });
+  }
+  return tags;
+}
+
+/**
+ * Serialize a structured anchor into the canonical block string, using the
+ * requested comment style. Used by the migration tool to write the unified
+ * block back to source.
+ *
+ * @param {{feature:string, acs?:string[], role?:string}} anchor
+ * @param {('block'|'line'|'html')} [style='block'] - comment family
+ * @returns {string} Single-line block, no trailing newline
+ */
+function emitAnchorBlock(anchor, style = 'block') {
+  const parts = [];
+  parts.push(`feature:${anchor.feature}`);
+  if (Array.isArray(anchor.acs) && anchor.acs.length > 0) {
+    parts.push(`acs:[${anchor.acs.join(',')}]`);
+  }
+  if (anchor.role === 'primary' || anchor.role === 'secondary') {
+    parts.push(`role:${anchor.role}`);
+  }
+  const body = `@cap ${parts.join(' ')}`;
+  if (style === 'line') return `# ${body}`;
+  if (style === 'html') return `<!-- ${body} -->`;
+  // default: block comment
+  return `/* ${body} */`;
+}
+
+/**
+ * Convenience: scan a full file content for unified anchor blocks and expand each.
+ * Internal use by cap-tag-scanner when unifiedAnchors.enabled is true.
+ *
+ * @param {string} content - Full file content
+ * @param {string} filePath - Relative path for tag.file
+ * @returns {CapTag[]} All tags expanded from every anchor in the file
+ */
+function scanAnchorsInContent(content, filePath) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+  const tags = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes('@cap ')) continue; // fast-path filter; space distinguishes from `@cap-feature`
+    const parsed = parseAnchorLine(line);
+    if (!parsed || !parsed.feature) continue;
+    tags.push(...expandAnchorToTags(parsed, filePath, i + 1));
+  }
+  return tags;
+}
+
+module.exports = {
+  parseAnchorLine,
+  expandAnchorToTags,
+  emitAnchorBlock,
+  scanAnchorsInContent,
+  // constants (exported for tests)
+  ANCHOR_RE,
+  KV_TOKEN_RE,
+};

package/cap/bin/lib/cap-annotation-writer.cjs

@@ -0,0 +1,340 @@
+// @cap-feature(feature:F-028) Code Annotation Writer — write @cap-history, @cap-pitfall, @cap-pattern annotations into source files
+// @cap-decision Annotations placed at file-top block, after shebang/'use strict', alongside existing @cap-feature tags.
+// @cap-decision Comment syntax detected per file extension — language-agnostic, same approach as tag scanner.
+// @cap-constraint Zero external dependencies — uses only Node.js built-ins.
+
+'use strict';
+
+// @cap-history(sessions:2, edits:7, since:2026-04-03, learned:2026-04-03) Frequently modified — 2 sessions, 7 edits
+const fs = require('node:fs');
+const path = require('node:path');
+
+// --- Comment Syntax Detection (AC-2) ---
+
+/** @type {Object<string, string>} Extension to single-line comment prefix mapping */
+const COMMENT_PREFIX_MAP = {
+  // // style
+  '.js': '//', '.cjs': '//', '.mjs': '//', '.ts': '//', '.tsx': '//', '.jsx': '//',
+  '.go': '//', '.rs': '//', '.c': '//', '.cpp': '//', '.h': '//', '.java': '//',
+  '.swift': '//', '.kt': '//', '.scala': '//', '.cs': '//', '.dart': '//', '.zig': '//',
+  // # style
+  '.py': '#', '.rb': '#', '.sh': '#', '.bash': '#', '.zsh': '#', '.fish': '#',
+  '.yml': '#', '.yaml': '#', '.toml': '#', '.pl': '#', '.pm': '#', '.r': '#',
+  '.tf': '#', '.hcl': '#', '.dockerfile': '#', '.conf': '#', '.ini': '#',
+  // -- style
+  '.sql': '--', '.lua': '--', '.hs': '--', '.elm': '--',
+  // ; style
+  '.lisp': ';', '.clj': ';', '.el': ';', '.scm': ';',
+  // % style
+  '.erl': '%', '.tex': '%', '.m': '%',
+};
+
+// @cap-todo(ref:F-028:AC-2) Detect correct comment syntax for target file based on extension
+
+/** File extensions that must never receive annotations (no valid comment syntax or structured format). */
+const ANNOTATION_BLOCKLIST = new Set([
+  '.md', '.markdown', '.json', '.jsonl', '.lock', '.svg', '.xml', '.html', '.htm',
+  '.css', '.scss', '.less', '.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2',
+  '.ttf', '.eot', '.map', '.min.js', '.min.css', '.patch', '.diff',
+]);
+
+/**
+ * Check if a file can receive annotations.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function canAnnotate(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const basename = path.basename(filePath).toLowerCase();
+  if (ANNOTATION_BLOCKLIST.has(ext)) return false;
+  if (basename === 'package-lock.json' || basename === 'yarn.lock' || basename === 'pnpm-lock.yaml') return false;
+  if (basename.endsWith('.md')) return false;
+  return true;
+}
+
+/**
+ * Get the single-line comment prefix for a file.
+ * @param {string} filePath
+ * @returns {string} Comment prefix (defaults to '//')
+ */
+function getCommentPrefix(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  // Dockerfile has no extension but starts with FROM
+  if (path.basename(filePath).toLowerCase() === 'dockerfile') return '#';
+  return COMMENT_PREFIX_MAP[ext] || '//';
+}
+
+// --- Annotation Parsing ---
+
+/** Regex to match existing memory annotations in a line */
+const MEMORY_TAG_RE = /^(\s*(?:\/\/|#|--|;|%)\s*)@(cap-history|cap-pitfall|cap-pattern|cap-decision)\b/;
+
+/**
+ * @typedef {Object} ParsedAnnotation
+ * @property {number} lineIndex - 0-based line index in file
+ * @property {string} tag - Tag name (e.g., 'cap-history')
+ * @property {string} fullLine - Complete line text
+ * @property {string} prefix - Comment prefix with whitespace
+ */
+
+/**
+ * Parse existing memory annotations from file lines.
+ * @param {string[]} lines
+ * @returns {ParsedAnnotation[]}
+ */
+function parseExistingAnnotations(lines) {
+  const annotations = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(MEMORY_TAG_RE);
+    if (match) {
+      annotations.push({
+        lineIndex: i,
+        tag: match[2],
+        fullLine: lines[i],
+        prefix: match[1],
+      });
+    }
+  }
+  return annotations;
+}
+
+// --- Insertion Point Detection ---
+
+// @cap-todo(ref:F-028:AC-1) Insert annotations at file-top block alongside existing @cap-feature tags
+
+/**
+ * Find the line index where memory annotations should be inserted.
+ * After shebang, 'use strict', and existing @cap-* annotation block.
+ * @param {string[]} lines
+ * @returns {number} Line index for insertion
+ */
+function findInsertionPoint(lines) {
+  let insertAt = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // Skip shebang
+    if (i === 0 && line.startsWith('#!')) {
+      insertAt = i + 1;
+      continue;
+    }
+
+    // Skip 'use strict'
+    if (line === "'use strict';" || line === '"use strict";') {
+      insertAt = i + 1;
+      continue;
+    }
+
+    // Skip empty lines at top
+    if (line === '' && i <= insertAt) {
+      insertAt = i + 1;
+      continue;
+    }
+
+    // Skip existing @cap-* annotation lines
+    if (/^\s*(?:\/\/|#|--|;|%)\s*@cap-/.test(line)) {
+      insertAt = i + 1;
+      continue;
+    }
+
+    // Stop at first non-annotation, non-header line
+    break;
+  }
+
+  return insertAt;
+}
+
+// --- Write Operations ---
+
+// @cap-todo(ref:F-028:AC-3) Update existing annotations in-place without creating duplicates
+// @cap-todo(ref:F-028:AC-4) Remove annotations marked as stale
+// @cap-todo(ref:F-028:AC-7) Support dry-run mode
+
+/**
+ * @typedef {Object} AnnotationChange
+ * @property {'add'|'update'|'remove'} action
+ * @property {string} file
+ * @property {string} annotation - Formatted annotation text
+ * @property {number} [lineIndex] - For update/remove: existing line
+ */
+
+/**
+ * Plan annotation changes for a single file.
+ * @param {string} filePath
+ * @param {string} fileContent - Current file content
+ * @param {import('./cap-memory-engine.cjs').MemoryEntry[]} entries - New entries for this file
+ * @param {string[]} [staleContentPrefixes] - Content prefixes of stale entries to remove
+ * @returns {AnnotationChange[]}
+ */
+function planFileChanges(filePath, fileContent, entries, staleContentPrefixes = []) {
+  const commentPrefix = getCommentPrefix(filePath);
+  const lines = fileContent.split('\n');
+  const existing = parseExistingAnnotations(lines);
+  const changes = [];
+
+  const { formatAnnotation } = require('./cap-memory-engine.cjs');
+
+  // Plan removals for stale entries (AC-4)
+  for (const ann of existing) {
+    const lineContent = ann.fullLine.replace(ann.prefix, '').trim();
+    if (staleContentPrefixes.some(prefix => lineContent.startsWith(prefix))) {
+      changes.push({ action: 'remove', file: filePath, annotation: ann.fullLine, lineIndex: ann.lineIndex });
+    }
+  }
+
+  // Plan adds/updates for new entries
+  for (const entry of entries) {
+    const formatted = formatAnnotation(entry);
+    // @cap-todo(ac:F-086/AC-1) Dedup matcher: aggregate annotations (one-per-file) like
+    //   @cap-history must match by TAG NAME alone, since their content carries live edit
+    //   counts that change between runs. Matching by content-prefix caused a duplicate
+    //   line every time the stats changed (observed on GoetzeInvest hub-types.ts).
+    //   Per-occurrence annotations (@cap-pitfall, @cap-pattern, @cap-decision) keep the
+    //   content-prefix match because multiple distinct ones can legitimately coexist.
+    const tagName = formatted.split('(')[0].split(' ')[0]; // e.g., @cap-history
+    const contentKey = entry.content.substring(0, 60).toLowerCase();
+    const isAggregateTag = tagName === '@cap-history';
+
+    const existingMatch = existing.find(ann => {
+      const annContent = ann.fullLine.replace(ann.prefix, '').trim();
+      if (!annContent.startsWith(tagName)) return false;
+      if (isAggregateTag) return true; // any existing @cap-history on this file is "the" one
+      return annContent.toLowerCase().includes(contentKey);
+    });
+
+    if (existingMatch) {
+      // Update in-place (AC-3)
+      const newLine = `${commentPrefix} ${formatted}`;
+      if (existingMatch.fullLine.trim() !== newLine.trim()) {
+        changes.push({ action: 'update', file: filePath, annotation: newLine, lineIndex: existingMatch.lineIndex });
+      }
+    } else {
+      // Add new
+      changes.push({ action: 'add', file: filePath, annotation: `${commentPrefix} ${formatted}` });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Apply planned changes to a file's content.
+ * @param {string} fileContent
+ * @param {AnnotationChange[]} changes
+ * @returns {string} Updated file content
+ */
+function applyChanges(fileContent, changes) {
+  const lines = fileContent.split('\n');
+
+  // Apply removals and updates (by line index, process from bottom to preserve indices)
+  const lineChanges = changes
+    .filter(c => c.action === 'remove' || c.action === 'update')
+    .sort((a, b) => b.lineIndex - a.lineIndex);
+
+  for (const change of lineChanges) {
+    if (change.action === 'remove') {
+      lines.splice(change.lineIndex, 1);
+    } else if (change.action === 'update') {
+      lines[change.lineIndex] = change.annotation;
+    }
+  }
+
+  // Apply additions at insertion point
+  const additions = changes.filter(c => c.action === 'add');
+  if (additions.length > 0) {
+    const insertAt = findInsertionPoint(lines);
+    const newLines = additions.map(a => a.annotation);
+    lines.splice(insertAt, 0, ...newLines);
+  }
+
+  return lines.join('\n');
+}
+
+// @cap-todo(ref:F-028:AC-5) Format annotations with parenthesized metadata matching existing tag conventions
+// @cap-todo(ref:F-028:AC-6) Be parseable by existing tag scanner without modifications
+
+/**
+ * Write memory annotations to files.
+ * @param {Object<string, import('./cap-memory-engine.cjs').MemoryEntry[]>} fileEntries - Map of filePath -> entries
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun] - If true, return changes without writing
+ * @param {Object<string, string[]>} [options.staleByFile] - Map of filePath -> stale content prefixes to remove
+ * @returns {{changes: AnnotationChange[], filesModified: number}}
+ */
+function writeAnnotations(fileEntries, options = {}) {
+  const allChanges = [];
+  let filesModified = 0;
+
+  for (const [filePath, entries] of Object.entries(fileEntries)) {
+    if (!fs.existsSync(filePath)) continue;
+    if (!canAnnotate(filePath)) continue;
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const stale = options.staleByFile?.[filePath] || [];
+    const changes = planFileChanges(filePath, content, entries, stale);
+
+    if (changes.length === 0) continue;
+
+    allChanges.push(...changes);
+
+    if (!options.dryRun) {
+      const updated = applyChanges(content, changes);
+      fs.writeFileSync(filePath, updated, 'utf8');
+    }
+    filesModified++;
+  }
+
+  return { changes: allChanges, filesModified };
+}
+
+/**
+ * Remove stale annotations from files.
+ * @param {Array<{file: string, content: string}>} staleEntries
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun]
+ * @returns {{removed: number, filesModified: number}}
+ */
+function removeStaleAnnotations(staleEntries, options = {}) {
+  const byFile = {};
+  for (const entry of staleEntries) {
+    if (!byFile[entry.file]) byFile[entry.file] = [];
+    byFile[entry.file].push(entry.content.substring(0, 60));
+  }
+
+  let removed = 0;
+  let filesModified = 0;
+
+  for (const [filePath, prefixes] of Object.entries(byFile)) {
+    if (!fs.existsSync(filePath)) continue;
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const changes = planFileChanges(filePath, content, [], prefixes);
+    const removals = changes.filter(c => c.action === 'remove');
+
+    if (removals.length === 0) continue;
+
+    if (!options.dryRun) {
+      const updated = applyChanges(content, removals);
+      fs.writeFileSync(filePath, updated, 'utf8');
+    }
+    removed += removals.length;
+    filesModified++;
+  }
+
+  return { removed, filesModified };
+}
+
+module.exports = {
+  canAnnotate,
+  getCommentPrefix,
+  parseExistingAnnotations,
+  findInsertionPoint,
+  planFileChanges,
+  applyChanges,
+  writeAnnotations,
+  removeStaleAnnotations,
+  COMMENT_PREFIX_MAP,
+  ANNOTATION_BLOCKLIST,
+  MEMORY_TAG_RE,
+};