azcodr 1.5.2 → 2.1.0

package/scripts/validate/text.js

@@ -0,0 +1,27 @@
+/**
+ * Text helpers shared by the validator phases.
+ *
+ * Both exist because generated documentation routinely contains ADR headings,
+ * rule headers, and Core Mandate lines inside examples. Matching the raw file
+ * would mistake documentation ABOUT the contract for the contract itself.
+ */
+
+export function stripHtmlComments(text) {
+  // Remove HTML comments, tolerating unclosed ones. A stray `<!--` from an
+  // editor's "comment selection" must not silently hide every ADR after it.
+  return text
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<!--[\s\S]*$/, '');
+}
+
+/**
+ * Removes fenced code blocks so that examples inside documentation are not
+ * mistaken for real content. Without this, a rule file whose only H1 and
+ * "Core Mandate" lines sit inside a ```md fence satisfies both checks, and a
+ * `#### ADR-001` shown as an example is counted as a real decision.
+ */
+export function stripFencedCode(text) {
+  return text.replace(/^([ \t]*)(```|~~~)[\s\S]*?^\1\2[ \t]*$/gm, '');
+}
+
+export default { stripHtmlComments, stripFencedCode };

package/scripts/validate-cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry for the agentic-architecture validator.
+ *
+ * Deliberately separate from scripts/validate.js: keeping the library free of a
+ * `require.main` guard means requiring it never validates or exits, and it
+ * avoids a permanently-unreachable branch that blocks the 100% coverage gate.
+ */
+import { main } from './validate.js';
+
+main();

package/scripts/validate.js

@@ -1,258 +1,158 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-function parseArgs(argv) {
-  let root = '';
-  for (const arg of argv) {
-    if (arg === '--fix') continue;
-    if (!root) root = arg;
-  }
-  return root || process.cwd();
-}
-
-function main() {
-  const workspaceRoot = path.resolve(parseArgs(process.argv.slice(2)));
-  let errors = 0;
-  let warnings = 0;
-
-  const pass = (msg) => console.log(`  ✅ ${msg}`);
-  const warn = (msg) => { warnings += 1; console.log(`  ⚠️  ${msg}`); };
-  const fail = (msg) => { errors += 1; console.log(`  ❌ ${msg}`); };
-
-  console.log(`🔍 Validating Agentic Architecture in: ${workspaceRoot}`);
-  console.log('--------------------------------------------------------------');
-
-  console.log('1. Checking Root Configuration & Symlinks...');
-  const agentsFile = path.join(workspaceRoot, 'AGENTS.md');
-  if (!fs.existsSync(agentsFile)) {
-    fail(`Missing root AGENTS.md at ${agentsFile}`);
-  } else {
-    pass('AGENTS.md exists.');
-    const lines = fs.readFileSync(agentsFile, 'utf-8').split('\n').length;
-    if (lines <= 120) pass(`AGENTS.md line count is lean: ${lines} lines (<= 120).`);
-    else if (lines <= 150) warn(`AGENTS.md line count is getting large: ${lines} lines (warn > 120).`);
-    else fail(`AGENTS.md exceeds maximum line limit: ${lines} lines (max 150).`);
-  }
-
-  const agentsContent = fs.existsSync(agentsFile) ? fs.readFileSync(agentsFile, 'utf-8') : '';
-
-  function isValidAgentsTarget(target) {
-    const normalized = target.replace(/\\/g, '/');
-    const rootNormalized = agentsFile.replace(/\\/g, '/');
-    return normalized === 'AGENTS.md' || normalized === './AGENTS.md' || normalized === rootNormalized;
-  }
-
-  function checkParity(filePath, label, allowCopyFallback) {
-    let stat = null;
-    try { stat = fs.lstatSync(filePath); } catch { fail(`${label} is missing.`); return; }
-    if (stat.isSymbolicLink()) {
-      let target = '';
-      try { target = fs.readlinkSync(filePath); } catch { fail(`${label} readlink failed.`); return; }
-      const normalized = target.replace(/\\/g, '/');
-      const ok = label.endsWith('copilot-instructions.md')
-        ? (normalized === '../AGENTS.md' || normalized === agentsFile.replace(/\\/g, '/') || normalized === 'AGENTS.md')
-        : isValidAgentsTarget(target);
-      if (ok) pass(`${label} is a valid symlink to AGENTS.md.`);
-      else fail(`${label} points to '${target}' instead of 'AGENTS.md'.`);
-      return;
-    }
-    if (stat.isFile()) {
-      const content = fs.readFileSync(filePath, 'utf-8');
-      const trimmed = content.trim();
-      if (trimmed === 'AGENTS.md' || trimmed === './AGENTS.md' || trimmed === agentsFile) {
-        pass(`${label} is a text pointer to AGENTS.md (symlink fallback).`);
-        return;
-      }
-      if (label.endsWith('copilot-instructions.md') && content.includes('AGENTS.md')) {
-        pass(`${label} references AGENTS.md (symlink fallback).`);
-        return;
-      }
-      if (allowCopyFallback && agentsContent && content === agentsContent) {
-        warn(`${label} is a byte-identical copy of AGENTS.md (Windows symlink fallback; drift risk).`);
-        return;
-      }
-      if (label === 'agents.md') {
-        try {
-          const entries = fs.readdirSync(workspaceRoot);
-          if (!entries.includes('agents.md') && entries.includes('AGENTS.md')) {
-            pass('agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem).');
-            return;
-          }
-        } catch { /* fall through */ }
-      }
-      fail(`${label} is not a symbolic link.`);
-      return;
-    }
-    fail(`${label} is neither a symlink nor a regular file.`);
-  }
-
-  checkParity(path.join(workspaceRoot, 'CLAUDE.md'), 'CLAUDE.md', true);
-  const lowerPath = path.join(workspaceRoot, 'agents.md');
-  try {
-    const entries = fs.readdirSync(workspaceRoot);
-    const hasUpper = entries.includes('AGENTS.md');
-    const hasLowerExact = entries.includes('agents.md');
-    if (hasUpper && !hasLowerExact) {
-      let appearsSame = false;
-      try { appearsSame = fs.existsSync(lowerPath); } catch { appearsSame = false; }
-      if (appearsSame) {
-        pass('agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem).');
-      } else {
-        // Case-sensitive filesystem gap (agents.md cannot be committed alongside
-        // AGENTS.md from case-insensitive systems): restore parity in place.
-        let created = false;
-        try { fs.symlinkSync('AGENTS.md', lowerPath); created = true; }
-        catch {
-          try { fs.writeFileSync(lowerPath, 'AGENTS.md\n', 'utf-8'); created = true; }
-          catch { created = false; }
-        }
-        if (created) pass('Created agents.md parity link to AGENTS.md (case-sensitive filesystem).');
-        checkParity(lowerPath, 'agents.md', true);
-      }
-    } else {
-      checkParity(lowerPath, 'agents.md', true);
-    }
-  } catch {
-    checkParity(lowerPath, 'agents.md', true);
-  }
-  checkParity(path.join(workspaceRoot, 'GEMINI.md'), 'GEMINI.md', true);
-  checkParity(path.join(workspaceRoot, '.cursorrules'), '.cursorrules', true);
-  checkParity(path.join(workspaceRoot, '.windsurfrules'), '.windsurfrules', true);
-  const githubDir = path.join(workspaceRoot, '.github');
-  if (fs.existsSync(githubDir) && fs.statSync(githubDir).isDirectory()) {
-    const copilot = path.join(githubDir, 'copilot-instructions.md');
-    if (fs.existsSync(copilot)) {
-      checkParity(copilot, '.github/copilot-instructions.md', true);
-    } else {
-      warn('.github/copilot-instructions.md is missing (run scaffold to restore harness parity).');
-    }
-    if (!fs.existsSync(path.join(githubDir, 'workflows'))) {
-      warn('.github/workflows is missing (CI will not run in scaffolded projects).');
-    }
-  }
-
-  if (fs.existsSync(path.join(workspaceRoot, '.gitignore'))) pass('.gitignore exists.');
-  else fail('Missing .gitignore');
-
-  console.log('');
-  console.log('2. Checking Progressive Disclosure Rules...');
-  const rulesDir = path.join(workspaceRoot, 'docs', 'rules');
-  if (!fs.existsSync(rulesDir)) {
-    fail(`Missing docs/rules directory at ${rulesDir}`);
-  } else {
-    const files = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md'));
-    let count = 0;
-    for (const name of files) {
-      count += 1;
-      const fp = path.join(rulesDir, name);
-      const content = fs.readFileSync(fp, 'utf-8');
-      const stat = fs.statSync(fp);
-      if (!/^# /m.test(content)) fail(`Rule ${name} missing H1 header (# Title)`);
-      if (!/^> \*\*Core Mandate:\*\*/m.test(content)) warn(`Rule ${name} missing standardized '> **Core Mandate:**' summary`);
-      if (stat.size > 24000) warn(`Rule ${name} exceeds 24KB token-economy cap (${stat.size} bytes)`);
-    }
-    pass(`Validated ${count} modular rule files in docs/rules/.`);
-  }
-
-  console.log('');
-  console.log('3. Checking Specialized Skills (.agents/skills)...');
-  const skillsDir = path.join(workspaceRoot, '.agents', 'skills');
-  if (!fs.existsSync(skillsDir)) {
-    fail(`Missing .agents/skills directory at ${skillsDir}`);
-  } else {
-    const folders = fs.readdirSync(skillsDir).filter((f) => fs.statSync(path.join(skillsDir, f)).isDirectory());
-    let count = 0;
-    for (const skill of folders) {
-      count += 1;
-      const skillFile = path.join(skillsDir, skill, 'SKILL.md');
-      if (!fs.existsSync(skillFile)) { fail(`Skill '${skill}' missing SKILL.md`); continue; }
-      const content = fs.readFileSync(skillFile, 'utf-8');
-      const lines = content.split('\n');
-      if (lines[0].trim() !== '---') { fail(`Skill '${skill}' missing opening front matter delimiter (---)`); continue; }
-      const closing = lines.slice(1).findIndex((l) => l.trim() === '---');
-      if (closing === -1) fail(`Skill '${skill}' missing closing front matter delimiter (---)`);
-      const nameMatch = content.match(/^name:\s*(.+)$/m);
-      if (!nameMatch || nameMatch[1].trim() !== skill) fail(`Skill '${skill}' front matter 'name:' does not match directory name`);
-      const descMatch = content.match(/^description:\s*(.+)$/m);
-      const desc = descMatch ? descMatch[1].trim() : '';
-      if (!desc) {
-        fail(`Skill '${skill}' missing front matter 'description:'`);
-      } else {
-        if (!/^Use when/.test(desc)) warn(`Skill '${skill}' description should start with imperative 'Use when...'`);
-        if (!/do not use/i.test(desc)) warn(`Skill '${skill}' description should specify negative boundaries ('Do not use for...')`);
-        if (desc.length > 1024) fail(`Skill '${skill}' description exceeds 1024 chars (${desc.length} chars)`);
-      }
-      if (lines.length > 500) warn(`Skill '${skill}' exceeds 500 lines (${lines.length} lines). Offload details to references/.`);
-      else pass(`Skill '${skill}': ${lines.length} lines, description valid (${desc.length} chars).`);
-      if (!/What NOT to do/i.test(content) && !/Gotchas/i.test(content)) {
-        warn(`Skill '${skill}' missing mandatory 'Gotchas & What NOT to Do' section`);
-      }
-    }
-    pass(`Validated ${count} skills in .agents/skills/.`);
-  }
-
-  console.log('');
-  console.log('4. Checking Markdown Internal Links & Cross-References...');
-  const broken = [];
-  let totalLinks = 0;
-  function walk(dir) {
-    let entries = [];
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-    for (const entry of entries) {
-      if (entry.name === '.git' || entry.name === 'node_modules') continue;
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.isFile() && entry.name.endsWith('.md')) checkFile(full);
-    }
-  }
-  function checkFile(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const dir = path.dirname(filePath);
-    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
-    let m;
-    while ((m = regex.exec(content)) !== null) {
-      const target = m[2].trim();
-      if (/^(https?:|mailto:|#|conversation:\/\/|file:\/\/)/.test(target)) continue;
-      const clean = target.split('#')[0];
-      if (!clean) continue;
-      totalLinks += 1;
-      if (!fs.existsSync(path.normalize(path.join(dir, clean)))) {
-        broken.push(`${path.relative(workspaceRoot, filePath)} -> ${target}`);
-      }
-    }
-  }
-  walk(workspaceRoot);
-  if (broken.length === 0) pass(`Validated ${totalLinks} internal links across workspace (0 broken links).`);
-  else for (const b of broken) fail(`Broken markdown link: ${b}`);
-
-  console.log('');
-  console.log('5. Checking Memory & ADR Ledger...');
-  const memoryFile = path.join(workspaceRoot, 'memory.md');
-  if (!fs.existsSync(memoryFile)) {
-    fail('Missing memory.md ADR ledger.');
-  } else {
-    const mem = fs.readFileSync(memoryFile, 'utf-8');
-    const withoutComments = mem.replace(/<!--[\s\S]*?-->/g, '');
-    if (!/^# /m.test(mem)) fail('memory.md missing H1 header');
-    else if (/#### ADR-/.test(withoutComments)) pass('memory.md contains ADR entries with valid envelope.');
-    else pass('memory.md is a clean slate (no ADRs yet; record ADR-001 during /lets-build).');
-    if (/ADR-025|ADR-028/.test(withoutComments) && /azcodr/i.test(mem)) {
-      warn('memory.md may contain template-internal ADRs; fresh projects must start at ADR-001.');
-    }
-  }
-
-  console.log('');
-  console.log('--------------------------------------------------------------');
-  if (errors === 0) {
-    console.log(`🎉 SUCCESS: All agentic configurations are valid and healthy! (${warnings} warnings)`);
-    process.exit(0);
-  } else {
-    console.log(`🚨 FAILURE: Found ${errors} error(s) and ${warnings} warning(s) in agentic configurations.`);
-    process.exit(1);
-  }
-}
-
-main();
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { createReporter, readTextOrFail, walkMarkdown } from './validate/io.js';
+import * as textHelpers from './validate/text.js';
+import * as parityHelpers from './validate/parity.js';
+import { parseAdrLedger, checkAdrIndexConsistency, checkGlossaryPopulated } from './validate/adr.js';
+import { phaseRootConfig } from './validate/root.js';
+import { phaseRules } from './validate/rules.js';
+import { phaseSkills } from './validate/skills.js';
+import { phaseLinks } from './validate/links.js';
+
+/**
+ * NOTE: this module is a library. It never self-executes, so importing it from
+ * a test or another tool cannot trigger validation or call process.exit().
+ * The CLI entry point lives in `scripts/validate-cli.js`.
+ */
+
+function parseArgs(argv) {
+  let root = '';
+  for (const arg of argv) {
+    if (arg === '--fix') continue;
+    if (!root) root = arg;
+  }
+  return root || process.cwd();
+}
+
+function reportMemoryLedger(mem, ctx) {
+  const { entryIds } = parseAdrLedger(mem);
+  if (!/^# /m.test(mem)) ctx.fail('memory.md missing H1 header');
+  // Uses the same parser as phase 6. The previous unanchored
+  // `/#### ADR-/` disagreed with phase 6's anchored form, so the validator
+  // contradicted itself within a single run.
+  else if (entryIds.length > 0) ctx.pass('memory.md contains ADR entries with valid envelope.');
+  else ctx.pass('memory.md is a clean slate (no ADRs yet; record ADR-001 during /lets-build).');
+  // Template ADRs start well past ADR-024. Match any ID >= 25 regardless of
+  // zero padding.
+  const highestAdr = Math.max(0, ...entryIds);
+  if (highestAdr >= 25 && /azcodr/i.test(mem)) {
+    ctx.warn('memory.md may contain template-internal ADRs; fresh projects must start at ADR-001.');
+  }
+}
+
+function phaseMemory(ctx) {
+  ctx.log('');
+  ctx.heading('5. Checking Memory & ADR Ledger...');
+  const memoryFile = path.join(ctx.workspaceRoot, 'memory.md');
+  if (!fs.existsSync(memoryFile)) {
+    ctx.fail('Missing memory.md ADR ledger.');
+    return;
+  }
+  // readTextOrFail already reported any read failure; skip the analysis.
+  const mem = readTextOrFail(memoryFile, 'memory.md', ctx.fail);
+  if (mem !== null) reportMemoryLedger(mem, ctx);
+}
+
+function phaseLedger(ctx) {
+  ctx.log('');
+  ctx.heading('6. Checking ADR Index Consistency...');
+  const consistency = checkAdrIndexConsistency(ctx.workspaceRoot, ctx.fail, ctx.pass);
+  if (consistency === 'indexed' || consistency === 'inconsistent') {
+    checkGlossaryPopulated(ctx.workspaceRoot, { fail: ctx.fail, pass: ctx.pass, warn: ctx.warn });
+  }
+}
+
+function buildValidationContext(workspaceRoot, reporter, counts) {
+  return {
+    workspaceRoot,
+    agentsFile: '',
+    agentsContent: '',
+    pass: reporter.pass,
+    warn: (msg) => { counts.warnings += 1; reporter.warn(msg); },
+    fail: (msg) => { counts.errors += 1; reporter.fail(msg); },
+    log: reporter.log,
+    heading: reporter.heading,
+    broken: [],
+    linkCount: 0,
+    visitedRealPaths: new Set()
+  };
+}
+
+function reportSummary(counts, reporter) {
+  reporter.log('');
+  reporter.log('--------------------------------------------------------------');
+  if (counts.errors === 0) {
+    reporter.log(`🎉 SUCCESS: All agentic configurations are valid and healthy! (${counts.warnings} warnings)`);
+  } else {
+    reporter.log(`🚨 FAILURE: Found ${counts.errors} error(s) and ${counts.warnings} warning(s) in agentic configurations.`);
+  }
+}
+
+function runValidation(workspaceRoot, reporter = createReporter()) {
+  // Counters live here, not on the reporter: an injected reporter only needs
+  // pass/warn/fail to observe outcomes, and the tally must not depend on the
+  // reporter's shape.
+  const counts = { errors: 0, warnings: 0 };
+  const ctx = buildValidationContext(workspaceRoot, reporter, counts);
+  reporter.heading(`🔍 Validating Agentic Architecture in: ${workspaceRoot}`);
+  reporter.log('--------------------------------------------------------------');
+  phaseRootConfig(ctx);
+  const validatedRules = phaseRules(ctx);
+  const validatedSkills = phaseSkills(ctx);
+  phaseLinks(ctx);
+  phaseMemory(ctx);
+  phaseLedger(ctx);
+  reportSummary(counts, reporter);
+  return {
+    errors: counts.errors,
+    warnings: counts.warnings,
+    validatedRules,
+    validatedSkills,
+    totalLinks: ctx.linkCount,
+    brokenLinks: ctx.broken
+  };
+}
+
+function main(argv = process.argv.slice(2), exit = process.exit) {
+  const workspaceRoot = path.resolve(parseArgs(argv));
+  const result = runValidation(workspaceRoot);
+  return exit(result.errors === 0 ? 0 : 1);
+}
+
+const { evaluateParityTarget, isValidAgentsTarget, createLowercaseParityLink } = parityHelpers;
+const { stripHtmlComments, stripFencedCode } = textHelpers;
+
+export {
+  runValidation,
+  parseArgs,
+  createReporter,
+  main,
+  parseAdrLedger,
+  checkAdrIndexConsistency,
+  checkGlossaryPopulated,
+  evaluateParityTarget,
+  isValidAgentsTarget,
+  createLowercaseParityLink,
+  stripHtmlComments,
+  stripFencedCode,
+  walkMarkdown
+};
+
+export default {
+  runValidation,
+  parseArgs,
+  createReporter,
+  main,
+  parseAdrLedger,
+  checkAdrIndexConsistency,
+  checkGlossaryPopulated,
+  evaluateParityTarget,
+  isValidAgentsTarget,
+  createLowercaseParityLink,
+  stripHtmlComments,
+  stripFencedCode,
+  walkMarkdown
+};

package/src/cli-parse.ts

@@ -0,0 +1,77 @@
+/**
+ * Argument parsing for the azcodr CLI.
+ *
+ * Table-driven: every boolean flag is one Map entry, so adding a flag cannot
+ * raise the complexity of the parser itself.
+ */
+
+export interface CliParsedOptions {
+  targetDir: string | null;
+  force: boolean;
+  noGit: boolean;
+  dryRun: boolean;
+  silent: boolean;
+  terminal: 'help' | 'version' | 'unknown-flag' | 'extra-arg' | null;
+  message?: string;
+}
+
+export type BooleanFlagKey = 'force' | 'noGit' | 'dryRun' | 'silent';
+
+export function emptyOptions(): Omit<CliParsedOptions, 'terminal' | 'message'> {
+  return { targetDir: null, force: false, noGit: false, dryRun: false, silent: false };
+}
+
+export const BOOLEAN_FLAGS = new Map<string, BooleanFlagKey>([
+  ['-f', 'force'],
+  ['--force', 'force'],
+  ['--no-git', 'noGit'],
+  ['-d', 'dryRun'],
+  ['--dry-run', 'dryRun'],
+  ['-s', 'silent'],
+  ['--silent', 'silent']
+]);
+
+export interface ArgOutcome {
+  terminal: 'help' | 'version' | 'unknown-flag' | 'extra-arg' | null;
+  message?: string;
+}
+
+export function applyArg(
+  state: Omit<CliParsedOptions, 'terminal' | 'message'>,
+  arg: string
+): ArgOutcome {
+  if (arg === '-h' || arg === '--help') return { terminal: 'help' };
+  if (arg === '-v' || arg === '--version') return { terminal: 'version' };
+  const flag = BOOLEAN_FLAGS.get(arg);
+  if (flag !== undefined) {
+    state[flag] = true;
+    return { terminal: null };
+  }
+  if (arg.startsWith('-')) {
+    return {
+      terminal: 'unknown-flag',
+      message: `Unknown argument '${arg}'. Run 'npx azcodr --help' for available options.`
+    };
+  }
+  if (!state.targetDir) {
+    state.targetDir = arg;
+    return { terminal: null };
+  }
+  return {
+    terminal: 'extra-arg',
+    message: `Unexpected argument '${arg}'. Run 'npx azcodr --help' for available options.`
+  };
+}
+
+export function parseArgs(rawArgs: readonly string[]): CliParsedOptions {
+  const state = emptyOptions();
+  for (const arg of rawArgs) {
+    const outcome = applyArg(state, arg);
+    if (outcome.terminal !== null) {
+      return { ...state, terminal: outcome.terminal, message: outcome.message };
+    }
+  }
+  return { ...state, terminal: null, message: undefined };
+}
+
+export default { emptyOptions, BOOLEAN_FLAGS, applyArg, parseArgs };