doclify-guardrail 1.1.2 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doclify-guardrail",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "type": "module",
   "description": "Quality gate for your Markdown docs. Zero dependencies, catches errors in seconds.",
   "files": [

package/src/checker.mjs

@@ -3,15 +3,21 @@ const DEFAULTS = {
   strict: false
 };
 
-const RULE_SEVERITY = {
-  frontmatter: 'warning',
-  'single-h1': 'error',
-  'line-length': 'warning',
-  placeholder: 'warning',
-  'insecure-link': 'warning',
-  'dead-link': 'error',
-  'stale-doc': 'warning'
-};
+const RULE_CATALOG = [
+  { id: 'frontmatter',        severity: 'warning', description: 'Require YAML frontmatter block' },
+  { id: 'single-h1',          severity: 'error',   description: 'Exactly one H1 heading per file' },
+  { id: 'heading-hierarchy',  severity: 'warning', description: 'No skipped heading levels (H2 → H4)' },
+  { id: 'duplicate-heading',  severity: 'warning', description: 'No duplicate headings at same level' },
+  { id: 'line-length',        severity: 'warning', description: 'Max line length (default: 160 chars)' },
+  { id: 'placeholder',        severity: 'warning', description: 'No TODO/FIXME/WIP/TBD markers' },
+  { id: 'insecure-link',      severity: 'warning', description: 'No http:// links (use https://)' },
+  { id: 'empty-link',         severity: 'warning', description: 'No empty link text or URL' },
+  { id: 'img-alt',            severity: 'warning', description: 'Images must have alt text' },
+  { id: 'dead-link',          severity: 'error',   description: 'No broken links (requires --check-links)' },
+  { id: 'stale-doc',          severity: 'warning', description: 'Warn on stale docs (requires --check-freshness)' }
+];
+
+const RULE_SEVERITY = Object.fromEntries(RULE_CATALOG.map(r => [r.id, r.severity]));
 
 const PLACEHOLDER_PATTERNS = [
   { rx: /\bTODO\b/i,           msg: 'TODO marker found — remove before publishing' },
@@ -118,6 +124,41 @@ function checkMarkdown(rawContent, opts = {}) {
     }
   }
 
+  // Rule: heading-hierarchy (h1→h3 without h2 is a skip)
+  let prevLevel = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const hMatch = lines[i].match(/^(#{1,6})\s/);
+    if (!hMatch) continue;
+    const level = hMatch[1].length;
+    if (prevLevel > 0 && level > prevLevel + 1) {
+      warnings.push(normalizeFinding(
+        'heading-hierarchy',
+        `Heading level skipped: H${prevLevel} → H${level} (expected H${prevLevel + 1}).`,
+        i + 1,
+        filePath
+      ));
+    }
+    prevLevel = level;
+  }
+
+  // Rule: duplicate-heading (same text at same level)
+  const headingSeen = new Map();
+  for (let i = 0; i < lines.length; i += 1) {
+    const hMatch = lines[i].match(/^(#{1,6})\s+(.+)$/);
+    if (!hMatch) continue;
+    const key = `${hMatch[1].length}:${hMatch[2].trim().toLowerCase()}`;
+    if (headingSeen.has(key)) {
+      warnings.push(normalizeFinding(
+        'duplicate-heading',
+        `Duplicate heading "${hMatch[2].trim()}" (also at line ${headingSeen.get(key)}).`,
+        i + 1,
+        filePath
+      ));
+    } else {
+      headingSeen.set(key, i + 1);
+    }
+  }
+
   // Rule: line-length (uses raw content — code block lines can still be too long)
   rawLines.forEach((line, idx) => {
     if (line.length > maxLineLength) {
@@ -179,6 +220,27 @@ function checkMarkdown(rawContent, opts = {}) {
     }
   });
 
+  // Rule: empty-link (uses stripped content, excludes images)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    // [](url) — empty link text (but not ![](url) which is img-alt)
+    if (/(?<!!)\[\]\([^)]+\)/.test(cleanLine)) {
+      warnings.push(normalizeFinding('empty-link', 'Link has empty text: [](url).', idx + 1, filePath));
+    }
+    // [text]() — empty link URL
+    if (/(?<!!)\[[^\]]+\]\(\s*\)/.test(cleanLine)) {
+      warnings.push(normalizeFinding('empty-link', 'Link has empty URL: [text]().', idx + 1, filePath));
+    }
+  });
+
+  // Rule: img-alt (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    if (/!\[\]\([^)]+\)/.test(cleanLine)) {
+      warnings.push(normalizeFinding('img-alt', 'Image missing alt text: ![](url).', idx + 1, filePath));
+    }
+  });
+
   // Custom rules (uses stripped content)
   if (opts.customRules && opts.customRules.length > 0) {
     lines.forEach((line, idx) => {
@@ -203,4 +265,4 @@ function checkMarkdown(rawContent, opts = {}) {
   };
 }
 
-export { DEFAULTS, RULE_SEVERITY, normalizeFinding, checkMarkdown, stripCodeBlocks, stripInlineCode };
+export { DEFAULTS, RULE_SEVERITY, RULE_CATALOG, normalizeFinding, checkMarkdown, stripCodeBlocks, stripInlineCode };

package/src/ci-output.mjs

@@ -33,7 +33,7 @@ function generateJUnitXml(output) {
   const suites = [];
 
   const tests = output.files.length + (output.fileErrors?.length || 0);
-  const failures = output.files.filter((f) => f.findings.errors.length > 0 || f.findings.warnings.length > 0).length;
+  const failures = output.files.filter((f) => f.findings.errors.length > 0).length;
   const errors = output.fileErrors?.length || 0;
 
   suites.push('<?xml version="1.0" encoding="UTF-8"?>');
@@ -42,16 +42,24 @@ function generateJUnitXml(output) {
   );
 
   for (const fileResult of output.files) {
+    const hasErrors = fileResult.findings.errors.length > 0;
+    const hasWarnings = fileResult.findings.warnings.length > 0;
+
+    if (!hasErrors && !hasWarnings) {
+      suites.push(`  <testcase classname="doclify.guardrail" name="${escapeXml(fileResult.file)}"/>`);
+      continue;
+    }
+
     suites.push(`  <testcase classname="doclify.guardrail" name="${escapeXml(fileResult.file)}">`);
 
-    const findings = [
-      ...fileResult.findings.errors,
-      ...fileResult.findings.warnings
-    ];
+    if (hasErrors) {
+      const errorDetail = fileResult.findings.errors.map(makeFindingLine).join('\n');
+      suites.push(`    <failure message="${escapeXml(`${fileResult.summary.errors} error${fileResult.summary.errors === 1 ? '' : 's'}`)}">${escapeXml(errorDetail)}</failure>`);
+    }
 
-    if (findings.length > 0) {
-      const detail = findings.map(makeFindingLine).join('\n');
-      suites.push(`    <failure message="${escapeXml(`${fileResult.summary.errors} errors, ${fileResult.summary.warnings} warnings`)}">${escapeXml(detail)}</failure>`);
+    if (hasWarnings) {
+      const warnDetail = fileResult.findings.warnings.map(makeFindingLine).join('\n');
+      suites.push(`    <system-out>${escapeXml(warnDetail)}</system-out>`);
     }
 
     suites.push('  </testcase>');
@@ -227,7 +235,7 @@ function generateSarifReport(output, options) {
 function generateBadge(output, options = {}) {
   const label = (options.label || 'docs health').trim() || 'docs health';
   const badgePath = path.resolve(options.badgePath || 'doclify-badge.svg');
-  const score = computeHealthScore(output.summary || {});
+  const score = output.summary?.healthScore ?? 0;
   const svg = generateBadgeSvg(score, label);
   fs.writeFileSync(badgePath, svg, 'utf8');
   return {

package/src/colors.mjs

@@ -34,9 +34,9 @@ function log(icon, message) {
   console.error(`  ${icon} ${message}`);
 }
 
-function printBanner(fileCount) {
+function printBanner(fileCount, version) {
   console.error('');
-  console.error(`  ${c.bold('Doclify Guardrail')} ${c.dim('v1.0')}`);
+  console.error(`  ${c.bold('Doclify Guardrail')} ${c.dim(`v${version || '?'}`)}`);
   console.error('');
   log(c.cyan('ℹ'), `Scanning ${c.bold(String(fileCount))} file${fileCount === 1 ? '' : 's'}...`);
 }

package/src/index.mjs

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { checkMarkdown } from './checker.mjs';
+import { checkMarkdown, RULE_CATALOG } from './checker.mjs';
 import { resolveFileList } from './glob.mjs';
 import { generateReport } from './report.mjs';
 import { loadCustomRules } from './rules-loader.mjs';
@@ -11,19 +11,22 @@ import { checkDeadLinks } from './links.mjs';
 import { autoFixInsecureLinks } from './fixer.mjs';
 import { computeDocHealthScore, checkDocFreshness } from './quality.mjs';
 import {
-  computeHealthScore,
   generateJUnitReport,
   generateSarifReport,
   generateBadge
 } from './ci-output.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+const VERSION = pkg.version;
+
 function printHelp() {
   const b = (t) => c.bold(t);
   const d = (t) => c.dim(t);
   const y = (t) => c.yellow(t);
 
   console.log(`
-  ${b('Doclify Guardrail')} ${d('v1.0')}
+  ${b('Doclify Guardrail')} ${d(`v${VERSION}`)}
   Quality gate for Markdown documentation.
 
   ${y('USAGE')}
@@ -38,6 +41,8 @@ function printHelp() {
     --max-line-length <n>    Max line length ${d('(default: 160)')}
     --config <path>          Config file ${d('(default: .doclify-guardrail.json)')}
     --rules <path>           Custom regex rules from JSON file
+    --ignore-rules <list>    Disable rules ${d('(comma-separated)')}
+    --exclude <list>         Exclude files/patterns ${d('(comma-separated)')}
 
   ${y('CHECKS')}
     --check-links            Validate HTTP and local links
@@ -55,7 +60,11 @@ function printHelp() {
     --badge-label <text>     Badge label ${d('(default: "docs health")')}
     --json                   Output raw JSON to stdout
 
+  ${y('SETUP')}
+    init                     Generate a .doclify-guardrail.json config
+
   ${y('OTHER')}
+    --list-rules             List all built-in rules
     --no-color               Disable colored output
     --debug                  Show debug info
     -h, --help               Show this help
@@ -97,6 +106,8 @@ function parseArgs(argv) {
     maxLineLength: undefined,
     configPath: path.resolve('.doclify-guardrail.json'),
     help: false,
+    listRules: false,
+    init: false,
     dir: null,
     report: null,
     rules: null,
@@ -105,6 +116,8 @@ function parseArgs(argv) {
     badge: null,
     badgeLabel: 'docs health',
     noColor: false,
+    ignoreRules: [],
+    exclude: [],
     checkLinks: false,
     checkFreshness: false,
     fix: false,
@@ -120,6 +133,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '--list-rules') {
+      args.listRules = true;
+      continue;
+    }
+
     if (a === '--debug') {
       args.debug = true;
       continue;
@@ -135,6 +153,26 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '--ignore-rules') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error('Missing value for --ignore-rules');
+      }
+      args.ignoreRules.push(...value.split(',').map(s => s.trim()).filter(Boolean));
+      i += 1;
+      continue;
+    }
+
+    if (a === '--exclude') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error('Missing value for --exclude');
+      }
+      args.exclude.push(...value.split(',').map(s => s.trim()).filter(Boolean));
+      i += 1;
+      continue;
+    }
+
     if (a === '--check-links') {
       args.checkLinks = true;
       continue;
@@ -258,6 +296,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === 'init') {
+      args.init = true;
+      continue;
+    }
+
     if (a.startsWith('-')) {
       throw new Error(`Unknown option: ${a}`);
     }
@@ -276,6 +319,8 @@ function resolveOptions(args) {
   const cfg = parseConfigFile(args.configPath);
   const maxLineLength = Number(args.maxLineLength ?? cfg.maxLineLength ?? 160);
   const strict = Boolean(args.strict ?? cfg.strict ?? false);
+  const cfgIgnore = Array.isArray(cfg.ignoreRules) ? cfg.ignoreRules : [];
+  const ignoreRules = new Set([...args.ignoreRules, ...cfgIgnore]);
 
   if (!Number.isInteger(maxLineLength) || maxLineLength <= 0) {
     throw new Error(`Invalid maxLineLength in config: ${cfg.maxLineLength}`);
@@ -284,28 +329,34 @@ function resolveOptions(args) {
   return {
     maxLineLength,
     strict,
+    ignoreRules,
     configPath: args.configPath,
     configLoaded: fs.existsSync(args.configPath)
   };
 }
 
+function toRelativePath(filePath) {
+  const rel = path.relative(process.cwd(), filePath);
+  return rel.startsWith('..') ? filePath : rel || filePath;
+}
+
 function buildFileResult(filePath, analysis, opts) {
-  const pass = analysis.errors.length === 0 && (!opts.strict || analysis.warnings.length === 0);
+  const ignore = opts.ignoreRules || new Set();
+  const errors = ignore.size > 0 ? analysis.errors.filter(f => !ignore.has(f.code)) : analysis.errors;
+  const warnings = ignore.size > 0 ? analysis.warnings.filter(f => !ignore.has(f.code)) : analysis.warnings;
+  const pass = errors.length === 0 && (!opts.strict || warnings.length === 0);
   const healthScore = computeDocHealthScore({
-    errors: analysis.summary.errors,
-    warnings: analysis.summary.warnings
+    errors: errors.length,
+    warnings: warnings.length
   });
 
   return {
-    file: filePath,
+    file: toRelativePath(filePath),
     pass,
-    findings: {
-      errors: analysis.errors,
-      warnings: analysis.warnings
-    },
+    findings: { errors, warnings },
     summary: {
-      errors: analysis.summary.errors,
-      warnings: analysis.summary.warnings,
+      errors: errors.length,
+      warnings: warnings.length,
       healthScore,
       status: pass ? 'PASS' : 'FAIL'
     }
@@ -333,11 +384,10 @@ function buildOutput(fileResults, fileErrors, opts, elapsed, fixSummary) {
     elapsed: Math.round(elapsed * 1000) / 1000
   };
 
-  summary.avgHealthScore = avgHealthScore;
-  summary.healthScore = computeHealthScore(summary);
+  summary.healthScore = avgHealthScore;
 
   return {
-    version: '1.0',
+    version: VERSION,
     strict: opts.strict,
     files: fileResults,
     fileErrors: fileErrors.length > 0 ? fileErrors : undefined,
@@ -361,6 +411,47 @@ async function runCli(argv = process.argv.slice(2)) {
     return 0;
   }
 
+  if (args.listRules) {
+    initColors(args.noColor);
+    console.log('');
+    console.log(`  ${c.bold('Built-in rules')}`);
+    console.log('');
+    for (const rule of RULE_CATALOG) {
+      const sev = rule.severity === 'error' ? c.red('error  ') : c.yellow('warning');
+      console.log(`  ${c.cyan(rule.id.padEnd(22))} ${sev}  ${c.dim(rule.description)}`);
+    }
+    console.log('');
+    return 0;
+  }
+
+  if (args.init) {
+    initColors(args.noColor);
+    const configFile = '.doclify-guardrail.json';
+    const configPath = path.resolve(configFile);
+
+    if (fs.existsSync(configPath)) {
+      console.error(`  ${c.yellow('⚠')} ${c.bold(configFile)} already exists. Remove it first to re-initialize.`);
+      return 1;
+    }
+
+    const defaultConfig = {
+      strict: false,
+      maxLineLength: 160,
+      ignoreRules: [],
+      checkLinks: false,
+      checkFreshness: false
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
+    console.error('');
+    console.error(`  ${c.green('✓')} Created ${c.bold(configFile)}`);
+    console.error('');
+    console.error(`  ${c.dim('Edit the file to customise rules, then run:')}`)
+    console.error(`  ${c.dim('$')} ${c.cyan('doclify .')}`);
+    console.error('');
+    return 0;
+  }
+
   initColors(args.noColor);
 
   let filePaths;
@@ -371,6 +462,19 @@ async function runCli(argv = process.argv.slice(2)) {
     return 2;
   }
 
+  if (args.exclude.length > 0) {
+    filePaths = filePaths.filter(fp => {
+      const rel = path.relative(process.cwd(), fp);
+      return !args.exclude.some(pattern => {
+        if (pattern.includes('*')) {
+          const regex = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*') + '$');
+          return regex.test(rel);
+        }
+        return rel === pattern || rel.startsWith(pattern + path.sep) || path.basename(rel) === pattern;
+      });
+    });
+  }
+
   if (filePaths.length === 0) {
     console.error('Error: no markdown files found.');
     return 2;
@@ -394,7 +498,7 @@ async function runCli(argv = process.argv.slice(2)) {
     }
   }
 
-  printBanner(filePaths.length);
+  printBanner(filePaths.length, VERSION);
 
   if (resolved.configLoaded) {
     log(c.cyan('ℹ'), `Loaded config from ${c.dim(resolved.configPath)}`);
@@ -432,6 +536,11 @@ async function runCli(argv = process.argv.slice(2)) {
         if (fixed.modified) {
           fixSummary.filesChanged += 1;
           fixSummary.replacements += fixed.changes.length;
+          for (const change of fixed.changes) {
+            if (args.dryRun) {
+              log(c.dim('    '), c.yellow('~') + ` ${c.dim(change.from)} ${c.dim('→')} ${c.green(change.to)}`);
+            }
+          }
           if (!args.dryRun) {
             fs.writeFileSync(filePath, fixed.content, 'utf8');
           }
@@ -442,32 +551,37 @@ async function runCli(argv = process.argv.slice(2)) {
             file: filePath,
             urls: [...new Set(fixed.ambiguous)]
           });
+          for (const url of [...new Set(fixed.ambiguous)]) {
+            log(c.dim('    '), c.dim(`⊘ skipped ${url} (localhost/custom port)`));
+          }
         }
       }
 
+      const relPath = toRelativePath(filePath);
       const analysis = checkMarkdown(content, {
         maxLineLength: resolved.maxLineLength,
-        filePath,
+        filePath: relPath,
         customRules
       });
 
       if (args.checkLinks) {
         log(c.dim('  ↳'), c.dim(`Checking links...`));
         const deadLinks = await checkDeadLinks(content, { sourceFile: filePath });
+        for (const dl of deadLinks) { dl.source = relPath; }
         analysis.errors.push(...deadLinks);
         analysis.summary.errors = analysis.errors.length;
       }
 
       if (args.checkFreshness) {
         log(c.dim('  ↳'), c.dim(`Checking freshness...`));
-        const freshnessWarnings = checkDocFreshness(content, { sourceFile: filePath });
+        const freshnessWarnings = checkDocFreshness(content, { sourceFile: relPath });
         analysis.warnings.push(...freshnessWarnings);
         analysis.summary.warnings = analysis.warnings.length;
       }
 
-      fileResults.push(buildFileResult(filePath, analysis, { strict: resolved.strict }));
+      fileResults.push(buildFileResult(filePath, analysis, { strict: resolved.strict, ignoreRules: resolved.ignoreRules }));
     } catch (err) {
-      fileErrors.push({ file: filePath, error: err.message });
+      fileErrors.push({ file: toRelativePath(filePath), error: err.message });
     }
   }
 
@@ -480,6 +594,16 @@ async function runCli(argv = process.argv.slice(2)) {
 
   printResults(output);
 
+  if (args.fix && fixSummary.replacements > 0) {
+    const action = args.dryRun ? 'Would fix' : 'Fixed';
+    log(
+      args.dryRun ? c.yellow('~') : c.green('✓'),
+      `${action} ${c.bold(String(fixSummary.replacements))} insecure link${fixSummary.replacements === 1 ? '' : 's'} in ${c.bold(String(fixSummary.filesChanged))} file${fixSummary.filesChanged === 1 ? '' : 's'}${args.dryRun ? c.dim(' (dry-run, no files changed)') : ''}`
+    );
+  } else if (args.fix && fixSummary.replacements === 0) {
+    log(c.dim('ℹ'), c.dim('No insecure links to fix'));
+  }
+
   if (args.json) {
     console.log(JSON.stringify(output, null, 2));
   }

package/src/links.mjs

@@ -2,6 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { stripCodeBlocks, stripInlineCode } from './checker.mjs';
 
+const LINK_TIMEOUT_MS = 8000;
+const CONCURRENCY = 5;
+
 function extractLinks(content) {
   const stripped = stripCodeBlocks(content);
   const lines = stripped.split('\n');
@@ -42,20 +45,28 @@ function isSkippableUrl(url) {
 }
 
 async function checkRemoteUrl(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), LINK_TIMEOUT_MS);
+
   try {
-    const headRes = await fetch(url, { method: 'HEAD', redirect: 'follow' });
+    const headRes = await fetch(url, { method: 'HEAD', redirect: 'follow', signal: controller.signal });
+    clearTimeout(timer);
     if (headRes.status < 400) {
       return null;
     }
 
     if (headRes.status === 405 || headRes.status === 501) {
-      const getRes = await fetch(url, { method: 'GET', redirect: 'follow' });
+      const timer2 = setTimeout(() => controller.abort(), LINK_TIMEOUT_MS);
+      const getRes = await fetch(url, { method: 'GET', redirect: 'follow', signal: controller.signal });
+      clearTimeout(timer2);
       if (getRes.status < 400) return null;
       return `HTTP ${getRes.status}`;
     }
 
     return `HTTP ${headRes.status}`;
   } catch (err) {
+    clearTimeout(timer);
+    if (err.name === 'AbortError') return `Timeout (${LINK_TIMEOUT_MS / 1000}s)`;
     return err.message;
   }
 }
@@ -68,11 +79,30 @@ function checkLocalUrl(url, sourceFile) {
   return fs.existsSync(targetPath) ? null : 'Target not found';
 }
 
+async function runWithConcurrency(tasks, limit) {
+  const results = [];
+  let idx = 0;
+
+  async function worker() {
+    while (idx < tasks.length) {
+      const i = idx++;
+      results[i] = await tasks[i]();
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+
 async function checkDeadLinks(content, { sourceFile }) {
   const links = extractLinks(content);
   const findings = [];
   const seen = new Set();
 
+  // Local links first (sync, fast)
+  const remoteChecks = [];
+
   for (const link of links) {
     const url = link.url;
     if (!url || isSkippableUrl(url)) continue;
@@ -82,21 +112,11 @@ async function checkDeadLinks(content, { sourceFile }) {
     seen.add(dedupeKey);
 
     if (url.startsWith('http://') || url.startsWith('https://')) {
-      const error = await checkRemoteUrl(url);
-      if (error) {
-        findings.push({
-          code: 'dead-link',
-          severity: 'error',
-          line: link.line,
-          message: `Dead link: ${url} (${error})`,
-          source: sourceFile
-        });
-      }
+      remoteChecks.push({ url, link });
       continue;
     }
 
     if (url.startsWith('/')) {
-      // Absolute filesystem paths are intentionally ignored for portability.
       continue;
     }
 
@@ -112,7 +132,28 @@ async function checkDeadLinks(content, { sourceFile }) {
     }
   }
 
+  // Remote links in parallel with concurrency limit
+  if (remoteChecks.length > 0) {
+    const tasks = remoteChecks.map(({ url, link }) => async () => {
+      const error = await checkRemoteUrl(url);
+      return { url, link, error };
+    });
+
+    const results = await runWithConcurrency(tasks, CONCURRENCY);
+    for (const { url, link, error } of results) {
+      if (error) {
+        findings.push({
+          code: 'dead-link',
+          severity: 'error',
+          line: link.line,
+          message: `Dead link: ${url} (${error})`,
+          source: sourceFile
+        });
+      }
+    }
+  }
+
   return findings;
 }
 
-export { extractLinks, checkDeadLinks };
+export { extractLinks, checkDeadLinks };