@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/frontmatter.cjs

@@ -0,0 +1,494 @@
+"use strict";
+/**
+ * Frontmatter — YAML frontmatter parsing, serialization, and CRUD commands
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/frontmatter.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output, error } = ioMod;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Parsing engine ───────────────────────────────────────────────────────────
+/**
+ * Split a YAML inline array body on commas, respecting quoted strings.
+ * e.g. '"a, b", c' → ['a, b', 'c']
+ */
+function splitInlineArray(body) {
+    const items = [];
+    let current = '';
+    let inQuote = null;
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (inQuote) {
+            if (ch === inQuote) {
+                inQuote = null;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            inQuote = ch;
+        }
+        else if (ch === ',') {
+            const trimmed = current.trim();
+            if (trimmed)
+                items.push(trimmed);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    const trimmed = current.trim();
+    if (trimmed)
+        items.push(trimmed);
+    return items;
+}
+function extractFrontmatter(content) {
+    const frontmatter = {};
+    // Match frontmatter only at byte 0 — a `---` block later in the document
+    // body (YAML examples, horizontal rules) must never be treated as frontmatter.
+    const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+    if (!match)
+        return frontmatter;
+    const yaml = match[1];
+    const lines = yaml.split(/\r?\n/);
+    const stack = [{ obj: frontmatter, key: null, indent: -1 }];
+    for (const line of lines) {
+        // Skip empty lines
+        if (line.trim() === '')
+            continue;
+        // Calculate indentation (number of leading spaces)
+        const indentMatch = line.match(/^(\s*)/);
+        const indent = indentMatch ? indentMatch[1].length : 0;
+        // Pop stack back to appropriate level
+        while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+            stack.pop();
+        }
+        const current = stack[stack.length - 1];
+        // Check for key: value pattern
+        const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
+        if (keyMatch) {
+            const key = keyMatch[2];
+            const value = keyMatch[3].trim();
+            if (value === '' || value === '[') {
+                // Key with no value or opening bracket — could be nested object or array
+                const newObj = value === '[' ? [] : {};
+                current.obj[key] = newObj;
+                current.key = null;
+                // Push new context for potential nested content
+                stack.push({ obj: newObj, key: null, indent });
+            }
+            else if (value.startsWith('[') && value.endsWith(']')) {
+                // Inline array: key: [a, b, c] — quote-aware split (REG-04 fix)
+                current.obj[key] = splitInlineArray(value.slice(1, -1));
+                current.key = null;
+            }
+            else {
+                // Simple key: value
+                current.obj[key] = value.replace(/^["']|["']$/g, '');
+                current.key = null;
+            }
+        }
+        else if (line.trim().startsWith('- ')) {
+            // Array item
+            const itemValue = line.trim().slice(2).replace(/^["']|["']$/g, '');
+            // If current context is an empty object, convert to array
+            if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
+                // Find the key in parent that points to this object and convert it
+                const parent = stack.length > 1 ? stack[stack.length - 2] : null;
+                if (parent) {
+                    for (const k of Object.keys(parent.obj)) {
+                        if (parent.obj[k] === current.obj) {
+                            parent.obj[k] = [itemValue];
+                            current.obj = parent.obj[k];
+                            break;
+                        }
+                    }
+                }
+            }
+            else if (Array.isArray(current.obj)) {
+                current.obj.push(itemValue);
+            }
+        }
+    }
+    return frontmatter;
+}
+function reconstructFrontmatter(obj) {
+    const lines = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                lines.push(`${key}: []`);
+            }
+            else if (value.every(v => typeof v === 'string') && value.length <= 3 && (value).join(', ').length < 60) {
+                lines.push(`${key}: [${(value).join(', ')}]`);
+            }
+            else {
+                lines.push(`${key}:`);
+                for (const item of value) {
+                    lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+                }
+            }
+        }
+        else if (typeof value === 'object') {
+            lines.push(`${key}:`);
+            for (const [subkey, subval] of Object.entries(value)) {
+                if (subval === null || subval === undefined)
+                    continue;
+                if (Array.isArray(subval)) {
+                    if (subval.length === 0) {
+                        lines.push(`  ${subkey}: []`);
+                    }
+                    else if (subval.every((v) => typeof v === 'string') && subval.length <= 3 && (subval).join(', ').length < 60) {
+                        lines.push(`  ${subkey}: [${(subval).join(', ')}]`);
+                    }
+                    else {
+                        lines.push(`  ${subkey}:`);
+                        for (const item of subval) {
+                            lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+                        }
+                    }
+                }
+                else if (typeof subval === 'object') {
+                    lines.push(`  ${subkey}:`);
+                    for (const [subsubkey, subsubval] of Object.entries(subval)) {
+                        if (subsubval === null || subsubval === undefined)
+                            continue;
+                        if (Array.isArray(subsubval)) {
+                            if (subsubval.length === 0) {
+                                lines.push(`    ${subsubkey}: []`);
+                            }
+                            else {
+                                lines.push(`    ${subsubkey}:`);
+                                for (const item of subsubval) {
+                                    lines.push(`      - ${item}`);
+                                }
+                            }
+                        }
+                        else {
+                            // eslint-disable-next-line @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions
+                            lines.push(`    ${subsubkey}: ${subsubval}`);
+                        }
+                    }
+                }
+                else {
+                    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                    const sv = String(subval);
+                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') ? `"${sv}"` : sv}`);
+                }
+            }
+        }
+        else {
+            const sv = String(value);
+            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
+                lines.push(`${key}: "${sv}"`);
+            }
+            else {
+                lines.push(`${key}: ${sv}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function spliceFrontmatter(content, newObj) {
+    const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
+    if (match) {
+        // Identity-preservation (additive, lossless round-trip): `reconstructFrontmatter` is a
+        // deliberately lossy serializer — it cannot faithfully re-emit nested object-list items
+        // (e.g. must_haves.artifacts / must_haves.prohibitions, whose items are `{ path, provides }`
+        // / `{ statement, status, … }` maps). When the caller is writing back a value that is
+        // STRUCTURALLY UNCHANGED from the original parse (the canonical CRUD round-trip and the
+        // #644 prohibition schema round-trip both do this), regenerating from the lossy object would
+        // silently mangle those blocks. Detect that case by deep-equality against a re-parse of the
+        // original frontmatter and preserve the ORIGINAL raw text verbatim — a true no-op splice.
+        // This touches neither the parser (`extractFrontmatter`) nor `parseMustHavesBlock`; it only
+        // makes the existing splice faithful when nothing changed. A genuine mutation (different
+        // object) still flows through `reconstructFrontmatter` exactly as before.
+        try {
+            if (frontmatterDeepEqual(extractFrontmatter(content), newObj)) {
+                return content;
+            }
+        }
+        catch {
+            /* fall through to regeneration on any comparison hiccup */
+        }
+        const yamlStr = reconstructFrontmatter(newObj);
+        return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+    }
+    const yamlStr = reconstructFrontmatter(newObj);
+    return `---\n${yamlStr}\n---\n\n` + content;
+}
+/**
+ * Structural deep-equality for two parsed frontmatter objects. Order-sensitive for arrays
+ * (YAML lists are ordered), key-order-insensitive for objects. Used only by `spliceFrontmatter`
+ * to recognize a no-op write-back; intentionally narrow (handles the string / string[] /
+ * nested-object shapes `extractFrontmatter` produces).
+ */
+function frontmatterDeepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => frontmatterDeepEqual(v, b[i]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const ao = a;
+        const bo = b;
+        const ak = Object.keys(ao);
+        const bk = Object.keys(bo);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && frontmatterDeepEqual(ao[k], bo[k]));
+    }
+    return false;
+}
+function parseMustHavesBlock(content, blockName) {
+    // Extract a specific block from must_haves in raw frontmatter YAML
+    // Handles 3-level nesting: must_haves > artifacts/key_links > [{path, provides, ...}]
+    const fmMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+    if (!fmMatch)
+        return [];
+    const yaml = fmMatch[1];
+    // Find must_haves: first to detect its indentation level
+    const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m);
+    if (!mustHavesMatch)
+        return [];
+    const mustHavesIndent = mustHavesMatch[1].length;
+    // Find the block (e.g., "truths:", "artifacts:", "key_links:") under must_haves
+    // It must be indented more than must_haves but we detect the actual indent dynamically
+    const blockPattern = new RegExp(`^(\\s+)${blockName}:\\s*$`, 'm');
+    const blockMatch = yaml.match(blockPattern);
+    if (!blockMatch)
+        return [];
+    const blockIndent = blockMatch[1].length;
+    // The block must be nested under must_haves (more indented)
+    if (blockIndent <= mustHavesIndent)
+        return [];
+    // Find where the block starts in the yaml string
+    const blockStart = yaml.indexOf(blockMatch[0]);
+    if (blockStart === -1)
+        return [];
+    const afterBlock = yaml.slice(blockStart);
+    const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line
+    // List items are indented one level deeper than blockIndent
+    // Continuation KVs are indented one level deeper than list items
+    const items = [];
+    let current = null;
+    let listItemIndent = -1; // detected from first "- " line
+    for (const line of blockLines) {
+        // Skip empty lines
+        if (line.trim() === '')
+            continue;
+        const indentMatch = line.match(/^(\s*)/);
+        const indent = indentMatch ? indentMatch[1].length : 0;
+        // Stop at same or lower indent level than the block header
+        if (indent <= blockIndent && line.trim() !== '')
+            break;
+        const trimmed = line.trim();
+        if (trimmed.startsWith('- ')) {
+            // Detect list item indent from the first occurrence
+            if (listItemIndent === -1)
+                listItemIndent = indent;
+            // Only treat as a top-level list item if at the expected indent
+            if (indent === listItemIndent) {
+                if (current)
+                    items.push(current);
+                const afterDash = trimmed.slice(2);
+                const trimmedAfterDash = afterDash.trim();
+                // Check if it's a fully-quoted string (may contain ':' inside the quotes)
+                if ((trimmedAfterDash.startsWith('"') && trimmedAfterDash.endsWith('"')) ||
+                    (trimmedAfterDash.startsWith("'") && trimmedAfterDash.endsWith("'"))) {
+                    current = trimmedAfterDash.slice(1, -1);
+                    // Check if it's a simple string item (no colon means not a key-value)
+                }
+                else if (!afterDash.includes(':')) {
+                    current = afterDash.replace(/^["']|["']$/g, '');
+                }
+                else {
+                    // Key-value on same line as dash: "- path: value"
+                    // YAML KV always has at least one space after the colon: "key: value"
+                    // Requiring \s+ rejects "Class::Method" and "db:seed" (no space after colon)
+                    const kvMatch = afterDash.match(/^(\w+):\s+"?([^"]*)"?\s*$/);
+                    if (kvMatch) {
+                        current = {};
+                        (current)[kvMatch[1]] = kvMatch[2];
+                    }
+                    else {
+                        // Looks like KV but doesn't match — treat as plain string (#2757)
+                        current = afterDash.replace(/^["']|["']$/g, '');
+                    }
+                }
+                continue;
+            }
+        }
+        if (current && typeof current === 'object' && indent > listItemIndent) {
+            // Continuation key-value or nested array item
+            if (trimmed.startsWith('- ')) {
+                // Array item under a key
+                const arrVal = trimmed.slice(2).replace(/^["']|["']$/g, '');
+                const keys = Object.keys(current);
+                const lastKey = keys[keys.length - 1];
+                if (lastKey && !Array.isArray((current)[lastKey])) {
+                    const existing = (current)[lastKey];
+                    (current)[lastKey] = existing ? [existing] : [];
+                }
+                if (lastKey)
+                    (current)[lastKey].push(arrVal);
+            }
+            else {
+                const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+                if (kvMatch) {
+                    const val = kvMatch[2];
+                    // Try to parse as number
+                    (current)[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
+                }
+            }
+        }
+    }
+    if (current)
+        items.push(current);
+    // Warn when must_haves block exists but parsed as empty -- likely YAML formatting issue.
+    // This is a critical diagnostic: empty must_haves causes verification to silently degrade
+    // to Option C (LLM-derived truths) instead of checking documented contracts.
+    if (items.length === 0 && blockLines.length > 0) {
+        const nonEmptyLines = blockLines.filter(l => l.trim() !== '').length;
+        if (nonEmptyLines > 0) {
+            process.stderr.write(`[gsd-tools] WARNING: must_haves.${blockName} block has ${nonEmptyLines} content lines but parsed 0 items. ` +
+                `Possible YAML formatting issue — verification will fall back to LLM-derived truths.\n`);
+        }
+    }
+    return items;
+}
+// ─── Frontmatter CRUD commands ────────────────────────────────────────────────
+const FRONTMATTER_SCHEMAS = {
+    plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+    summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
+    verification: { required: ['phase', 'verified', 'status', 'score'] },
+};
+function cmdFrontmatterGet(cwd, filePath, field, raw) {
+    if (!filePath) {
+        error('file path required');
+    }
+    // Path traversal guard: reject null bytes
+    if (filePath.includes('\0')) {
+        error('file path contains null bytes');
+    }
+    const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
+    const content = (0, shell_command_projection_cjs_1.platformReadSync)(fullPath);
+    if (!content) {
+        output({ error: 'File not found', path: filePath }, raw, undefined);
+        return;
+    }
+    const fm = extractFrontmatter(content);
+    if (field) {
+        const value = fm[field];
+        if (value === undefined) {
+            output({ error: 'Field not found', field }, raw, undefined);
+            return;
+        }
+        output({ [field]: value }, raw, JSON.stringify(value));
+    }
+    else {
+        output(fm, raw, undefined);
+    }
+}
+function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
+    if (!filePath || !field || value === undefined) {
+        error('file, field, and value required');
+    }
+    // Path traversal guard: reject null bytes
+    if (filePath.includes('\0')) {
+        error('file path contains null bytes');
+    }
+    const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
+    if (!node_fs_1.default.existsSync(fullPath)) {
+        output({ error: 'File not found', path: filePath }, raw, undefined);
+        return;
+    }
+    const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    let parsedValue;
+    try {
+        parsedValue = JSON.parse(value);
+    }
+    catch {
+        parsedValue = value;
+    }
+    fm[field] = parsedValue;
+    const newContent = spliceFrontmatter(content, fm);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, newContent);
+    output({ updated: true, field, value: parsedValue }, raw, 'true');
+}
+function cmdFrontmatterMerge(cwd, filePath, data, raw) {
+    if (!filePath || !data) {
+        error('file and data required');
+    }
+    const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
+    if (!node_fs_1.default.existsSync(fullPath)) {
+        output({ error: 'File not found', path: filePath }, raw, undefined);
+        return;
+    }
+    const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    let mergeData;
+    try {
+        mergeData = JSON.parse(data);
+    }
+    catch {
+        error('Invalid JSON for --data');
+        return;
+    }
+    Object.assign(fm, mergeData);
+    const newContent = spliceFrontmatter(content, fm);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, newContent);
+    output({ merged: true, fields: Object.keys(mergeData) }, raw, 'true');
+}
+function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
+    if (!filePath || !schemaName) {
+        error('file and schema required');
+    }
+    const schema = FRONTMATTER_SCHEMAS[schemaName];
+    if (!schema) {
+        error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`);
+    }
+    const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
+    const content = (0, shell_command_projection_cjs_1.platformReadSync)(fullPath);
+    if (!content) {
+        output({ error: 'File not found', path: filePath }, raw, undefined);
+        return;
+    }
+    const fm = extractFrontmatter(content);
+    const missing = schema.required.filter(f => fm[f] === undefined);
+    const present = schema.required.filter(f => fm[f] !== undefined);
+    output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
+}
+module.exports = {
+    extractFrontmatter,
+    // Additive alias (#644 prohibition-probe schema contract): the probe round-trip seam reads a
+    // frontmatter object via `parseFrontmatter` (the name the contract test pins). It is the SAME
+    // function as `extractFrontmatter` — a bare-object parse with no behavior change — exposed under
+    // the alias so the prohibition schema round-trip and any future caller can use the canonical name.
+    parseFrontmatter: extractFrontmatter,
+    reconstructFrontmatter,
+    spliceFrontmatter,
+    parseMustHavesBlock,
+    FRONTMATTER_SCHEMAS,
+    cmdFrontmatterGet,
+    cmdFrontmatterSet,
+    cmdFrontmatterMerge,
+    cmdFrontmatterValidate,
+};