@ibalzam/codejitsu-core 0.3.3 → 0.5.0

package/bin/codejitsu.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { runBlog } from '../modules/cli/src/blog.mjs';
+import { runAudit } from '../modules/audit/src/run.mjs';
+
+const subcommand = process.argv[2];
+const rest = process.argv.slice(3);
+
+const COMMANDS = {
+  'blog:list': () => runBlog('blog:list'),
+  'blog:drafts': () => runBlog('blog:drafts'),
+  audit: () => {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        live: { type: 'string' },
+        a11y: { type: 'boolean' },
+        ai: { type: 'boolean' },
+      },
+      allowPositionals: true,
+    });
+    return runAudit({ liveUrl: values.live, a11y: values.a11y, ai: values.ai });
+  },
+  // Aliases for the existing standalone bins
+  llms: () => import('../modules/llms/bin/generate.mjs'),
+  'optimize-images': () => import('../modules/images/bin/optimize.mjs'),
+  check: () => import('../checklist/bin/run.mjs'),
+};
+
+if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+const handler = COMMANDS[subcommand];
+if (!handler) {
+  console.error(`Unknown subcommand: ${subcommand}\n`);
+  printHelp();
+  process.exit(1);
+}
+
+try {
+  await handler();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+
+function printHelp() {
+  console.log(`\nUsage: codejitsu <subcommand> [flags]\n`);
+  console.log(`Subcommands:`);
+  console.log(`  blog:list           List every non-draft post with URL + image check`);
+  console.log(`  blog:drafts         List future-dated (pending) posts only`);
+  console.log(``);
+  console.log(`  audit               Run pre-delivery audit. Flags:`);
+  console.log(`    --live <url>      Add live-URL checks (SSL, headers, 404, broken links)`);
+  console.log(`    --a11y            Add axe-core WCAG 2.1 AA scan (with --live)`);
+  console.log(`    --ai              Add Claude-powered content audit (uses 'claude -p')`);
+  console.log(``);
+  console.log(`  llms                Generate public/llms.txt and public/llms-full.txt`);
+  console.log(`  optimize-images     Optimize images per codejitsu.config`);
+  console.log(`  check               Run minimal pre-build checklist`);
+  console.log(``);
+  console.log(`All commands read codejitsu.config.{ts,mjs,json} from the current directory.`);
+}

package/modules/audit/src/a11y/runner.mjs

@@ -0,0 +1,146 @@
+import { spawn } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { pass, fail, warn, info } from '../util.mjs';
+
+/**
+ * Accessibility audit via `@axe-core/cli`. Spawns the CLI against the live URL,
+ * parses its JSON report, and groups violations by impact (critical / serious /
+ * moderate / minor) for the audit summary.
+ *
+ * Requires either:
+ *   - `@axe-core/cli` installed in the site (`npm install -D @axe-core/cli`), or
+ *   - network access for npx to fetch it on demand.
+ *
+ * Uses real headless Chrome (via Puppeteer, bundled by @axe-core/cli) so the
+ * test reflects WCAG 2.1 AA verdicts on the rendered page (not raw HTML).
+ */
+export async function runA11y(ctx) {
+  const { liveUrl } = ctx;
+  if (!liveUrl) {
+    return [info('a11y skipped — provide --live <url> to enable')];
+  }
+
+  const reportFile = path.join(os.tmpdir(), `codejitsu-axe-${Date.now()}.json`);
+  const reportDir = path.dirname(reportFile);
+
+  let stderr = '';
+  let exitCode;
+  try {
+    const result = await runCmd('npx', [
+      '--yes',
+      '@axe-core/cli',
+      liveUrl,
+      '--dir', reportDir,
+      '--save', path.basename(reportFile),
+      '--exit',
+    ]);
+    exitCode = result.code;
+    stderr = result.stderr;
+  } catch (err) {
+    return [warn('Could not run @axe-core/cli', String(err.message ?? err))];
+  }
+
+  // Find the file axe wrote. The --save option names it; --dir specifies its dir.
+  let parsed;
+  try {
+    if (!fs.existsSync(reportFile)) {
+      // axe sometimes writes a slightly different filename. Try the dir.
+      const candidates = fs.readdirSync(reportDir).filter((n) => n.startsWith('codejitsu-axe-') && n.endsWith('.json'));
+      if (candidates.length === 0) {
+        return [warn('axe-core ran but produced no JSON report', stderr.slice(0, 400) || `exit code: ${exitCode}`)];
+      }
+      const newest = candidates.map((n) => path.join(reportDir, n)).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0];
+      parsed = JSON.parse(fs.readFileSync(newest, 'utf8'));
+    } else {
+      parsed = JSON.parse(fs.readFileSync(reportFile, 'utf8'));
+    }
+  } catch (err) {
+    return [warn('Could not parse axe-core JSON output', err.message)];
+  }
+
+  const results = [];
+  // axe report is an array of per-URL test results.
+  const reports = Array.isArray(parsed) ? parsed : [parsed];
+
+  // Aggregate counts.
+  const violationsByImpact = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  const ruleHits = new Map();         // rule id → { impact, help, count, exampleUrl }
+  let totalPasses = 0;
+  let totalIncomplete = 0;
+
+  for (const r of reports) {
+    totalPasses += (r.passes ?? []).length;
+    totalIncomplete += (r.incomplete ?? []).length;
+
+    for (const v of r.violations ?? []) {
+      const impact = v.impact ?? 'moderate';
+      violationsByImpact[impact] = (violationsByImpact[impact] ?? 0) + (v.nodes?.length ?? 1);
+      const existing = ruleHits.get(v.id);
+      if (existing) {
+        existing.count += v.nodes?.length ?? 1;
+      } else {
+        ruleHits.set(v.id, {
+          impact,
+          help: v.help,
+          helpUrl: v.helpUrl,
+          count: v.nodes?.length ?? 1,
+          exampleUrl: r.url ?? liveUrl,
+        });
+      }
+    }
+  }
+
+  const totalViolations = Object.values(violationsByImpact).reduce((a, b) => a + b, 0);
+
+  results.push(info(
+    `axe-core checked ${reports.length} URL(s) — ${totalPasses} rules passed, ${totalViolations} violations, ${totalIncomplete} need manual review`
+  ));
+
+  // Per-impact severity buckets.
+  const impactMap = [
+    { key: 'critical', label: 'critical', sev: 'fail' },
+    { key: 'serious',  label: 'serious',  sev: 'fail' },
+    { key: 'moderate', label: 'moderate', sev: 'warn' },
+    { key: 'minor',    label: 'minor',    sev: 'warn' },
+  ];
+
+  for (const { key, label, sev } of impactMap) {
+    const count = violationsByImpact[key] ?? 0;
+    if (count === 0) {
+      results.push(pass(`No ${label} a11y violations`));
+    } else {
+      const examples = [...ruleHits.entries()]
+        .filter(([, info]) => info.impact === key)
+        .slice(0, 5)
+        .map(([id, info]) => `${id} (×${info.count}) — ${info.help}`);
+      const result = sev === 'fail' ? fail : warn;
+      results.push(result(`${count} ${label} a11y violation${count === 1 ? '' : 's'}`, examples));
+    }
+  }
+
+  return results;
+}
+
+function runCmd(cmd, args, timeoutMs = 180_000) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => { stdout += d.toString(); });
+    proc.stderr.on('data', (d) => { stderr += d.toString(); });
+    const t = setTimeout(() => {
+      proc.kill();
+      reject(new Error(`${cmd} timed out after ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+    proc.on('error', (err) => {
+      clearTimeout(t);
+      reject(err);
+    });
+    proc.on('close', (code) => {
+      clearTimeout(t);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}

package/modules/audit/src/ai/runner.mjs

@@ -0,0 +1,176 @@
+import { spawn } from 'child_process';
+import { pass, fail, warn, info } from '../util.mjs';
+
+/**
+ * AI-tier audit via `claude -p` headless. Samples a few pages, asks Claude to
+ * proofread + score AI-friendliness, displays findings in the audit summary.
+ *
+ * Uses --bare mode and --model sonnet to minimize context cost. A typical
+ * audit (3 sample pages) costs ~$0.02–0.05.
+ */
+export async function runAi(ctx) {
+  const { htmlFiles, ai } = ctx;
+  if (!ai) return [];
+
+  // Verify claude is in PATH.
+  const claudeAvailable = await commandExists('claude');
+  if (!claudeAvailable) {
+    return [warn(
+      'AI tier skipped — `claude` CLI not in PATH',
+      'Install Claude Code: https://claude.com/claude-code'
+    )];
+  }
+
+  const results = [];
+  const sample = pickSample(htmlFiles, 3);
+
+  results.push(info(`AI sampling ${sample.length} pages via claude -p (--model sonnet)`));
+
+  let totalIssues = 0;
+  let totalCost = 0;
+
+  for (const f of sample) {
+    const text = extractMainText(f.content);
+    if (text.length < 200) {
+      results.push(info(`Skipped ${f.relPath} (too short: ${text.length} chars)`));
+      continue;
+    }
+
+    const proofread = await callClaude(buildProofreadPrompt(text), f.relPath);
+    if (proofread.error) {
+      results.push(warn(`Proofread failed: ${f.relPath}`, proofread.error));
+      continue;
+    }
+    totalCost += proofread.costUsd ?? 0;
+
+    if (proofread.issues.length === 0) {
+      results.push(pass(`Proofread clean: ${f.relPath}`));
+    } else {
+      totalIssues += proofread.issues.length;
+      const details = proofread.issues.slice(0, 5).map((i) => `${i.severity}: ${i.message}`);
+      const sev = proofread.issues.some((i) => i.severity === 'fail') ? 'fail' : 'warn';
+      const result = sev === 'fail' ? fail : warn;
+      results.push(result(
+        `Proofread: ${proofread.issues.length} issues in ${f.relPath}`,
+        details
+      ));
+    }
+  }
+
+  if (totalCost > 0) {
+    results.push(info(`AI tier total cost: ~$${totalCost.toFixed(3)}`));
+  }
+
+  return results;
+}
+
+function buildProofreadPrompt(text) {
+  return `Read the webpage content between <PAGE> tags. Identify ONLY:
+- Typos / misspellings
+- Grammar errors
+- Sentences that are objectively broken or incoherent
+
+DO NOT flag style preferences, alternative phrasings, or things you'd just personally prefer.
+
+Output STRICT JSON, no markdown, no preamble. Schema:
+{"issues": [{"severity": "fail" | "warn", "message": "specific issue with quoted text"}]}
+
+If no issues: {"issues": []}
+
+<PAGE>
+${text}
+</PAGE>`;
+}
+
+async function callClaude(prompt, label) {
+  try {
+    // Note: --bare requires ANTHROPIC_API_KEY env var. We don't use it so users
+    // on OAuth (Claude Code subscribers) still work. Cost is higher per call
+    // (~$0.07 with sonnet) but the audit only samples a few pages.
+    const out = await runCmd(
+      'claude',
+      [
+        '--model', 'sonnet',
+        '--system-prompt', 'You are a senior copy editor. Output strict JSON only, no preamble.',
+        '--disallowedTools', 'Bash,Edit,Write,Read,Glob,Grep,Agent',
+        '-p',
+        '--output-format', 'json',
+        prompt,
+      ],
+      120_000
+    );
+
+    if (out.code !== 0) {
+      return { error: `claude exit ${out.code}: ${out.stderr.slice(0, 200)}` };
+    }
+
+    // claude -p --output-format json returns an envelope { result, total_cost_usd, ... }
+    let envelope;
+    try { envelope = JSON.parse(out.stdout); }
+    catch { return { error: 'Could not parse claude envelope JSON' }; }
+
+    const inner = (envelope.result ?? '').trim();
+    const costUsd = envelope.total_cost_usd;
+
+    // Strip code fences if Claude added them despite the instruction.
+    const cleaned = inner.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
+    let parsed;
+    try { parsed = JSON.parse(cleaned); }
+    catch { return { error: `Claude returned non-JSON: ${cleaned.slice(0, 100)}` }; }
+
+    return { issues: parsed.issues ?? [], costUsd };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+function pickSample(files, n) {
+  const sample = [];
+  const home = files.find((f) => f.relPath === 'index.html');
+  if (home) sample.push(home);
+  for (const f of files) {
+    if (sample.length >= n) break;
+    if (sample.includes(f)) continue;
+    if (f.relPath === '404.html') continue;
+    sample.push(f);
+  }
+  return sample;
+}
+
+function extractMainText(html) {
+  let cleaned = html
+    .replace(/<head[\s\S]*?<\/head>/gi, '')
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<nav[\s\S]*?<\/nav>/gi, '')
+    .replace(/<footer[\s\S]*?<\/footer>/gi, '')
+    .replace(/<header[\s\S]*?<\/header>/gi, '');
+  const main = cleaned.match(/<main[\s\S]*?<\/main>/i);
+  if (main) cleaned = main[0];
+  const text = cleaned.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+  return text.split(/\s+/).slice(0, 2500).join(' ');
+}
+
+async function commandExists(cmd) {
+  return new Promise((resolve) => {
+    const proc = spawn('which', [cmd], { stdio: 'ignore' });
+    proc.on('close', (code) => resolve(code === 0));
+    proc.on('error', () => resolve(false));
+  });
+}
+
+function runCmd(cmd, args, timeoutMs = 120_000) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => { stdout += d.toString(); });
+    proc.stderr.on('data', (d) => { stderr += d.toString(); });
+    const t = setTimeout(() => {
+      proc.kill();
+      reject(new Error(`${cmd} timed out`));
+    }, timeoutMs);
+    proc.on('error', (err) => { clearTimeout(t); reject(err); });
+    proc.on('close', (code) => { clearTimeout(t); resolve({ code, stdout, stderr }); });
+  });
+}

package/modules/audit/src/groups/ai-discoverability.mjs

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import { pass, fail, warn, info } from '../util.mjs';
+
+const AI_BOTS = [
+  'GPTBot',          // OpenAI
+  'ClaudeBot',       // Anthropic
+  'PerplexityBot',   // Perplexity
+  'CCBot',           // Common Crawl (used by many AI training pipelines)
+  'Google-Extended', // Google (Bard / Gemini)
+];
+
+export async function runAi(ctx) {
+  const { distDir } = ctx;
+  const results = [];
+
+  const robotsPath = path.join(distDir, 'robots.txt');
+  if (!fs.existsSync(robotsPath)) {
+    results.push(warn('robots.txt missing — cannot check AI bot rules'));
+    return results;
+  }
+
+  const robots = fs.readFileSync(robotsPath, 'utf8');
+  const mentioned = AI_BOTS.filter((bot) =>
+    new RegExp(`User-agent:\\s*${bot}`, 'i').test(robots)
+  );
+
+  if (mentioned.length === 0) {
+    results.push(info(
+      'robots.txt has no explicit AI crawler rules',
+      'Default = allow. Add `User-agent: GPTBot` (etc.) with Allow/Disallow if you want explicit control.'
+    ));
+  } else {
+    results.push(pass(`robots.txt mentions AI bots: ${mentioned.join(', ')}`));
+  }
+
+  // llms.txt presence checked in structure.mjs; here check content quality.
+  const llmsPath = path.join(distDir, 'llms.txt');
+  if (fs.existsSync(llmsPath)) {
+    const llms = fs.readFileSync(llmsPath, 'utf8');
+    const lines = llms.split('\n');
+    const headings = lines.filter((l) => l.startsWith('## ')).length;
+    results.push(
+      headings >= 3
+        ? pass(`llms.txt has ${headings} sections`)
+        : warn(`llms.txt has only ${headings} sections — consider expanding`)
+    );
+  }
+
+  return results;
+}

package/modules/audit/src/groups/analytics.mjs

@@ -0,0 +1,54 @@
+import { pass, fail, warn, info } from '../util.mjs';
+
+const PROVIDERS = [
+  { key: 'ga4',       label: 'GA4',            pattern: /G-[A-Z0-9]{6,}/, },
+  { key: 'gtm',       label: 'GTM',            pattern: /GTM-[A-Z0-9]{6,}/, },
+  { key: 'googleAds', label: 'Google Ads',     pattern: /AW-\d{8,}/, },
+  { key: 'ahrefs',    label: 'Ahrefs',         pattern: /analytics\.ahrefs\.com\/analytics\.js/, },
+  { key: 'hotjar',    label: 'Hotjar',         pattern: /static\.hotjar\.com\/c\/hotjar-/, },
+];
+
+const VERIFICATION = [
+  { key: 'googleSearchConsole', label: 'Google Search Console',
+    pattern: /<meta\s+name=["']google-site-verification["']/ },
+  { key: 'bingWebmaster',       label: 'Bing Webmaster',
+    pattern: /<meta\s+name=["']msvalidate\.01["']/ },
+];
+
+export async function runAnalytics(ctx) {
+  const { htmlFiles, config } = ctx;
+  const results = [];
+  const auditCfg = config.audit ?? {};
+  const analyticsCfg = auditCfg.analytics ?? {};
+  const verificationCfg = auditCfg.verification ?? {};
+
+  // Sample the homepage; analytics scripts should be on every page, but checking
+  // one is enough — they're usually injected via a layout component.
+  const home = htmlFiles.find((f) => f.relPath === 'index.html') ?? htmlFiles[0];
+
+  for (const provider of PROVIDERS) {
+    const present = provider.pattern.test(home.content);
+    const requirement = analyticsCfg[provider.key] ?? 'optional';
+
+    if (requirement === 'required') {
+      results.push(present ? pass(`${provider.label} installed`) : fail(`${provider.label} required but not found`));
+    } else if (requirement === 'banned') {
+      results.push(present ? fail(`${provider.label} found but banned in config`) : pass(`${provider.label} not present (as configured)`));
+    } else {
+      // optional
+      results.push(present ? pass(`${provider.label} installed`) : info(`${provider.label} not installed`));
+    }
+  }
+
+  for (const v of VERIFICATION) {
+    const present = v.pattern.test(home.content);
+    const required = verificationCfg[v.key] === true;
+    if (required) {
+      results.push(present ? pass(`${v.label} verification tag`) : fail(`${v.label} verification tag missing`));
+    } else {
+      results.push(present ? pass(`${v.label} verification tag`) : info(`${v.label} verification tag not present`));
+    }
+  }
+
+  return results;
+}

package/modules/audit/src/groups/blog-quality.mjs

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { pass, fail, warn, info, summarize } from '../util.mjs';
+
+export async function runBlogQuality(ctx) {
+  const { cwd, config, enabled } = ctx;
+  if (!enabled.blog) return [];
+
+  const blogCfg = config.blog && typeof config.blog === 'object' ? config.blog : {};
+  const contentDir = path.resolve(cwd, blogCfg.contentDir ?? 'src/content/blog');
+  const dateField = blogCfg.dateField ?? 'date';
+  const draftField = blogCfg.draftField ?? null;
+
+  if (!fs.existsSync(contentDir)) {
+    return [info('Blog content directory not found', `Looked at: ${contentDir}`)];
+  }
+
+  const results = [];
+  const auditCfg = config.audit ?? {};
+  const staleMonths = auditCfg.blog?.staleMonths ?? 12;
+
+  const files = fs.readdirSync(contentDir).filter((n) => n.endsWith('.md'));
+  if (files.length === 0) {
+    results.push(info('No blog posts found'));
+    return results;
+  }
+
+  const now = new Date();
+  const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  const staleCutoff = new Date(today);
+  staleCutoff.setUTCMonth(staleCutoff.getUTCMonth() - staleMonths);
+
+  const stalePosts = [];
+  const missingDescription = [];
+  const missingImage = [];
+  const shortBody = [];
+  const dupTitle = new Map();
+  const dupDesc = new Map();
+
+  for (const fileName of files) {
+    const raw = fs.readFileSync(path.join(contentDir, fileName), 'utf8');
+    const { data, content } = matter(raw);
+    if (draftField && data[draftField]) continue;
+
+    const slug = fileName.replace(/\.md$/, '');
+    const dateVal = data[dateField];
+    const postDate = dateVal instanceof Date ? dateVal : (typeof dateVal === 'string' ? new Date(dateVal) : null);
+
+    if (postDate && postDate < staleCutoff) {
+      stalePosts.push(`${slug} (${postDate.toISOString().split('T')[0]})`);
+    }
+    if (!data.description || data.description.length < 50) {
+      missingDescription.push(slug);
+    }
+    if (!data.image) missingImage.push(slug);
+    if (content.length < 800) shortBody.push(`${slug} (${content.length} chars)`);
+
+    if (data.title) {
+      const list = dupTitle.get(data.title) ?? [];
+      list.push(slug);
+      dupTitle.set(data.title, list);
+    }
+    if (data.description) {
+      const list = dupDesc.get(data.description) ?? [];
+      list.push(slug);
+      dupDesc.set(data.description, list);
+    }
+  }
+
+  results.push(info(`${files.length} blog posts indexed`));
+  results.push(summarize(
+    `No posts older than ${staleMonths} months`,
+    stalePosts,
+    'warn'
+  ));
+  results.push(summarize('Posts have a description (≥ 50 chars)', missingDescription));
+  results.push(summarize('Posts have an image', missingImage, 'warn'));
+  results.push(summarize('Posts have substantial body (≥ 800 chars)', shortBody, 'warn'));
+
+  const dupTitles = [...dupTitle.entries()].filter(([, ps]) => ps.length > 1);
+  results.push(
+    dupTitles.length === 0
+      ? pass('Blog post titles are unique')
+      : warn(`${dupTitles.length} duplicate post titles`,
+          dupTitles.map(([t, ps]) => `"${t.slice(0, 50)}" → ${ps.join(', ')}`))
+  );
+
+  const dupDescs = [...dupDesc.entries()].filter(([, ps]) => ps.length > 1);
+  results.push(
+    dupDescs.length === 0
+      ? pass('Blog post descriptions are unique')
+      : warn(`${dupDescs.length} duplicate post descriptions`,
+          dupDescs.map(([d, ps]) => `"${d.slice(0, 50)}..." → ${ps.join(', ')}`))
+  );
+
+  return results;
+}

package/modules/audit/src/groups/content.mjs

@@ -0,0 +1,87 @@
+import { pass, fail, warn, info, summarize } from '../util.mjs';
+
+const PLACEHOLDER_RE = /\b(lorem ipsum|TODO:|FIXME:|XXX:)\b/i;
+
+// Anchor text that's bad for SEO + accessibility. "Click here" doesn't tell
+// screen readers (or search engines) what's on the other side of the link.
+const GENERIC_ANCHOR_RE = /^(click here|read more|learn more|here|more info|details|continue|see more|find out more)$/i;
+
+export async function runContent(ctx) {
+  const { htmlFiles, webpSet } = ctx;
+  const results = [];
+
+  const placeholderHits = [];
+  const pngWhereWebp = [];
+  const imgsNoAlt = [];
+  const aTagsNoText = [];
+  const genericAnchors = [];
+
+  // Heading hierarchy: every page must have exactly one <h1>, and headings
+  // shouldn't skip levels (h1 → h3 without h2).
+  const noH1 = [];
+  const multiH1 = [];
+  const skippedHeading = [];
+
+  for (const f of htmlFiles) {
+    // Placeholders
+    if (PLACEHOLDER_RE.test(f.content)) placeholderHits.push(f.relPath);
+
+    // PNG/JPG references where WebP exists
+    for (const m of f.content.matchAll(/<img[^>]+src=["']([^"']+\.(?:png|jpe?g))["']/gi)) {
+      const src = m[1].replace(/^\//, '');
+      const noExt = src.replace(/\.(?:png|jpe?g)$/i, '');
+      if (webpSet.has(noExt)) pngWhereWebp.push(`${f.relPath}: ${m[1]}`);
+    }
+
+    // <img> without alt
+    for (const m of f.content.matchAll(/<img(?![^>]*\salt=)[^>]*>/gi)) {
+      if (/aria-hidden=["']true["']/.test(m[0])) continue;
+      const src = m[0].match(/src=["']([^"']+)["']/)?.[1] ?? '(no src)';
+      imgsNoAlt.push(`${f.relPath}: ${src}`);
+    }
+
+    // <a> tags: empty content + generic anchor text
+    for (const m of f.content.matchAll(/<a[^>]*>([\s\S]*?)<\/a>/gi)) {
+      const inner = m[1].replace(/<[^>]+>/g, '').trim();
+      const hasAriaLabel = /aria-label=["'][^"']+["']/.test(m[0]);
+      const hasTitle = /title=["'][^"']+["']/.test(m[0]);
+      const href = m[0].match(/href=["']([^"']+)["']/)?.[1] ?? '?';
+
+      if (!inner && !hasAriaLabel && !hasTitle) {
+        aTagsNoText.push(`${f.relPath}: <a href="${href}"> (empty)`);
+      } else if (GENERIC_ANCHOR_RE.test(inner) && !hasAriaLabel) {
+        genericAnchors.push(`${f.relPath}: "${inner}" → ${href}`);
+      }
+    }
+
+    // Heading hierarchy
+    const headings = [...f.content.matchAll(/<h([1-6])(?:\s[^>]*)?>/gi)].map((m) => parseInt(m[1], 10));
+    const h1Count = headings.filter((h) => h === 1).length;
+    if (h1Count === 0) noH1.push(f.relPath);
+    if (h1Count > 1) multiH1.push(`${f.relPath} (${h1Count} <h1>s)`);
+
+    let prev = 0;
+    for (const h of headings) {
+      if (prev > 0 && h - prev > 1) {
+        skippedHeading.push(`${f.relPath}: h${prev} → h${h}`);
+        break;
+      }
+      prev = h;
+    }
+  }
+
+  results.push(summarize('No placeholder text (Lorem/TODO/FIXME)', placeholderHits));
+  results.push(summarize('No raw PNG/JPG where WebP exists', pngWhereWebp));
+  results.push(summarize('All images have alt text', dedupe(imgsNoAlt), 'warn'));
+  results.push(summarize('All links have accessible text', dedupe(aTagsNoText), 'warn'));
+  results.push(summarize('No generic anchor text ("click here" etc.)', dedupe(genericAnchors), 'warn'));
+  results.push(summarize('Every page has exactly one <h1>', noH1));
+  results.push(summarize('No multiple <h1>s', multiH1, 'warn'));
+  results.push(summarize('Heading hierarchy is sequential', dedupe(skippedHeading), 'warn'));
+
+  return results;
+}
+
+function dedupe(arr) {
+  return Array.from(new Set(arr)).slice(0, 20);
+}