pan-wizard 3.5.1 → 3.7.10

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 };

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

@@ -0,0 +1,135 @@
+'use strict';
+/**
+ * walk.js — recursive .md file walker with --exclude glob support.
+ *
+ * Synchronous (no need for async — file count is bounded; perf budget allows
+ * it; matches PAN's CLI shape). Returns an array of {path, content} where
+ * `path` is an absolute path with forward-slash normalization (POSIX).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Normalize a path to POSIX-style forward slashes. */
+function toPosix(p) {
+  return p.replace(/\\/g, '/');
+}
+
+/**
+ * Walk a directory recursively and return all .md files.
+ *
+ * @param {string} dir - absolute directory path
+ * @param {object} [opts]
+ * @param {Array<string>} [opts.exclude] - simple glob patterns to exclude
+ *   (matches against the POSIX path; supported tokens: ** and *)
+ * @returns {Array<{path: string, content: string, relativePath: string}>}
+ */
+function walkMarkdownFiles(dir, opts = {}) {
+  const exclude = opts.exclude || [];
+  const excludeRegexes = exclude.map(globToRegex);
+
+  if (!fs.existsSync(dir)) {
+    throw new Error(`directory not found: ${dir}`);
+  }
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) {
+    throw new Error(`not a directory: ${dir}`);
+  }
+
+  const out = [];
+  const baseAbs = path.resolve(dir);
+  walkRecursive(baseAbs, baseAbs, excludeRegexes, out);
+  return out;
+}
+
+function walkRecursive(currentDir, baseDir, excludeRegexes, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(currentDir, { withFileTypes: true });
+  } catch (err) {
+    // Permission denied, etc. — emit a synthetic entry the caller can convert
+    // to a violation.
+    out.push({
+      path: toPosix(currentDir),
+      content: null,
+      relativePath: toPosix(path.relative(baseDir, currentDir)),
+      readError: err.message,
+    });
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+    const posixFull = toPosix(fullPath);
+    const relative = toPosix(path.relative(baseDir, fullPath));
+
+    if (matchesAny(posixFull, excludeRegexes) || matchesAny(relative, excludeRegexes)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      walkRecursive(fullPath, baseDir, excludeRegexes, out);
+      continue;
+    }
+
+    if (entry.isFile() && entry.name.endsWith('.md')) {
+      let content = '';
+      let readError = null;
+      try {
+        content = fs.readFileSync(fullPath, 'utf-8');
+      } catch (err) {
+        readError = err.message;
+      }
+      out.push({
+        path: posixFull,
+        relativePath: relative,
+        content,
+        readError,
+      });
+    }
+  }
+}
+
+function matchesAny(s, regexes) {
+  for (const re of regexes) if (re.test(s)) return true;
+  return false;
+}
+
+/**
+ * Convert a simple glob to a RegExp.
+ * Supports: ** (matches any chars including /), * (matches any chars except /)
+ * Anchored to full string match.
+ *
+ * Convention: when `**` is followed by `/`, the slash is also optional —
+ * `**\/foo.md` matches both `foo.md` (root) and `a/b/foo.md` (nested).
+ * Mirrors gitignore / minimatch behavior.
+ */
+function globToRegex(glob) {
+  let re = '^';
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        // Match the standard `**\/<name>` pattern: the trailing slash is
+        // optional, so `**\/foo.md` matches root-level `foo.md` too.
+        if (glob[i + 2] === '/') {
+          re += '(?:.*/)?';
+          i += 2; // skip ** and /
+        } else {
+          re += '.*';
+          i++; // skip next *
+        }
+      } else {
+        re += '[^/]*';
+      }
+    } else if ('.+?^$()|{}[]\\'.includes(ch)) {
+      re += '\\' + ch;
+    } else {
+      re += ch;
+    }
+  }
+  re += '$';
+  return new RegExp(re);
+}
+
+module.exports = { walkMarkdownFiles, toPosix, globToRegex };