edgepress 2026.9.3

package/src/page-check.js

@@ -0,0 +1,416 @@
+import { access, lstat, mkdir, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { addVisualEvidence } from './report-visuals.js';
+
+async function htmlFiles(directory) {
+  let entries;
+  try { entries = await readdir(directory, { withFileTypes: true }); }
+  catch (error) { if (error.code === 'ENOENT') throw new Error('Build output is missing. Run npm run build first.'); throw error; }
+  const result = [];
+  for (const entry of entries) {
+    const file = resolve(directory, entry.name);
+    if (entry.isDirectory()) result.push(...await htmlFiles(file));
+    else if (entry.isFile() && extname(entry.name).toLowerCase() === '.html') result.push(file);
+  }
+  return result;
+}
+
+async function allFiles(directory) {
+  let entries;
+  try { entries = await readdir(directory, { withFileTypes: true }); }
+  catch { return []; }
+  const result = [];
+  for (const entry of entries) {
+    const file = resolve(directory, entry.name);
+    if (entry.isDirectory()) result.push(...await allFiles(file));
+    else if (entry.isFile()) result.push(file);
+  }
+  return result;
+}
+
+function hasAccessibleName(attributes, inner) {
+  if (/\baria-label\s*=\s*["'][^"']+\s*["']/i.test(attributes)) return true;
+  if (inner.replace(/<[^>]*>/g, '').replace(/&nbsp;|&#160;/g, ' ').trim()) return true;
+  return /<img\b[^>]*\balt\s*=\s*["'][^"']+["']/i.test(inner);
+}
+
+async function exists(path) {
+  try { await access(path); return true; }
+  catch { return false; }
+}
+
+async function contentDocuments(output, config) {
+  const documents = new Map();
+  for (const locale of config.i18n.locales) {
+    const prefix = locale === config.i18n.defaultLocale ? '' : locale + '/';
+    let entries;
+    try { entries = JSON.parse(await readFile(resolve(output, prefix + 'search.json'), 'utf8')); }
+    catch { continue; }
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (!['post', 'page'].includes(entry.type) || typeof entry.url !== 'string') continue;
+      let pathname;
+      try { pathname = decodeURIComponent(new URL(entry.url, 'https://edgepress.invalid').pathname); }
+      catch { continue; }
+      const segments = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+      const target = resolve(output, ...segments, 'index.html');
+      documents.set(target, { type: entry.type, title: String(entry.title || ''), url: entry.url });
+    }
+  }
+  return documents;
+}
+
+function markdownFeatureCoverage(root, files, sourceByFile) {
+  const expected = [
+    ['headings 2 through 6', /<h2\b[\s\S]*?<h3\b[\s\S]*?<h4\b[\s\S]*?<h5\b[\s\S]*?<h6\b/i],
+    ['Setext heading syntax', /<h2\b[^>]*>Setext (?:heading level two|二级标题示例)<\/h2>/i],
+    ['paragraphs and hard line breaks', /<p\b[\s\S]*?<br\s*\/?\s*>/i],
+    ['hyphen, asterisk, and underscore thematic breaks', (html) => (html.match(/<hr\b/gi) || []).length >= 3],
+    ['emphasis and strong emphasis', /<em\b[\s\S]*?<\/em>[\s\S]*?<strong\b[\s\S]*?<\/strong>/i],
+    ['strikethrough', /<del\b[\s\S]*?<\/del>/i],
+    ['inline and fenced code', /<code\b[\s\S]*?<\/code>[\s\S]*?<pre\b[\s\S]*?<code\b[^>]*class="language-js"/i],
+    ['tilde-fenced and four-space-indented code', /class="language-text"[\s\S]*?<pre\b[^>]*><code[^>]*>const indented =/i],
+    ['code spans containing a literal backtick', (html) => html.includes('<code>`</code>')],
+    ['escaped Markdown punctuation and character references', /\\\*[\s\S]*?&lt;[\s\S]*?&amp;/i],
+    ['inline and reference links', /href="\/quick-start\/"/i],
+    ['GFM automatic links', /href="https:\/\/www\.markdownguide\.org\//i],
+    ['angle-bracket, www, and email automatic links', /href="https:\/\/commonmark\.org"[\s\S]*?href="http:\/\/www\.example\.com"[\s\S]*?href="mailto:team@example\.com"/i],
+    ['images with alternative text', /<img\b[^>]*src="\/edgepress-markdown-guide\.svg"[^>]*alt="[^"]+"/i],
+    ['nested lists with inline formatting', /<li>[\s\S]*?<strong\b[\s\S]*?<ol\b[\s\S]*?<li>/i],
+    ['task lists with accessible status names', /markdown-task-status" role="img" aria-label="[^"]+"/i],
+    ['lists nested inside block quotes', /<blockquote>[\s\S]*?<ul\b[\s\S]*?<\/blockquote>/i],
+    ['nested block quotes', /<blockquote>[\s\S]*?<blockquote>/i],
+    ['tables and inline table syntax', /<table\b[\s\S]*?<th\b[\s\S]*?<em\b[\s\S]*?<\/table>/i],
+    ['safe semantic inline HTML', /<kbd>Ctrl<\/kbd>/i],
+    ['sanitization of active script markup', (html) => !/<script\b[^>]*>alert\(/i.test(html)]
+  ];
+  const guides = files.filter((file) => /markdown-syntax-guide\/index\.html$/i.test(file.replace(/\\/g, '/')));
+  const documents = guides.map((file) => {
+    const html = sourceByFile.get(file) || '';
+    const content = html.match(/<div class="post-content">([\s\S]*?)<\/div>/i)?.[1] || '';
+    const checks = expected.map(([feature, matcher]) => ({ feature, passed: typeof matcher === 'function' ? matcher(content) : matcher.test(content) }));
+    return { path: relative(root, file).replace(/\\/g, '/'), checks, passed: checks.filter((item) => item.passed).length };
+  });
+  return {
+    status: guides.length && documents.every((document) => document.checks.every((item) => item.passed)) ? 'pass' : 'fail',
+    checks: expected.length * Math.max(1, guides.length),
+    passed: documents.reduce((total, document) => total + document.passed, 0),
+    documents
+  };
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel);
+}
+
+async function resolveLocalLink(output, pageFile, href) {
+  let url;
+  try { url = new URL(href, 'https://edgepress.invalid/' + relative(output, pageFile).split(sep).join('/')); }
+  catch { return null; }
+  if (url.origin !== 'https://edgepress.invalid') return null;
+  let pathname;
+  try { pathname = decodeURIComponent(url.pathname); }
+  catch { return { broken: true, target: href }; }
+  const clean = pathname.replace(/^\/+/, '');
+  const candidates = [];
+  if (!clean || clean.endsWith('/')) candidates.push(resolve(output, clean, 'index.html'));
+  else if (extname(clean)) candidates.push(resolve(output, clean));
+  else candidates.push(resolve(output, clean + '.html'), resolve(output, clean, 'index.html'));
+  for (const candidate of candidates) {
+    if (!candidate.startsWith(output + sep)) continue;
+    if (await exists(candidate)) return { file: candidate, fragment: url.hash.slice(1) };
+  }
+  return { broken: true, target: href };
+}
+
+function auditSummary(checks, findings) {
+  const errors = findings.filter((issue) => issue.severity === 'error').length;
+  const warnings = findings.length - errors;
+  return {
+    status: errors ? 'fail' : warnings ? 'warning' : 'pass',
+    score: checks ? Math.floor((checks - findings.length) / checks * 100) : 100,
+    checks,
+    errors,
+    warnings
+  };
+}
+
+function markdownReport(report) {
+  const lines = [
+    '# EdgePress accessibility and agent-friendliness audit',
+    '',
+    'Overall status: **' + report.status + '**',
+    '',
+    '| Audit | Status | Score | Checks | Errors | Warnings |',
+    '| --- | --- | ---: | ---: | ---: | ---: |',
+    '| Accessibility | ' + report.accessibility.status + ' | ' + report.accessibility.score + '% | ' + report.accessibility.checks + ' | ' + report.accessibility.errors + ' | ' + report.accessibility.warnings + ' |',
+    '| Agent friendliness | ' + report.agentFriendliness.status + ' | ' + report.agentFriendliness.score + '% | ' + report.agentFriendliness.checks + ' | ' + report.agentFriendliness.errors + ' | ' + report.agentFriendliness.warnings + ' |',
+    '| Markdown rendering | ' + report.markdownRendering.status + ' | ' + Math.floor(report.markdownRendering.passed / Math.max(1, report.markdownRendering.checks) * 100) + '% | ' + report.markdownRendering.checks + ' | ' + (report.markdownRendering.checks - report.markdownRendering.passed) + ' | 0 |',
+    '| Report reading structure | ' + (report.visualEvidence?.reportAccessibility?.status || 'pending') + ' | ' +
+      Math.floor((report.visualEvidence?.reportAccessibility?.passed || 0) / Math.max(1, report.visualEvidence?.reportAccessibility?.checks || 0) * 100) + '% | ' +
+      (report.visualEvidence?.reportAccessibility?.checks || 0) + ' | ' +
+      ((report.visualEvidence?.reportAccessibility?.checks || 0) - (report.visualEvidence?.reportAccessibility?.passed || 0)) + ' | 0 |',
+    '',
+    'Generated documents: ' + report.pages + ' | Posts: ' + report.contentSummary.posts + ' | Pages: ' + report.contentSummary.pages +
+      ' | System routes: ' + report.contentSummary.system + ' | Errors: ' + report.errors + ' | Warnings: ' + report.warnings,
+    'HTML bytes: ' + report.metrics.htmlBytes + ' | Stylesheet references: ' + report.metrics.stylesheets +
+      ' | Potentially render-blocking stylesheets: ' + report.metrics.blockingStylesheets +
+    ' | Script references: ' + report.metrics.scripts + ' | Blocking scripts: ' + report.metrics.blockingScripts,
+    '',
+    report.visualEvidence?.status === 'complete'
+      ? 'Accessible PDF evidence: [page-check.pdf](page-check.pdf) | HTML report: [page-check-visual.html](page-check-visual.html) | Screenshots: ' +
+        report.visualEvidence.screenshots.map((item) => '[' + item.title + ' · ' + item.viewport + ' (' + item.viewportWidth + '/' + item.documentWidth + ' px)](' + item.path.replace(/^tools\//, '') + ')').join(' · ')
+      : 'Visual evidence: ' + (report.visualEvidence?.reason || 'not generated'),
+    '',
+    '## Findings',
+    ''
+  ];
+  if (!report.issues.length) lines.push('No findings.');
+  for (const issue of report.issues) lines.push('- **' + issue.severity.toUpperCase() + ' · ' + issue.category + '** ' + issue.page + ' — ' + issue.message);
+  lines.push('', '## Markdown rendering', '', 'Verified ' + report.markdownRendering.passed + ' of ' + report.markdownRendering.checks +
+    ' syntax combinations in the generated tutorial post.');
+  for (const document of report.markdownRendering.documents) {
+    lines.push('', '### ' + document.path, '', ...document.checks.map((item) => '- [' + (item.passed ? 'x' : ' ') + '] ' + item.feature));
+  }
+  lines.push('', '## Documents reviewed', '', '| Type | Count |', '| --- | ---: |', '| Posts | ' + report.contentSummary.posts + ' |',
+    '| Customizable pages and homepages | ' + report.contentSummary.pages + ' |', '| System routes | ' + report.contentSummary.system + ' |');
+  lines.push('', '## Scope', '', ...report.scope.map((item) => '- ' + item), '', 'This report is written outside the public output directory.');
+  return lines.join('\n');
+}
+
+export async function checkPages(config) {
+  const output = config.resolvedPaths.output;
+  const files = await htmlFiles(output);
+  const contentMap = await contentDocuments(output, config);
+  const issues = [];
+  const auditFindings = { accessibility: [], agentFriendliness: [] };
+  const auditChecks = { accessibility: 0, agentFriendliness: 0 };
+  const pageIds = new Map();
+  const sourceByFile = new Map();
+  const metrics = { htmlBytes: 0, stylesheets: 0, blockingStylesheets: 0, scripts: 0, blockingScripts: 0 };
+  const inspect = (category, fails, severity, page, message) => {
+    auditChecks[category] += 1;
+    if (!fails) return;
+    const finding = { severity, category, page, message };
+    issues.push(finding);
+    auditFindings[category].push(finding);
+  };
+  const addFinding = (severity, category, page, message) => issues.push({ severity, category, page, message });
+
+  for (const file of files) {
+    const html = await readFile(file, 'utf8');
+    sourceByFile.set(file, html);
+    pageIds.set(file, new Set([...html.matchAll(/\bid\s*=\s*["']([^"']+)["']/gi)].map((match) => match[1])));
+    metrics.htmlBytes += Buffer.byteLength(html);
+  }
+  const markdownRendering = markdownFeatureCoverage(output, files, sourceByFile);
+  if (!markdownRendering.documents.length) {
+    addFinding('error', 'markdown-rendering', 'content/posts', 'The Markdown syntax guide post was not generated.');
+  }
+  for (const document of markdownRendering.documents) {
+    for (const check of document.checks.filter((item) => !item.passed)) {
+      addFinding('error', 'markdown-rendering', document.path, 'Markdown syntax did not render: ' + check.feature + '.');
+    }
+  }
+  for (const file of files) {
+    const html = sourceByFile.get(file);
+    const page = relative(output, file).split(sep).join('/');
+    inspect('accessibility', !/<html\b[^>]*\blang\s*=\s*["'][^"']+["']/i.test(html), 'error', page, 'Missing document language (html lang).');
+    inspect('accessibility', !/<main\b/i.test(html), 'error', page, 'Missing main landmark.');
+    const h1Count = [...html.matchAll(/<h1\b/gi)].length;
+    inspect('accessibility', h1Count !== 1, 'warning', page, 'Expected exactly one h1 heading.');
+    inspect('agentFriendliness', h1Count !== 1, 'warning', page, 'A single page-level heading helps identify the page topic.');
+    for (const match of html.matchAll(/<nav\b([^>]*)>/gi)) {
+      inspect('accessibility', !/\baria-label\s*=\s*["'][^"']+/.test(match[1]), 'warning', page, 'Navigation landmark has no accessible label.');
+    }
+    inspect('agentFriendliness', !/<title>\s*[^<]+\s*<\/title>/i.test(html), 'error', page, 'Missing or empty page title.');
+    inspect('agentFriendliness', !/<meta\b[^>]*name\s*=\s*["']description["'][^>]*content\s*=\s*["'][^"']+["']/i.test(html), 'warning', page, 'Missing meta description.');
+    const canonical = html.match(/<link\b[^>]*\brel\s*=\s*["']canonical["'][^>]*>/i)?.[0] ?? '';
+    const canonicalHref = canonical.match(/\bhref\s*=\s*["']([^"']*)["']/i)?.[1] ?? '';
+    inspect('agentFriendliness', !canonicalHref || (config.site.url && !canonicalHref.startsWith(config.site.url)), 'warning', page, 'Missing or non-canonical URL metadata.');
+    const jsonLd = html.match(/<script\b[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/i)?.[1];
+    let validStructuredData = false;
+    try { validStructuredData = Boolean(jsonLd && JSON.parse(jsonLd)?.['@context'] === 'https://schema.org'); } catch { validStructuredData = false; }
+    inspect('agentFriendliness', !validStructuredData, 'warning', page, 'Missing or invalid Schema.org JSON-LD.');
+
+    const ids = [...html.matchAll(/\bid\s*=\s*["']([^"']+)["']/gi)].map((match) => match[1]);
+    inspect('accessibility', new Set(ids).size !== ids.length, 'warning', page, 'Duplicate HTML id values were found.');
+    let previousHeading = 0;
+    let skippedHeadingLevel = false;
+    for (const match of html.matchAll(/<h([1-6])\b/gi)) {
+      const level = Number(match[1]);
+      if (previousHeading && level > previousHeading + 1) skippedHeadingLevel = true;
+      previousHeading = level;
+    }
+    inspect('accessibility', skippedHeadingLevel, 'warning', page, 'Heading levels skip one or more steps.');
+
+    for (const match of html.matchAll(/<img\b([^>]*)>/gi)) {
+      inspect('accessibility', !/\balt\s*=/.test(match[1]), 'error', page, 'Image is missing an alt attribute.');
+    }
+    for (const match of html.matchAll(/<a\b([^>]*)>([\s\S]*?)<\/a>/gi)) {
+      inspect('accessibility', !hasAccessibleName(match[1], match[2]), 'error', page, 'Link has no accessible name.');
+      if (/\btarget\s*=\s*["']_blank["']/i.test(match[1]) && !/\brel\s*=\s*["'][^"']*noopener/i.test(match[1])) {
+        inspect('accessibility', true, 'warning', page, 'A new-tab link should include rel="noopener".');
+      }
+      const href = match[1].match(/\bhref\s*=\s*["']([^"']+)\s*["']/i)?.[1];
+      if (!href || /^(?:mailto:|tel:|javascript:)/i.test(href)) continue;
+      const target = await resolveLocalLink(output, file, href);
+      if (target?.broken) {
+        inspect('accessibility', true, 'error', page, 'Broken internal link: ' + href);
+        inspect('agentFriendliness', true, 'error', page, 'Broken internal link: ' + href);
+      } else if (target?.file) {
+        inspect('agentFriendliness', false, 'warning', page, 'Internal link resolves: ' + href);
+        if (target.fragment && extname(target.file).toLowerCase() === '.html') {
+          let idsForTarget = pageIds.get(target.file);
+          if (!idsForTarget) {
+            const targetHtml = sourceByFile.get(target.file) ?? await readFile(target.file, 'utf8');
+            idsForTarget = new Set([...targetHtml.matchAll(/\bid\s*=\s*["']([^"']+)["']/gi)].map((item) => item[1]));
+            pageIds.set(target.file, idsForTarget);
+          }
+          inspect('accessibility', !idsForTarget.has(target.fragment), 'warning', page, 'Link fragment not found: ' + href);
+        }
+      }
+    }
+
+    for (const match of html.matchAll(/<link\b([^>]*)>/gi)) {
+      if (!/\brel\s*=\s*["'][^"']*\bstylesheet\b[^"']*["']/i.test(match[1])) continue;
+      metrics.stylesheets += 1;
+      const media = match[1].match(/\bmedia\s*=\s*["']([^"']+)["']/i)?.[1].trim().toLowerCase();
+      if (!media || media === 'all') metrics.blockingStylesheets += 1;
+      const href = match[1].match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1] ?? '';
+      if (/\.css(?:[?#]|$)/i.test(href) && !/\.[a-f0-9]{16}\.css(?:[?#]|$)/i.test(href)) {
+        addFinding('warning', 'performance', page, 'Stylesheet URL is not content-fingerprinted: ' + href);
+      }
+    }
+    for (const match of html.matchAll(/<script\b([^>]*)>/gi)) {
+      if (!/\bsrc\s*=/.test(match[1])) continue;
+      metrics.scripts += 1;
+      if (!/\b(?:async|defer)\b/i.test(match[1]) && !/\btype\s*=\s*["']module["']/i.test(match[1])) {
+        metrics.blockingScripts += 1;
+        addFinding('warning', 'performance', page, 'External script may block rendering; use defer, async, or a module script.');
+      }
+    }
+  }
+
+  const all = await allFiles(output);
+  const hashedAssets = all.filter((file) => /\.[a-f0-9]{16}\.(?:css|js)$/i.test(file))
+    .map((file) => relative(output, file).split(sep).join('/'));
+  const styleFiles = all.filter((file) => extname(file).toLowerCase() === '.css');
+  if (styleFiles.length) {
+    const styles = (await Promise.all(styleFiles.map((file) => readFile(file, 'utf8')))).join('\n');
+    inspect('accessibility', !/:focus(?:-visible)?\s*\{[^}]*outline/i.test(styles), 'warning', 'theme', 'No visible keyboard focus outline was found in the generated CSS.');
+  } else {
+    inspect('accessibility', true, 'warning', 'theme', 'No stylesheet was found to inspect for keyboard focus styles.');
+  }
+
+  let robots = '';
+  let sitemap = '';
+  let llms = '';
+  try { robots = await readFile(resolve(output, 'robots.txt'), 'utf8'); } catch { /* Checked below. */ }
+  try { sitemap = await readFile(resolve(output, 'sitemap.xml'), 'utf8'); } catch { /* Checked below. */ }
+  inspect('agentFriendliness', !robots.includes('User-agent: *') || !robots.includes('Sitemap:'), 'warning', 'robots.txt', 'robots.txt should identify the sitemap and a default crawler rule.');
+  for (const crawler of config.site.agentSeo.enabled ? config.site.agentSeo.agentCrawlers : []) {
+    inspect('agentFriendliness', !robots.includes('User-agent: ' + crawler), 'warning', 'robots.txt', 'robots.txt does not include the configured agent crawler: ' + crawler);
+  }
+  inspect('agentFriendliness', !sitemap.includes('<urlset') || !sitemap.includes('<url>'), 'warning', 'sitemap.xml', 'The XML sitemap is missing or contains no URLs.');
+  if (config.site.agentSeo.enabled && config.site.agentSeo.llmsTxt) {
+    try { llms = await readFile(resolve(output, 'llms.txt'), 'utf8'); } catch { /* Checked below. */ }
+    inspect('agentFriendliness', !llms.startsWith('# ') || !llms.includes('## Project pages'), 'warning', 'llms.txt', 'The configured llms.txt discovery file is missing or incomplete.');
+  }
+
+  if (!config.site.url || new URL(config.site.url).hostname.endsWith('example.com')) {
+    addFinding('warning', 'publication-readiness', 'config.yml', 'Replace the example site URL with the published site URL.');
+  }
+  if (!config.privacy.controller.name.trim() || !config.privacy.controller.contact.trim()) {
+    addFinding('warning', 'publication-readiness', 'config.yml', 'Add the real site operator name and privacy contact before publishing the privacy policy.');
+  }
+
+  const accessibility = auditSummary(auditChecks.accessibility, auditFindings.accessibility);
+  const agentFriendliness = auditSummary(auditChecks.agentFriendliness, auditFindings.agentFriendliness);
+  const homepagePaths = new Set(config.i18n.locales.map((locale) => locale === config.i18n.defaultLocale ? 'index.html' : locale + '/index.html'));
+  const documents = files.map((file) => {
+    const path = relative(output, file).split(sep).join('/');
+    const metadata = contentMap.get(file);
+    const isHomepage = homepagePaths.has(path);
+    const type = metadata?.type || (isHomepage ? 'homepage' : 'system');
+    const documentIssues = issues.filter((issue) => issue.page === path);
+    return {
+      path,
+      type,
+      title: metadata?.title || sourceByFile.get(file).match(/<h1\b[^>]*>([\s\S]*?)<\/h1>/i)?.[1]?.replace(/<[^>]+>/g, '').trim() || path,
+      status: documentIssues.some((issue) => issue.severity === 'error') ? 'fail' :
+        documentIssues.length ? 'warning' : 'pass'
+    };
+  });
+  const contentSummary = {
+    posts: documents.filter((document) => document.type === 'post').length,
+    pages: documents.filter((document) => document.type === 'page' || document.type === 'homepage').length,
+    system: documents.filter((document) => document.type === 'system').length
+  };
+  const errors = issues.filter((issue) => issue.severity === 'error').length;
+  const warnings = issues.length - errors;
+  const report = {
+    generatedAt: new Date().toISOString(),
+    status: errors ? 'fail' : warnings ? 'warning' : 'pass',
+    pages: files.length,
+    contentSummary,
+    documents,
+    markdownRendering,
+    errors,
+    warnings,
+    accessibility,
+    agentFriendliness,
+    metrics,
+    hashedAssets,
+    issues,
+    scope: [
+      'Accessibility checks inspect generated HTML and CSS. They do not measure color contrast, screen-reader behavior, keyboard interactions in a browser, or dynamic vendor widgets.',
+      'Agent-friendliness checks inspect metadata, structured data, internal links, robots.txt, sitemap.xml, and llms.txt. They do not guarantee crawler indexing or answer quality.',
+      'This automated report is not a legal-compliance assessment or a substitute for manual review.',
+      'Screenshots capture generated local pages at desktop and mobile viewports. They do not replace manual keyboard, zoom, contrast, or assistive-technology review.'
+    ]
+  };
+  const requestedDirectory = resolve(config.root, 'tools');
+  await mkdir(requestedDirectory, { recursive: true });
+  const directoryInfo = await lstat(requestedDirectory);
+  if (directoryInfo.isSymbolicLink() || !directoryInfo.isDirectory()) {
+    throw new Error('Page-check report directory must be a real directory: ' + requestedDirectory);
+  }
+  const root = await realpath(config.root);
+  const directory = await realpath(requestedDirectory);
+  if (!isInside(root, directory)) throw new Error('Page-check report directory must stay inside the project root');
+  const jsonPath = resolve(directory, 'page-check.json');
+  const markdownPath = resolve(directory, 'page-check.md');
+  for (const file of [jsonPath, markdownPath]) {
+    try {
+      const info = await lstat(file);
+      if (info.isSymbolicLink() || !info.isFile()) throw new Error('Refusing an unsafe page-check report path: ' + file);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  for (const file of [resolve(directory, 'page-check.pdf'), resolve(directory, 'page-check-visual.html')]) {
+    try {
+      const info = await lstat(file);
+      if (info.isSymbolicLink() || !info.isFile()) throw new Error('Refusing an unsafe visual report path: ' + file);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  try {
+    report.visualEvidence = await addVisualEvidence(config, report);
+    if (report.visualEvidence.status !== 'complete') {
+      issues.push({ severity: 'warning', category: 'visual-evidence', page: 'report', message: report.visualEvidence.reason || 'Visual evidence was not generated.' });
+    }
+  } catch (error) {
+    report.visualEvidence = { status: 'failed', reason: error.message };
+    issues.push({ severity: 'warning', category: 'visual-evidence', page: 'report', message: 'Screenshot or PDF generation failed: ' + error.message });
+  }
+  report.errors = issues.filter((issue) => issue.severity === 'error').length;
+  report.warnings = issues.filter((issue) => issue.severity === 'warning').length;
+  report.status = report.errors ? 'fail' : report.warnings ? 'warning' : 'pass';
+  await writeFile(jsonPath, JSON.stringify(report, null, 2), 'utf8');
+  await writeFile(markdownPath, markdownReport(report), 'utf8');
+  return report;
+}

package/src/plugin-api.js

@@ -0,0 +1,75 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { renderMarkdown } from './markdown.js';
+
+export async function createExtensions(config) {
+  const filters = new Map();
+  const generators = new Map();
+  const renderers = new Map([['.md', { render: (source, context) => {
+    const locale = context.document.locale;
+    const base = context.config.i18n.translationsByLocale?.[context.config.i18n.defaultLocale];
+    const selected = context.config.i18n.translationsByLocale?.[locale];
+    return renderMarkdown(source, {
+      ...context.config.markdown,
+      taskLabels: {
+        complete: selected?.markdownTaskComplete ?? base?.markdownTaskComplete ?? 'Task complete',
+        incomplete: selected?.markdownTaskIncomplete ?? base?.markdownTaskIncomplete ?? 'Task incomplete'
+      }
+    });
+  }, cacheable: true }]]);
+
+  function registerFilter(name, fn) {
+    if (typeof fn !== 'function') throw new TypeError('A filter must be a function');
+    const list = filters.get(name) ?? [];
+    list.push(fn);
+    filters.set(name, list);
+  }
+  function registerGenerator(name, fn) {
+    if (generators.has(name)) throw new Error('Generator already registered: ' + name);
+    if (typeof fn !== 'function') throw new TypeError('A generator must be a function');
+    generators.set(name, fn);
+  }
+  function registerRenderer(extension, fn) {
+    if (typeof fn !== 'function') throw new TypeError('A renderer must be a function');
+    const ext = extension.startsWith('.') ? extension.toLowerCase() : '.' + extension.toLowerCase();
+    renderers.set(ext, { render: fn, cacheable: false });
+  }
+
+  const api = { registerFilter, registerGenerator, registerRenderer };
+  const realRoot = await realpath(config.root);
+  for (const pluginPath of config.plugins) {
+    if (typeof pluginPath !== 'string' || !pluginPath.trim() || isAbsolute(pluginPath)) {
+      throw new Error('Each plugin must be a non-empty relative module path');
+    }
+    const pluginFile = resolve(config.root, pluginPath);
+    const pluginRelative = relative(config.root, pluginFile);
+    if (pluginRelative === '..' || pluginRelative.startsWith('..' + sep) || isAbsolute(pluginRelative)) {
+      throw new Error('Plugin paths must stay inside the project root: ' + pluginPath);
+    }
+    const realPluginFile = await realpath(pluginFile);
+    const realPluginRelative = relative(realRoot, realPluginFile);
+    if (realPluginRelative === '..' || realPluginRelative.startsWith('..' + sep) || isAbsolute(realPluginRelative)) {
+      throw new Error('Plugin paths must resolve inside the project root, including through symbolic links: ' + pluginPath);
+    }
+    const url = pathToFileURL(pluginFile).href;
+    const plugin = (await import(url)).default;
+    if (typeof plugin !== 'function') throw new Error('Plugin must have a default function export: ' + pluginPath);
+    await plugin(api);
+  }
+
+  return {
+    generators,
+    renderer(extension) {
+      return renderers.get(extension.toLowerCase()) ?? null;
+    },
+    async filter(name, value, context = {}) {
+      let current = value;
+      for (const fn of filters.get(name) ?? []) {
+        const next = await fn(current, context);
+        if (next !== undefined) current = next;
+      }
+      return current;
+    }
+  };
+}

package/src/preview.js

@@ -0,0 +1,167 @@
+import { access, readdir, stat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { buildSite } from './build.js';
+import { loadConfig } from './config.js';
+import { checkPages } from './page-check.js';
+
+const watchedDirectories = ['content', 'languages', 'plugins', 'src', 'static', 'themes'];
+const watchedFiles = ['config.yml', 'edgepress.config.mjs', 'wrangler.jsonc'];
+const ignoredNames = new Set(['.edgepress', '.git', '.wrangler', 'dist', 'node_modules', 'tools']);
+
+async function sourceSnapshot(root) {
+  const values = [];
+  for (const name of watchedFiles) {
+    try {
+      const info = await stat(resolve(root, name));
+      values.push(name + ':' + info.size + ':' + info.mtimeMs);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      values.push(name + ':missing');
+    }
+  }
+  async function visit(directory, relativePath) {
+    let entries;
+    try { entries = await readdir(directory, { withFileTypes: true }); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (entry.isSymbolicLink() || ignoredNames.has(entry.name)) continue;
+      const file = resolve(directory, entry.name);
+      const relativeFile = relativePath ? relativePath + '/' + entry.name : entry.name;
+      if (entry.isDirectory()) await visit(file, relativeFile);
+      else if (entry.isFile()) {
+        const info = await stat(file);
+        values.push(relativeFile + ':' + info.size + ':' + info.mtimeMs);
+      }
+    }
+  }
+  for (const name of watchedDirectories) await visit(resolve(root, name), name);
+  return values.join('\n');
+}
+
+function cliArgs(args) {
+  const options = [...args];
+  if (!options.some((value) => value === '--ip' || value.startsWith('--ip='))) options.push('--ip', '127.0.0.1');
+  if (!options.some((value) => value === '--port' || value.startsWith('--port='))) options.push('--port', '8787');
+  return options;
+}
+
+async function main() {
+  const config = await loadConfig();
+  const root = config.root;
+  const wrangler = resolve(root, 'node_modules/wrangler/bin/wrangler.js');
+  await access(wrangler);
+
+  async function rebuild() {
+    await buildSite(root, { preview: true });
+    const currentConfig = await loadConfig(root);
+    const report = await checkPages(currentConfig);
+    console.log('Accessibility and agent-friendliness report: ' + report.status +
+      ' (' + report.accessibility.status + ', ' + report.agentFriendliness.status + ')');
+  }
+
+  await rebuild();
+  let snapshot = await sourceSnapshot(root);
+  const commandOffset = ['preview', 'dev', 'server'].includes(process.argv[2]) ? 3 : 2;
+  const args = [wrangler, 'dev', ...cliArgs(process.argv.slice(commandOffset))];
+  let child;
+  let stopped = false;
+  let restarting = false;
+  let scanning = false;
+  let rebuilding = false;
+  let rebuildAgain = false;
+  let debounce;
+
+  function startWrangler() {
+    if (stopped) return;
+    child = spawn(process.execPath, args, { cwd: root, env: process.env, stdio: 'inherit', windowsHide: true });
+    const started = child;
+    started.once('error', (error) => {
+      console.error('Could not start Wrangler preview: ' + error.message);
+      if (!restarting) stop();
+      process.exitCode = 1;
+    });
+    started.once('exit', (code) => {
+      if (child === started) child = null;
+      if (stopped || restarting) return;
+      console.error('Wrangler preview exited' + (code === null ? '' : ' with code ' + code) + '.');
+      stop();
+      if (code !== 0) process.exitCode = code ?? 1;
+    });
+  }
+
+  async function stopWrangler() {
+    const current = child;
+    child = null;
+    if (!current || current.exitCode !== null || current.signalCode !== null) return;
+    await new Promise((resolveExit) => {
+      const timeout = setTimeout(() => {
+        if (current.exitCode === null) current.kill('SIGKILL');
+        resolveExit();
+      }, 5000);
+      current.once('exit', () => {
+        clearTimeout(timeout);
+        resolveExit();
+      });
+      current.kill();
+    });
+  }
+
+  startWrangler();
+
+  async function scheduleBuild() {
+    if (stopped) return;
+    if (rebuilding) {
+      rebuildAgain = true;
+      return;
+    }
+    rebuilding = true;
+    do {
+      rebuildAgain = false;
+      restarting = true;
+      try {
+        await stopWrangler();
+        await rebuild();
+      } catch (error) {
+        console.error('Preview rebuild failed; the last successful output remains available.\n' + (error?.stack || error));
+      } finally {
+        restarting = false;
+        startWrangler();
+      }
+    } while (rebuildAgain && !stopped);
+    rebuilding = false;
+  }
+
+  const poll = setInterval(async () => {
+    if (scanning || stopped) return;
+    scanning = true;
+    try {
+      const next = await sourceSnapshot(root);
+      if (next !== snapshot) {
+        snapshot = next;
+        clearTimeout(debounce);
+        debounce = setTimeout(scheduleBuild, 400);
+      }
+    } catch (error) {
+      console.error('Preview source scan failed: ' + error.message);
+    } finally {
+      scanning = false;
+    }
+  }, 900);
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(poll);
+    clearTimeout(debounce);
+    void stopWrangler();
+  }
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+}
+
+main().catch((error) => {
+  console.error(error?.stack || error);
+  process.exitCode = 1;
+});