pan-wizard 3.5.2 → 3.8.0

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

package/pan-wizard-core/bin/lib/doc-lint.cjs

@@ -0,0 +1,287 @@
+'use strict';
+/**
+ * doc-lint.cjs — markdown frontmatter linter for PAN's own files.
+ *
+ * Vendored from whooo (https://github.com/oharms/PanWizard experiments/whooo).
+ * Wraps doc-lint/{frontmatter,schema,validate,walk,reporter}.js with PAN's
+ * core.cjs output() pattern.
+ *
+ * Spec: docs/specs/self_improvement_loop_featureai.md (whooo experiment outputs)
+ * Pattern source: P-201 + P-202 + P-301 (promoted from whooo run, v3.7.0)
+ *
+ * Usage (CLI):
+ *   pan-tools doc-lint <dir> [--schema <path>] [--format json|human] [--strict]
+ *
+ * Default schema: pan-wizard-core/references/schemas/pan-command.schema.yml
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+
+const { parseFrontmatter } = require('./doc-lint/frontmatter.js');
+const { parseSchema } = require('./doc-lint/schema.js');
+const { validateAgainstSchema } = require('./doc-lint/validate.js');
+const { walkMarkdownFiles } = require('./doc-lint/walk.js');
+const { formatHuman, formatJson, summaryLine } = require('./doc-lint/reporter.js');
+
+const DEFAULT_SCHEMA_PATH = path.join(
+  __dirname,
+  '..',
+  '..',
+  'references',
+  'schemas',
+  'pan-command.schema.yml'
+);
+
+/**
+ * Lint a directory of markdown files against a schema.
+ * @param {string} cwd - working directory (used to resolve relative paths)
+ * @param {string} dir - directory to scan (relative to cwd or absolute)
+ * @param {object} opts - { schema: string, format: 'json'|'human', strict: bool, exclude: string[], raw: bool }
+ * @returns {void} — writes to stdout via output(); exit code via process.exit
+ */
+function cmdDocLint(cwd, dir, opts = {}) {
+  const targetDir = path.isAbsolute(dir) ? dir : path.join(cwd, dir);
+  if (!fs.existsSync(targetDir)) {
+    error(`directory not found: ${targetDir}`);
+  }
+
+  const schemaPath = opts.schema
+    ? (path.isAbsolute(opts.schema) ? opts.schema : path.join(cwd, opts.schema))
+    : DEFAULT_SCHEMA_PATH;
+  if (!fs.existsSync(schemaPath)) {
+    error(`schema not found: ${schemaPath}`);
+  }
+
+  const schemaText = fs.readFileSync(schemaPath, 'utf-8');
+  const { schema, errors: schemaErrors } = parseSchema(schemaText);
+  if (schemaErrors.length > 0) {
+    if (opts.raw) {
+      process.stderr.write(`schema has ${schemaErrors.length} error(s):\n`);
+      for (const e of schemaErrors) {
+        process.stderr.write(`  ${schemaPath}:${e.line} — ${e.message}\n`);
+      }
+    } else {
+      output({ schema_errors: schemaErrors, schema: schemaPath }, false);
+    }
+    process.exit(2);
+  }
+
+  const exclude = opts.exclude || [];
+  const files = walkMarkdownFiles(targetDir, { exclude });
+  const violations = [];
+  for (const file of files) {
+    if (file.readError) {
+      violations.push({
+        file: file.relativePath,
+        line: 1, field: null,
+        code: 'file-read-error',
+        message: file.readError,
+        severity: 'error',
+      });
+      continue;
+    }
+    const fm = parseFrontmatter(file.content);
+    const v = validateAgainstSchema(fm, schema, file.relativePath, { strict: !!opts.strict });
+    violations.push(...v);
+  }
+
+  const fileCount = files.length;
+  const errorCount = violations.filter(v => v.severity === 'error').length;
+  const warningCount = violations.filter(v => v.severity === 'warning').length;
+
+  const format = opts.format || 'human';
+  if (opts.raw) {
+    if (format === 'json') {
+      const txt = formatJson(violations);
+      if (txt) process.stdout.write(txt + '\n');
+    } else {
+      const txt = formatHuman(violations);
+      if (txt) process.stdout.write(txt + '\n');
+      process.stdout.write(summaryLine(violations, fileCount) + '\n');
+    }
+  } else {
+    output({
+      directory: dir,
+      schema: schemaPath,
+      file_count: fileCount,
+      error_count: errorCount,
+      warning_count: warningCount,
+      violations,
+    }, false);
+  }
+
+  process.exit(errorCount > 0 ? 1 : 0);
+}
+
+/**
+ * Validate that a schema file is well-formed.
+ */
+function cmdDocLintSchemaCheck(cwd, schemaPath, opts = {}) {
+  const resolved = path.isAbsolute(schemaPath) ? schemaPath : path.join(cwd, schemaPath);
+  if (!fs.existsSync(resolved)) {
+    error(`schema not found: ${resolved}`);
+  }
+  const text = fs.readFileSync(resolved, 'utf-8');
+  const { errors } = parseSchema(text);
+  const result = {
+    schema: resolved,
+    ok: errors.length === 0,
+    error_count: errors.length,
+    errors,
+  };
+  output(result, opts.raw);
+  process.exit(result.ok ? 0 : 1);
+}
+
+// ─── Count-drift lint (IMPROVEMENT-TODO P1, v3.7.10) ────────────────────────
+//
+// Counts (tests, commands, agents, modules, etc.) are supposed to live ONLY
+// in CLAUDE.md. Other docs MUST NOT embed them — they drift instantly. This
+// linter scans markdown files and flags any drift-prone numeric count it
+// finds outside the allowed paths.
+
+// Negative lookbehind `(?<!\.)` excludes version-number captures like
+// "v3.5 module" or "v4.7 Commands" — these are version refs, not counts.
+const COUNT_PATTERNS = [
+  // "52 commands", "21 agents", "30 modules", "2667 tests", etc.
+  // Word boundaries + allowed plurals; case-insensitive matching.
+  { re: /(?<!\.)\b(\d+)\s+(commands?|agents?|modules?|workflows?|templates?|references?|specs?|adrs?|test\s+files?|test\s+suites?)\b/gi,
+    label: 'noun-phrase count' },
+  // "27th module", "21st agent", "52nd command" — drift-prone ordinals
+  { re: /(?<!\.)\b(\d+)(th|st|nd|rd)\s+(module|reference|agent|command|template|hook|workflow|spec|adr)\b/gi,
+    label: 'ordinal' },
+  // "(9 files)", "(58 tests)" — parenthetical counts
+  { re: /(?<!\.)\((\d+)\s+(files?|tests?)\)/gi, label: 'parenthetical count' },
+];
+
+// Files where counts ARE allowed:
+//   - CLAUDE.md (the SSoT)
+//   - CHANGELOG.md (frozen historical record)
+//   - MEMORY.md (user memory file, not shipped)
+//   - SKILLS-FULL-TEXT.md / SKILLS-REFERENCE.md (auto-generated; embed command
+//     prompt text that itself may legitimately reference numbers)
+//   - EXAMPLES.md (illustrative tool-output scenarios, not authoritative claims)
+const COUNT_ALLOWED_RE = /(^|[\\/])(CLAUDE\.md|CHANGELOG\.md|MEMORY\.md|SKILLS-FULL-TEXT\.md|SKILLS-REFERENCE\.md|EXAMPLES\.md)$/i;
+
+// Path SEGMENTS that mark a directory as count-allowed (frozen historical
+// content). Matched as path segments so they catch both project-root-relative
+// paths (e.g. "docs/decisions/X.md") and scan-root-relative paths (e.g.
+// "decisions/X.md" when the scan rooted at docs/).
+const COUNT_ALLOWED_DIR_SEGMENTS = [
+  'decisions',  // ADRs — frozen
+  'specs',      // feature specs — frozen
+  'experiments', // harvested experiment artifacts
+  'learnings',  // AI-derived patterns; evidence quotes reference numbers
+  'archive',    // archived old docs
+];
+
+function isCountAllowed(relativePath) {
+  if (COUNT_ALLOWED_RE.test(relativePath)) return true;
+  const norm = relativePath.replace(/\\/g, '/');
+  const segments = norm.split('/');
+  return segments.some(seg => COUNT_ALLOWED_DIR_SEGMENTS.includes(seg));
+}
+
+// Things that LOOK like counts but are stable identities (allowed everywhere):
+const STABLE_IDENTITIES = [
+  /\b5\s+(target\s+)?runtimes\b/i,                          // 5 target runtimes
+  /\b5\s+hooks\b/i,                                          // 5 hooks (named individually)
+  /\bLAYER\s+\d+\b/,                                         // architecture layer labels
+  /\b5\s+(parallel\s+)?(researchers?|research\s+)/i,         // 5 parallel researchers
+  /\b6\s+(parallel\s+)?agents\b/i,                           // 6 parallel agents (codebase mapper)
+  /\b6\s+focus\s+areas\b/i,                                  // 6 focus areas (mapper)
+  /\b4\s+parallel\s+research/i,                              // 4 parallel research
+  /\bthree\s+phases\b|\bfour\s+phases\b/i,                   // generic phase counts in narrative
+];
+
+function isStableIdentity(matchText, surrounding) {
+  for (const re of STABLE_IDENTITIES) {
+    if (re.test(matchText) || re.test(surrounding)) return true;
+  }
+  return false;
+}
+
+/**
+ * Scan a directory tree for drift-prone count violations.
+ * @param {string} cwd - working directory
+ * @param {string} dir - dir to scan (relative or absolute)
+ * @param {object} opts - { format, raw, exclude }
+ */
+function cmdDocLintCounts(cwd, dir, opts = {}) {
+  const targetDir = path.isAbsolute(dir) ? dir : path.join(cwd, dir);
+  if (!fs.existsSync(targetDir)) {
+    error(`directory not found: ${targetDir}`);
+  }
+
+  const exclude = opts.exclude || [];
+  const files = walkMarkdownFiles(targetDir, { exclude });
+  const violations = [];
+
+  for (const file of files) {
+    if (isCountAllowed(file.relativePath)) continue;
+    if (file.readError) continue;
+
+    const lines = file.content.split(/\r?\n/);
+    let inFence = false;  // track ```fenced``` code blocks; skip their content
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Toggle fence on lines starting with ```
+      if (/^\s{0,3}```/.test(line)) {
+        inFence = !inFence;
+        continue;
+      }
+      if (inFence) continue;
+
+      for (const { re, label } of COUNT_PATTERNS) {
+        re.lastIndex = 0; // reset for /g
+        let m;
+        while ((m = re.exec(line)) !== null) {
+          // Skip if this whole line is in a stable-identity surrounding
+          if (isStableIdentity(m[0], line)) continue;
+          violations.push({
+            file: file.relativePath,
+            line: i + 1,
+            column: m.index + 1,
+            match: m[0],
+            label,
+            severity: 'warning',
+            message: `Drift-prone count "${m[0]}" outside CLAUDE.md. Counts live only in CLAUDE.md; replace with qualitative phrasing or remove.`,
+          });
+        }
+      }
+    }
+  }
+
+  const fileCount = files.length;
+  const result = {
+    directory: dir,
+    file_count: fileCount,
+    violation_count: violations.length,
+    violations,
+  };
+
+  if (opts.raw) {
+    if (violations.length === 0) {
+      process.stdout.write(`OK — ${fileCount} files scanned, no count violations\n`);
+    } else {
+      for (const v of violations) {
+        process.stdout.write(`${v.file}:${v.line}:${v.column} — ${v.match} (${v.label})\n`);
+      }
+      process.stdout.write(`\n${violations.length} violation(s) across ${fileCount} files\n`);
+    }
+  } else {
+    output(result, false);
+  }
+  process.exit(violations.length > 0 ? 1 : 0);
+}
+
+module.exports = {
+  cmdDocLint,
+  cmdDocLintSchemaCheck,
+  cmdDocLintCounts,
+  isCountAllowed,
+  COUNT_PATTERNS,
+  DEFAULT_SCHEMA_PATH,
+};