pan-wizard 3.5.2 → 3.8.0

package/pan-wizard-core/bin/lib/doc-lint/frontmatter.js

@@ -0,0 +1,270 @@
+'use strict';
+/**
+ * frontmatter.js — minimal YAML-ish frontmatter parser.
+ *
+ * Supports the subset documented in DESIGN_SPEC.md §"YAML subset":
+ *   - Scalars: strings (quoted or bare), numbers, booleans, null
+ *   - Flow lists: [a, b, c]
+ *   - Block maps: key: value (one per line)
+ *   - Comments: # ... (skipped)
+ *
+ * Anything beyond this subset → error code 'frontmatter-malformed'.
+ *
+ * Returns: {data, bodyStart, errors}
+ *   data       — parsed object (empty {} if no frontmatter)
+ *   bodyStart  — line number (1-indexed) where the body starts (after closing ---)
+ *                Used for line-number arithmetic in violation reports.
+ *   errors     — array of {line, message} for parse problems (NOT validation —
+ *                that's validate.js's job)
+ */
+
+const FENCE = '---';
+
+function parseFrontmatter(text) {
+  if (text == null) return { data: {}, bodyStart: 1, errors: [] };
+
+  const lines = text.split(/\r?\n/);
+  if (lines.length === 0 || lines[0] !== FENCE) {
+    // No frontmatter. Body starts at line 1.
+    return { data: {}, bodyStart: 1, errors: [], hasFrontmatter: false };
+  }
+
+  // Find closing fence
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === FENCE) {
+      closingIndex = i;
+      break;
+    }
+  }
+
+  if (closingIndex === -1) {
+    return {
+      data: {},
+      bodyStart: 1,
+      errors: [{ line: 1, message: 'frontmatter opening --- has no matching closing ---' }],
+      hasFrontmatter: true,
+    };
+  }
+
+  const fmLines = lines.slice(1, closingIndex);
+  const result = parseFrontmatterBlock(fmLines);
+
+  return {
+    data: result.data,
+    bodyStart: closingIndex + 2, // 1-indexed line AFTER the closing ---
+    errors: result.errors,
+    hasFrontmatter: true,
+  };
+}
+
+function parseFrontmatterBlock(lines) {
+  const data = {};
+  const errors = [];
+
+  // Extended after dogfood gate (see .planning/optimization/traces/.../trace.jsonl event 2026-04-27T11:50:00Z):
+  // Block-style lists are the dominant real-world format. The DESIGN_SPEC originally
+  // scoped them out — that decision was wrong. Block-list support added per deviation R1.
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 2; // 1-indexed in source file (line 1 is opening ---)
+    let line = lines[i];
+
+    // Strip trailing comments
+    line = stripTrailingComment(line);
+
+    // Skip blank/comment-only lines
+    if (line.trim() === '') continue;
+
+    // Match `key:` (no value) — start of a block list or block map
+    const blockKeyMatch = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*$/);
+    if (blockKeyMatch) {
+      const key = blockKeyMatch[1];
+
+      // Look ahead: collect subsequent lines that are list items ("  - x") or
+      // sub-map entries ("  k: v") indented under this key. Stop at next top-level
+      // key (no leading whitespace) or end of block.
+      const childLines = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const next = lines[j];
+        if (next.trim() === '' || next.trim().startsWith('#')) { j++; continue; }
+        // Top-level key (no indent) ends the child block
+        if (/^[A-Za-z_]/.test(next)) break;
+        // Indented line — accumulate
+        childLines.push({ raw: next, line: j + 2 });
+        j++;
+      }
+
+      // Detect: is this a block list (- items) or a block map (key: val)?
+      const looksList = childLines.length > 0 && childLines.every(c => /^\s+-\s+/.test(c.raw));
+      if (looksList) {
+        const items = [];
+        for (const cl of childLines) {
+          const itemMatch = cl.raw.match(/^\s+-\s+(.*)$/);
+          if (!itemMatch) {
+            errors.push({ line: cl.line, message: `expected "- value" in block list, got: ${JSON.stringify(cl.raw)}` });
+            continue;
+          }
+          const itemRaw = stripTrailingComment(itemMatch[1]).trim();
+          const parsed = parseScalarOrList(itemRaw, cl.line);
+          if (parsed.error) {
+            errors.push({ line: cl.line, message: `in list item: ${parsed.error}` });
+            continue;
+          }
+          items.push(parsed.value);
+        }
+        if (key in data) {
+          errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+        } else {
+          data[key] = items;
+        }
+        i = j - 1; // resume after the block
+        continue;
+      }
+      // Block map shape: not supported in v0.1, but don't error — treat the
+      // key as null-valued and let validation handle it.
+      if (childLines.length > 0) {
+        // Block-style maps are out of scope per DESIGN_SPEC. Surface a warning
+        // rather than a crash so the rest of the file still validates.
+        errors.push({ line: lineNum, message: `block-map values not supported in v0.1 for key "${key}" (use a flow map or scalar)` });
+        i = j - 1;
+        continue;
+      }
+      // No child lines → just an empty value
+      if (key in data) {
+        errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+      } else {
+        data[key] = null;
+      }
+      continue;
+    }
+
+    // Match `key: value` (scalar / flow list / etc.)
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) {
+      errors.push({ line: lineNum, message: `expected "key: value", got: ${JSON.stringify(line)}` });
+      continue;
+    }
+
+    const key = m[1];
+    const rawValue = m[2];
+
+    if (key in data) {
+      errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+      continue;
+    }
+
+    const parsed = parseScalarOrList(rawValue, lineNum);
+    if (parsed.error) {
+      errors.push({ line: lineNum, message: parsed.error });
+      continue;
+    }
+    data[key] = parsed.value;
+  }
+
+  return { data, errors };
+}
+
+function stripTrailingComment(line) {
+  // Naive: strip from first # not inside quotes. PAN frontmatter doesn't put
+  // # in values, so this is safe for our subset. If a user does, they'll see
+  // a frontmatter-malformed error and can quote it.
+  const inSingle = (s, idx) => {
+    let q = 0;
+    for (let j = 0; j < idx; j++) if (s[j] === "'") q++;
+    return q % 2 === 1;
+  };
+  const inDouble = (s, idx) => {
+    let q = 0;
+    for (let j = 0; j < idx; j++) if (s[j] === '"') q++;
+    return q % 2 === 1;
+  };
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '#' && !inSingle(line, i) && !inDouble(line, i)) {
+      return line.slice(0, i).trimEnd();
+    }
+  }
+  return line;
+}
+
+function parseScalarOrList(raw, lineNum) {
+  const trimmed = raw.trim();
+
+  if (trimmed === '') return { value: null };
+
+  // Flow list: [a, b, c]
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === '') return { value: [] };
+    const items = splitFlowItems(inner);
+    const parsedItems = [];
+    for (const item of items) {
+      const sub = parseScalarOrList(item, lineNum);
+      if (sub.error) return { error: `in list: ${sub.error}` };
+      parsedItems.push(sub.value);
+    }
+    return { value: parsedItems };
+  }
+
+  if (trimmed.startsWith('{')) {
+    return { error: `inline maps not supported in v0.1 (got ${JSON.stringify(trimmed)})` };
+  }
+
+  // Quoted strings
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    if (trimmed.length < 2) return { error: 'unterminated quoted string' };
+    return { value: trimmed.slice(1, -1) };
+  }
+
+  // Bare keywords
+  if (trimmed === 'true') return { value: true };
+  if (trimmed === 'false') return { value: false };
+  if (trimmed === 'null' || trimmed === '~') return { value: null };
+
+  // Numbers
+  if (/^-?\d+$/.test(trimmed)) return { value: parseInt(trimmed, 10) };
+  if (/^-?\d+\.\d+$/.test(trimmed)) return { value: parseFloat(trimmed) };
+
+  // Bare string (catch-all)
+  return { value: trimmed };
+}
+
+function splitFlowItems(inner) {
+  // Simple comma-split that respects quoted strings and nested brackets.
+  const items = [];
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let current = '';
+
+  for (const ch of inner) {
+    if (inSingle) {
+      current += ch;
+      if (ch === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      current += ch;
+      if (ch === '"') inDouble = false;
+      continue;
+    }
+    if (ch === "'") { inSingle = true; current += ch; continue; }
+    if (ch === '"') { inDouble = true; current += ch; continue; }
+    if (ch === '[' || ch === '{') { depth++; current += ch; continue; }
+    if (ch === ']' || ch === '}') { depth--; current += ch; continue; }
+    if (ch === ',' && depth === 0) {
+      items.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim() !== '') items.push(current.trim());
+  return items;
+}
+
+module.exports = { parseFrontmatter };

package/pan-wizard-core/bin/lib/doc-lint/reporter.js

@@ -0,0 +1,45 @@
+'use strict';
+/**
+ * reporter.js — format violations for output.
+ *
+ * Two formats per DESIGN_SPEC.md §"CLI surface":
+ *   - human: <file>:<line> — <code> — <message>   (multi-line, colorless for v0.1)
+ *   - json:  NDJSON, one violation per line
+ */
+
+/**
+ * @param {Array<Violation>} violations
+ * @returns {string}
+ */
+function formatHuman(violations) {
+  if (!violations || violations.length === 0) return '';
+  const lines = [];
+  for (const v of violations) {
+    const sev = v.severity === 'warning' ? '[warn]' : '[err] ';
+    lines.push(`${sev} ${v.file}:${v.line} — ${v.code} — ${v.message}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {Array<Violation>} violations
+ * @returns {string}
+ */
+function formatJson(violations) {
+  if (!violations || violations.length === 0) return '';
+  return violations.map(v => JSON.stringify(v)).join('\n');
+}
+
+/**
+ * Returns a one-line summary suitable for end-of-run output.
+ * @param {Array<Violation>} violations
+ * @param {number} fileCount
+ * @returns {string}
+ */
+function summaryLine(violations, fileCount) {
+  const errors = violations.filter(v => v.severity === 'error').length;
+  const warnings = violations.filter(v => v.severity === 'warning').length;
+  return `Linted ${fileCount} file(s): ${errors} error(s), ${warnings} warning(s)`;
+}
+
+module.exports = { formatHuman, formatJson, summaryLine };

package/pan-wizard-core/bin/lib/doc-lint/schema.js

@@ -0,0 +1,202 @@
+'use strict';
+/**
+ * schema.js — parse + validate schema definition files.
+ *
+ * Schema source format (also YAML-ish, parsed by frontmatter.js's parser
+ * applied to a fenced wrapper):
+ *
+ *   fields:
+ *     title:
+ *       required: true
+ *       type: string
+ *       pattern: ^[A-Z]
+ *
+ * Returns: {schema, errors} where schema is the normalized form with regexes
+ * compiled, types validated, etc.
+ *
+ * Note: we don't reuse the frontmatter parser's block style — schemas use a
+ * deeper nested map shape than v0.1 frontmatter supports. We hand-roll a tiny
+ * indentation-aware parser tuned for the schema shape only. This is a
+ * scope-bounded compromise documented in DESIGN_SPEC §"YAML subset".
+ */
+
+const VALID_TYPES = ['string', 'number', 'boolean', 'enum', 'array'];
+const FIELD_KEYS = ['required', 'type', 'pattern', 'values', 'default', 'items'];
+
+/**
+ * Parse a schema source string into a normalized schema or return errors.
+ * @returns {{schema: object|null, errors: Array<{line:number, message:string}>}}
+ */
+function parseSchema(text) {
+  const errors = [];
+  if (text == null || text.trim() === '') {
+    return { schema: null, errors: [{ line: 1, message: 'schema is empty' }] };
+  }
+
+  const lines = text.split(/\r?\n/);
+
+  // Find `fields:` line
+  let fieldsLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === 'fields:') {
+      fieldsLine = i;
+      break;
+    }
+  }
+
+  if (fieldsLine === -1) {
+    errors.push({ line: 1, message: 'schema must start with `fields:` block' });
+    return { schema: null, errors };
+  }
+
+  // Parse fields block
+  const fields = {};
+  let currentField = null;
+  let currentFieldLine = 0;
+
+  for (let i = fieldsLine + 1; i < lines.length; i++) {
+    const lineNum = i + 1; // 1-indexed
+    const raw = lines[i];
+
+    // Skip blank lines
+    if (raw.trim() === '') continue;
+    // Skip comment lines
+    if (raw.trim().startsWith('#')) continue;
+
+    // Field name: 2-space indent, ends with `:`
+    const fieldMatch = raw.match(/^  ([A-Za-z_][A-Za-z0-9_-]*):\s*$/);
+    if (fieldMatch) {
+      currentField = fieldMatch[1];
+      currentFieldLine = lineNum;
+      if (currentField in fields) {
+        errors.push({ line: lineNum, message: `duplicate field "${currentField}"` });
+      }
+      fields[currentField] = { _line: lineNum };
+      continue;
+    }
+
+    // Field property: 4-space indent
+    const propMatch = raw.match(/^    ([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (propMatch && currentField) {
+      const key = propMatch[1];
+      const rawValue = propMatch[2].trim();
+
+      if (!FIELD_KEYS.includes(key)) {
+        errors.push({ line: lineNum, message: `unknown field property "${key}" (allowed: ${FIELD_KEYS.join(', ')})` });
+        continue;
+      }
+
+      const parsed = parseSchemaValue(key, rawValue, lineNum);
+      if (parsed.error) {
+        errors.push({ line: lineNum, message: parsed.error });
+        continue;
+      }
+      fields[currentField][key] = parsed.value;
+      continue;
+    }
+
+    // Anything else (including incorrectly-indented lines)
+    if (raw.length > 0 && !/^\s*$/.test(raw)) {
+      errors.push({ line: lineNum, message: `unexpected line in fields block: ${JSON.stringify(raw)}` });
+    }
+  }
+
+  // Validate each field
+  const normalized = {};
+  for (const [name, def] of Object.entries(fields)) {
+    const fieldErrors = checkFieldDefinition(name, def);
+    errors.push(...fieldErrors);
+    if (fieldErrors.length === 0) {
+      // Strip the _line marker from the public shape; keep all other props
+      const { _line, ...publicDef } = def;
+      normalized[name] = publicDef;
+    }
+  }
+
+  return {
+    schema: errors.length === 0 ? { fields: normalized } : null,
+    errors,
+  };
+}
+
+function parseSchemaValue(key, rawValue, lineNum) {
+  if (key === 'required') {
+    if (rawValue === 'true') return { value: true };
+    if (rawValue === 'false') return { value: false };
+    return { error: `required must be true|false, got ${JSON.stringify(rawValue)}` };
+  }
+
+  if (key === 'type') {
+    if (!VALID_TYPES.includes(rawValue)) {
+      return { error: `type must be one of ${VALID_TYPES.join(', ')}, got ${JSON.stringify(rawValue)}` };
+    }
+    return { value: rawValue };
+  }
+
+  if (key === 'pattern') {
+    try {
+      return { value: new RegExp(rawValue) };
+    } catch (e) {
+      return { error: `invalid regex pattern: ${e.message}` };
+    }
+  }
+
+  if (key === 'values') {
+    // Inline list shape: [a, b, c]
+    if (!rawValue.startsWith('[') || !rawValue.endsWith(']')) {
+      return { error: `values must be a flow list [a, b, c], got ${JSON.stringify(rawValue)}` };
+    }
+    const inner = rawValue.slice(1, -1).trim();
+    if (inner === '') return { value: [] };
+    return { value: inner.split(',').map(s => s.trim()).filter(Boolean) };
+  }
+
+  if (key === 'default') {
+    return { value: rawValue }; // store raw
+  }
+
+  if (key === 'items') {
+    if (!VALID_TYPES.includes(rawValue)) {
+      return { error: `items must be one of ${VALID_TYPES.join(', ')}, got ${JSON.stringify(rawValue)}` };
+    }
+    return { value: rawValue };
+  }
+
+  return { error: `unknown property ${key}` };
+}
+
+function checkFieldDefinition(name, def) {
+  const errors = [];
+  const line = def._line || 1;
+
+  if (!('type' in def)) {
+    errors.push({ line, message: `field "${name}" missing required property "type"` });
+    return errors;
+  }
+
+  if (def.type === 'enum' && !('values' in def)) {
+    errors.push({ line, message: `field "${name}" type=enum requires "values:"` });
+  }
+
+  if (def.type === 'array' && !('items' in def)) {
+    errors.push({ line, message: `field "${name}" type=array requires "items:"` });
+  }
+
+  if (def.required === true && 'default' in def) {
+    errors.push({ line, message: `field "${name}" cannot have both required:true and default:` });
+  }
+
+  return errors;
+}
+
+/**
+ * Public API: validate that a parsed schema is well-formed (no extra checks
+ * beyond what parseSchema already does, but exposed for the CLI's
+ * `whooo schema check` subcommand).
+ */
+function checkSchema(schemaText) {
+  const result = parseSchema(schemaText);
+  return { ok: result.errors.length === 0, errors: result.errors };
+}
+
+module.exports = { parseSchema, checkSchema, VALID_TYPES, FIELD_KEYS };

package/pan-wizard-core/bin/lib/doc-lint/validate.js

@@ -0,0 +1,190 @@
+'use strict';
+/**
+ * validate.js — validate parsed frontmatter data against a parsed schema.
+ *
+ * Returns an array of violations matching the shape documented in
+ * DESIGN_SPEC.md §"Key data shapes":
+ *
+ *   { file, line, field, code, message, severity }
+ *
+ * Implements the 8 error codes in DESIGN_SPEC.md §"Error codes":
+ *   frontmatter-missing, frontmatter-malformed, required-missing,
+ *   type-mismatch, enum-violation, pattern-mismatch, array-item-type,
+ *   unknown-field
+ *
+ * The {data, errors, hasFrontmatter} input is whatever frontmatter.js
+ * returned for a given file. line numbers are absolute in the source file.
+ */
+
+/**
+ * @param {object} fmResult - {data, bodyStart, errors, hasFrontmatter} from parseFrontmatter
+ * @param {object} schema   - parsed schema from parseSchema (i.e., {fields: {...}})
+ * @param {string} sourceFile - POSIX-style relative path for the violation report
+ * @param {object} [opts]   - {strict: bool} — if true, frontmatter-missing is error severity
+ * @returns {Array<Violation>}
+ */
+function validateAgainstSchema(fmResult, schema, sourceFile, opts = {}) {
+  const violations = [];
+  const strict = !!opts.strict;
+
+  // 1. Frontmatter parse errors → frontmatter-malformed
+  if (fmResult.errors && fmResult.errors.length > 0) {
+    for (const err of fmResult.errors) {
+      violations.push(violation({
+        file: sourceFile, line: err.line, field: null,
+        code: 'frontmatter-malformed',
+        message: err.message,
+        severity: 'error',
+      }));
+    }
+    return violations; // can't validate fields if parse failed
+  }
+
+  // 2. No frontmatter at all
+  if (fmResult.hasFrontmatter === false) {
+    violations.push(violation({
+      file: sourceFile, line: 1, field: null,
+      code: 'frontmatter-missing',
+      message: 'file has no frontmatter',
+      severity: strict ? 'error' : 'warning',
+    }));
+    return violations;
+  }
+
+  const data = fmResult.data || {};
+  const fields = schema.fields || {};
+
+  // 3. Per-field checks
+  for (const [name, def] of Object.entries(fields)) {
+    const present = name in data;
+    const value = data[name];
+
+    if (!present) {
+      if (def.required) {
+        violations.push(violation({
+          file: sourceFile, line: 1, field: name,
+          code: 'required-missing',
+          message: `field "${name}" is required`,
+          severity: 'error',
+        }));
+      }
+      continue;
+    }
+
+    // Type check
+    const typeError = checkType(value, def);
+    if (typeError) {
+      violations.push(violation({
+        file: sourceFile, line: 1, field: name,
+        code: typeError.code,
+        message: typeError.message,
+        severity: 'error',
+      }));
+      continue;
+    }
+
+    // Enum check
+    if (def.type === 'enum' && Array.isArray(def.values) && !def.values.includes(String(value))) {
+      violations.push(violation({
+        file: sourceFile, line: 1, field: name,
+        code: 'enum-violation',
+        message: `field "${name}" value ${JSON.stringify(value)} not in [${def.values.join(', ')}]`,
+        severity: 'error',
+      }));
+      continue;
+    }
+
+    // Pattern check
+    if (def.pattern instanceof RegExp && typeof value === 'string' && !def.pattern.test(value)) {
+      violations.push(violation({
+        file: sourceFile, line: 1, field: name,
+        code: 'pattern-mismatch',
+        message: `field "${name}" value ${JSON.stringify(value)} does not match pattern ${def.pattern}`,
+        severity: 'error',
+      }));
+      continue;
+    }
+  }
+
+  // 4. Unknown fields (warning only — info-level)
+  for (const key of Object.keys(data)) {
+    if (!(key in fields)) {
+      violations.push(violation({
+        file: sourceFile, line: 1, field: key,
+        code: 'unknown-field',
+        message: `field "${key}" is not in schema (consider adding it or removing from file)`,
+        severity: 'warning',
+      }));
+    }
+  }
+
+  return violations;
+}
+
+function checkType(value, def) {
+  switch (def.type) {
+    case 'string':
+      if (typeof value !== 'string') {
+        return { code: 'type-mismatch', message: `expected string, got ${typeOf(value)}` };
+      }
+      return null;
+    case 'number':
+      if (typeof value !== 'number') {
+        return { code: 'type-mismatch', message: `expected number, got ${typeOf(value)}` };
+      }
+      return null;
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        return { code: 'type-mismatch', message: `expected boolean, got ${typeOf(value)}` };
+      }
+      return null;
+    case 'enum':
+      if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+        return { code: 'type-mismatch', message: `expected scalar (for enum), got ${typeOf(value)}` };
+      }
+      return null;
+    case 'array':
+      if (!Array.isArray(value)) {
+        return { code: 'type-mismatch', message: `expected array, got ${typeOf(value)}` };
+      }
+      // Item type check
+      if (def.items) {
+        for (let i = 0; i < value.length; i++) {
+          const itemType = typeOf(value[i]);
+          const expected = def.items;
+          // Note: the item-type contract treats string/number/boolean only;
+          // enum/array items are out of scope for v0.1.
+          const matches = (
+            (expected === 'string' && itemType === 'string') ||
+            (expected === 'number' && itemType === 'number') ||
+            (expected === 'boolean' && itemType === 'boolean')
+          );
+          if (!matches) {
+            return { code: 'array-item-type', message: `array item [${i}] expected ${expected}, got ${itemType}` };
+          }
+        }
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+
+function typeOf(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+function violation(v) {
+  return {
+    file: v.file,
+    line: v.line || 1,
+    field: v.field || null,
+    code: v.code,
+    message: v.message,
+    severity: v.severity || 'error',
+  };
+}
+
+module.exports = { validateAgainstSchema };