doclify-guardrail 1.2.0 → 1.4.0

package/package.json

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

package/src/checker.mjs

@@ -14,7 +14,22 @@ const RULE_CATALOG = [
   { 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)' }
+  { id: 'stale-doc',          severity: 'warning', description: 'Warn on stale docs (requires --check-freshness)' },
+  { id: 'no-trailing-spaces',          severity: 'warning', description: 'No trailing whitespace' },
+  { id: 'no-multiple-blanks',          severity: 'warning', description: 'No multiple consecutive blank lines' },
+  { id: 'single-trailing-newline',     severity: 'warning', description: 'File must end with a single newline' },
+  { id: 'no-missing-space-atx',        severity: 'warning', description: 'Space required after # in headings' },
+  { id: 'heading-start-left',          severity: 'warning', description: 'Headings must not be indented' },
+  { id: 'no-trailing-punctuation-heading', severity: 'warning', description: 'No trailing punctuation in headings' },
+  { id: 'blanks-around-headings',      severity: 'warning', description: 'Blank line required around headings' },
+  { id: 'blanks-around-lists',         severity: 'warning', description: 'Blank line required around lists' },
+  { id: 'blanks-around-fences',        severity: 'warning', description: 'Blank line required around fenced code blocks' },
+  { id: 'fenced-code-language',        severity: 'warning', description: 'Fenced code blocks must specify a language' },
+  { id: 'no-bare-urls',                severity: 'warning', description: 'URLs must be wrapped in <> or []()' },
+  { id: 'no-reversed-links',           severity: 'warning', description: 'No reversed link syntax (text)[url]' },
+  { id: 'no-space-in-emphasis',        severity: 'warning', description: 'No spaces inside emphasis markers' },
+  { id: 'no-space-in-links',           severity: 'warning', description: 'No spaces inside link brackets' },
+  { id: 'no-inline-html',              severity: 'warning', description: 'No inline HTML (opt-in via --check-inline-html)' }
 ];
 
 const RULE_SEVERITY = Object.fromEntries(RULE_CATALOG.map(r => [r.id, r.severity]));
@@ -32,10 +47,10 @@ const PLACEHOLDER_PATTERNS = [
   { rx: /\bxxx\b/i,            msg: '"xxx" placeholder found' }
 ];
 
-function normalizeFinding(rule, message, line, source) {
+function normalizeFinding(rule, message, line, source, severityOverride) {
   const finding = {
     code: rule,
-    severity: RULE_SEVERITY[rule] || 'warning',
+    severity: severityOverride || RULE_SEVERITY[rule] || 'warning',
     message
   };
   if (line != null) finding.line = line;
@@ -86,9 +101,106 @@ function stripInlineCode(line) {
   return line.replace(/`[^`]+`/g, '');
 }
 
+const SUPPRESS_NEXT_LINE_RX = /<!--\s*doclify-disable-next-line\s*(.*?)\s*-->/;
+const SUPPRESS_BLOCK_START_RX = /<!--\s*doclify-disable\s*(.*?)\s*-->/;
+const SUPPRESS_BLOCK_END_RX = /<!--\s*doclify-enable\s*(.*?)\s*-->/;
+const SUPPRESS_FILE_RX = /<!--\s*doclify-disable-file\s*(.*?)\s*-->/;
+
+function parseRuleIds(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return null; // null means "all rules"
+  return trimmed.split(/\s+/);
+}
+
+/**
+ * Build a map of line numbers to sets of suppressed rule IDs.
+ * Uses code-block-stripped lines so comments inside fences are ignored.
+ * A suppressed set containing '*' means all rules are suppressed.
+ */
+function buildSuppressionMap(lines) {
+  const suppressions = new Map();
+  const activeDisables = new Map(); // ruleId → count (or '*' → count)
+
+  function addSuppression(lineNum, ruleIds) {
+    if (!suppressions.has(lineNum)) suppressions.set(lineNum, new Set());
+    const set = suppressions.get(lineNum);
+    if (ruleIds === null) {
+      set.add('*');
+    } else {
+      for (const id of ruleIds) set.add(id);
+    }
+  }
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    const nextLineMatch = line.match(SUPPRESS_NEXT_LINE_RX);
+    if (nextLineMatch) {
+      const ruleIds = parseRuleIds(nextLineMatch[1]);
+      addSuppression(i + 2, ruleIds); // i is 0-based, line numbers are 1-based, next line = i+2
+    }
+
+    const blockStartMatch = line.match(SUPPRESS_BLOCK_START_RX);
+    if (!nextLineMatch && blockStartMatch) {
+      const ruleIds = parseRuleIds(blockStartMatch[1]);
+      if (ruleIds === null) {
+        activeDisables.set('*', (activeDisables.get('*') || 0) + 1);
+      } else {
+        for (const id of ruleIds) activeDisables.set(id, (activeDisables.get(id) || 0) + 1);
+      }
+      continue;
+    }
+
+    const blockEndMatch = line.match(SUPPRESS_BLOCK_END_RX);
+    if (blockEndMatch) {
+      const ruleIds = parseRuleIds(blockEndMatch[1]);
+      if (ruleIds === null) {
+        activeDisables.delete('*');
+      } else {
+        for (const id of ruleIds) {
+          const count = activeDisables.get(id) || 0;
+          if (count <= 1) activeDisables.delete(id);
+          else activeDisables.set(id, count - 1);
+        }
+      }
+      continue;
+    }
+
+    // Apply active block disables to this line
+    if (activeDisables.size > 0) {
+      const lineNum = i + 1;
+      if (!suppressions.has(lineNum)) suppressions.set(lineNum, new Set());
+      const set = suppressions.get(lineNum);
+      for (const id of activeDisables.keys()) set.add(id);
+    }
+  }
+
+  return suppressions;
+}
+
+function isSuppressed(suppressions, finding) {
+  if (!finding.line) return false;
+  const set = suppressions.get(finding.line);
+  if (!set) return false;
+  return set.has('*') || set.has(finding.code);
+}
+
 function checkMarkdown(rawContent, opts = {}) {
   const maxLineLength = Number(opts.maxLineLength ?? DEFAULTS.maxLineLength);
   const filePath = opts.filePath || undefined;
+
+  // File-level suppression: <!-- doclify-disable-file [rules] -->
+  const fileDisableMatch = rawContent.match(SUPPRESS_FILE_RX);
+  let fileDisabledRules = null;
+  if (fileDisableMatch) {
+    const ruleIds = parseRuleIds(fileDisableMatch[1]);
+    if (ruleIds === null) {
+      // All rules disabled — short-circuit
+      return { errors: [], warnings: [], summary: { errors: 0, warnings: 0 } };
+    }
+    fileDisabledRules = new Set(ruleIds);
+  }
+
   const errors = [];
   const warnings = [];
 
@@ -97,8 +209,11 @@ function checkMarkdown(rawContent, opts = {}) {
   const lines = content.split('\n');
   const rawLines = rawContent.split('\n');
 
-  // Rule: frontmatter
-  if (!rawContent.startsWith('---\n')) {
+  // Build suppression map from inline comments (uses stripped content)
+  const suppressions = buildSuppressionMap(lines);
+
+  // Rule: frontmatter (opt-in via --check-frontmatter or config)
+  if (opts.checkFrontmatter && !rawContent.startsWith('---\n')) {
     warnings.push(normalizeFinding('frontmatter', 'Missing frontmatter block at the beginning of the file.', 1, filePath));
   }
 
@@ -114,14 +229,12 @@ function checkMarkdown(rawContent, opts = {}) {
     errors.push(normalizeFinding('single-h1', 'Missing H1 heading.', 1, filePath));
   } else if (h1Lines.length > 1) {
     const lineList = h1Lines.join(', ');
-    for (const lineNum of h1Lines) {
-      errors.push(normalizeFinding(
-        'single-h1',
-        `Found ${h1Lines.length} H1 headings (expected 1) at lines ${lineList}.`,
-        lineNum,
-        filePath
-      ));
-    }
+    errors.push(normalizeFinding(
+      'single-h1',
+      `Found ${h1Lines.length} H1 headings (expected 1) at lines ${lineList}.`,
+      h1Lines[0],
+      filePath
+    ));
   }
 
   // Rule: heading-hierarchy (h1→h3 without h2 is a skip)
@@ -141,12 +254,28 @@ function checkMarkdown(rawContent, opts = {}) {
     prevLevel = level;
   }
 
-  // Rule: duplicate-heading (same text at same level)
+  // Rule: duplicate-heading (scope-aware: H3-H6 scoped under nearest parent)
   const headingSeen = new Map();
+  const parentStack = new Array(7).fill(''); // indices 1-6 for heading levels
   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()}`;
+    const level = hMatch[1].length;
+    const text = hMatch[2].trim().toLowerCase();
+
+    // Update parent stack: set current level and clear deeper levels
+    parentStack[level] = text;
+    for (let l = level + 1; l <= 6; l += 1) parentStack[l] = '';
+
+    // H1-H2: global scope; H3-H6: scoped under parent chain
+    let key;
+    if (level <= 2) {
+      key = `${level}:${text}`;
+    } else {
+      const scope = parentStack.slice(1, level).join('|');
+      key = `${scope}|${level}:${text}`;
+    }
+
     if (headingSeen.has(key)) {
       warnings.push(normalizeFinding(
         'duplicate-heading',
@@ -241,6 +370,183 @@ function checkMarkdown(rawContent, opts = {}) {
     }
   });
 
+  // Rule: no-trailing-spaces (uses raw content)
+  rawLines.forEach((line, idx) => {
+    if (/[ \t]+$/.test(line)) {
+      warnings.push(normalizeFinding('no-trailing-spaces', 'Trailing whitespace found.', idx + 1, filePath));
+    }
+  });
+
+  // Rule: no-multiple-blanks (uses raw content)
+  {
+    let consecutiveBlanks = 0;
+    rawLines.forEach((line, idx) => {
+      if (line.trim() === '') {
+        consecutiveBlanks += 1;
+        if (consecutiveBlanks >= 2) {
+          warnings.push(normalizeFinding('no-multiple-blanks', 'Multiple consecutive blank lines.', idx + 1, filePath));
+        }
+      } else {
+        consecutiveBlanks = 0;
+      }
+    });
+  }
+
+  // Rule: single-trailing-newline (uses raw content)
+  if (rawContent.length > 0) {
+    if (!rawContent.endsWith('\n')) {
+      warnings.push(normalizeFinding('single-trailing-newline', 'File must end with a single newline.', rawLines.length, filePath));
+    } else if (rawContent.endsWith('\n\n')) {
+      warnings.push(normalizeFinding('single-trailing-newline', 'File has multiple trailing newlines.', rawLines.length, filePath));
+    }
+  }
+
+  // Rule: no-missing-space-atx (uses stripped content)
+  lines.forEach((line, idx) => {
+    if (/^#{1,6}[^\s#]/.test(line)) {
+      warnings.push(normalizeFinding('no-missing-space-atx', 'Missing space after # in heading.', idx + 1, filePath));
+    }
+  });
+
+  // Rule: heading-start-left (uses stripped content)
+  lines.forEach((line, idx) => {
+    if (/^\s+#{1,6}\s/.test(line)) {
+      warnings.push(normalizeFinding('heading-start-left', 'Heading must start at the beginning of the line.', idx + 1, filePath));
+    }
+  });
+
+  // Rule: no-trailing-punctuation-heading (uses stripped content)
+  lines.forEach((line, idx) => {
+    const hMatch = line.match(/^#{1,6}\s+(.+)$/);
+    if (hMatch) {
+      const text = hMatch[1].trim();
+      if (/[.,:;!]$/.test(text)) {
+        warnings.push(normalizeFinding('no-trailing-punctuation-heading', `Heading has trailing punctuation: "${text.slice(-1)}".`, idx + 1, filePath));
+      }
+    }
+  });
+
+  // Rule: blanks-around-headings (uses stripped content)
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!/^#{1,6}\s/.test(lines[i])) continue;
+    // Check line before heading (skip first line, skip frontmatter end)
+    if (i > 0 && lines[i - 1].trim() !== '' && lines[i - 1] !== '---') {
+      warnings.push(normalizeFinding('blanks-around-headings', 'Missing blank line before heading.', i + 1, filePath));
+    }
+    // Check line after heading
+    if (i < lines.length - 1 && lines[i + 1].trim() !== '') {
+      warnings.push(normalizeFinding('blanks-around-headings', 'Missing blank line after heading.', i + 1, filePath));
+    }
+  }
+
+  // Rule: blanks-around-lists (uses stripped content)
+  {
+    const isListItem = (l) => /^\s*[-*+]\s|^\s*\d+[.)]\s/.test(l);
+    for (let i = 0; i < lines.length; i += 1) {
+      if (!isListItem(lines[i])) continue;
+      // First list item — check blank before
+      if (i > 0 && !isListItem(lines[i - 1]) && lines[i - 1].trim() !== '') {
+        warnings.push(normalizeFinding('blanks-around-lists', 'Missing blank line before list.', i + 1, filePath));
+      }
+      // Last list item — check blank after
+      if (i < lines.length - 1 && !isListItem(lines[i + 1]) && lines[i + 1].trim() !== '') {
+        warnings.push(normalizeFinding('blanks-around-lists', 'Missing blank line after list.', i + 1, filePath));
+      }
+    }
+  }
+
+  // Rule: blanks-around-fences (uses raw content to detect fence lines)
+  {
+    let inFence = false;
+    for (let i = 0; i < rawLines.length; i += 1) {
+      const isFence = /^(`{3,}|~{3,})/.test(rawLines[i]);
+      if (isFence && !inFence) {
+        // Opening fence — check blank before
+        inFence = true;
+        if (i > 0 && rawLines[i - 1].trim() !== '') {
+          warnings.push(normalizeFinding('blanks-around-fences', 'Missing blank line before code block.', i + 1, filePath));
+        }
+      } else if (isFence && inFence) {
+        // Closing fence — check blank after
+        inFence = false;
+        if (i < rawLines.length - 1 && rawLines[i + 1].trim() !== '') {
+          warnings.push(normalizeFinding('blanks-around-fences', 'Missing blank line after code block.', i + 1, filePath));
+        }
+      }
+    }
+  }
+
+  // Rule: fenced-code-language (uses raw content)
+  rawLines.forEach((line, idx) => {
+    if (/^(`{3,}|~{3,})\s*$/.test(line)) {
+      // Only flag opening fences (not closing ones). Check if we're not inside a fence.
+      // Simple heuristic: count fences above this line
+      let fenceCount = 0;
+      for (let j = 0; j < idx; j += 1) {
+        if (/^(`{3,}|~{3,})/.test(rawLines[j])) fenceCount += 1;
+      }
+      if (fenceCount % 2 === 0) {
+        // Even count → this is an opening fence
+        warnings.push(normalizeFinding('fenced-code-language', 'Fenced code block without language specification.', idx + 1, filePath));
+      }
+    }
+  });
+
+  // Rule: no-bare-urls (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    // Match bare URLs not inside []() or <>
+    const bareRx = /(?<![(<\[])\bhttps?:\/\/[^\s>)]+/g;
+    let m;
+    while ((m = bareRx.exec(cleanLine)) !== null) {
+      const url = m[0];
+      const before = cleanLine.substring(0, m.index);
+      // Skip if inside markdown link [text](url) or <url>
+      if (/\]\($/.test(before) || before.endsWith('<')) continue;
+      // Skip if inside reference-style [label]: url
+      if (/^\[[^\]]*\]:\s*/.test(cleanLine)) continue;
+      warnings.push(normalizeFinding('no-bare-urls', `Bare URL found: ${url} — wrap in <> or use [text](url).`, idx + 1, filePath));
+    }
+  });
+
+  // Rule: no-reversed-links (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    if (/\([^)]+\)\[[^\]]+\]/.test(cleanLine)) {
+      warnings.push(normalizeFinding('no-reversed-links', 'Reversed link syntax: (text)[url] should be [text](url).', idx + 1, filePath));
+    }
+  });
+
+  // Rule: no-space-in-emphasis (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    if (/\*\*\s+[^*]+\s+\*\*/.test(cleanLine) || /\*\s+[^*]+\s+\*(?!\*)/.test(cleanLine)) {
+      warnings.push(normalizeFinding('no-space-in-emphasis', 'Spaces inside emphasis markers — may not render correctly.', idx + 1, filePath));
+    }
+  });
+
+  // Rule: no-space-in-links (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    if (/\[\s+[^\]]*\]\(/.test(cleanLine) || /\[[^\]]*\s+\]\(/.test(cleanLine)) {
+      warnings.push(normalizeFinding('no-space-in-links', 'Spaces inside link text brackets.', idx + 1, filePath));
+    }
+    if (/\]\(\s+[^)]*\)/.test(cleanLine) || /\]\([^)]*\s+\)/.test(cleanLine)) {
+      warnings.push(normalizeFinding('no-space-in-links', 'Spaces inside link URL parentheses.', idx + 1, filePath));
+    }
+  });
+
+  // Rule: no-inline-html (opt-in via --check-inline-html or config)
+  if (opts.checkInlineHtml) {
+    lines.forEach((line, idx) => {
+      const cleanLine = stripInlineCode(line);
+      // Match HTML tags but skip comments (<!-- -->)
+      if (/<[a-zA-Z/][^>]*>/.test(cleanLine) && !cleanLine.includes('<!--')) {
+        warnings.push(normalizeFinding('no-inline-html', 'Inline HTML found.', idx + 1, filePath));
+      }
+    });
+  }
+
   // Custom rules (uses stripped content)
   if (opts.customRules && opts.customRules.length > 0) {
     lines.forEach((line, idx) => {
@@ -249,18 +555,24 @@ function checkMarkdown(rawContent, opts = {}) {
         rule.pattern.lastIndex = 0;
         if (rule.pattern.test(cleanLine)) {
           const bucket = rule.severity === 'error' ? errors : warnings;
-          bucket.push(normalizeFinding(rule.id, rule.message, idx + 1, filePath));
+          bucket.push(normalizeFinding(rule.id, rule.message, idx + 1, filePath, rule.severity));
         }
       }
     });
   }
 
+  // Apply inline suppressions + file-level suppression
+  const isFileSuppressed = (f) =>
+    fileDisabledRules && (fileDisabledRules.has(f.code));
+  const filteredErrors = errors.filter(f => !isSuppressed(suppressions, f) && !isFileSuppressed(f));
+  const filteredWarnings = warnings.filter(f => !isSuppressed(suppressions, f) && !isFileSuppressed(f));
+
   return {
-    errors,
-    warnings,
+    errors: filteredErrors,
+    warnings: filteredWarnings,
     summary: {
-      errors: errors.length,
-      warnings: warnings.length
+      errors: filteredErrors.length,
+      warnings: filteredWarnings.length
     }
   };
 }

package/src/ci-output.mjs

@@ -1,5 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { RULE_CATALOG } from './checker.mjs';
+
+const RULE_DESCRIPTIONS = Object.fromEntries(RULE_CATALOG.map(r => [r.id, r.description]));
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -86,7 +89,7 @@ function collectRuleCatalog(output) {
           id: finding.code,
           name: finding.code,
           shortDescription: { text: finding.code },
-          help: { text: finding.message || finding.code },
+          help: { text: RULE_DESCRIPTIONS[finding.code] || finding.message || finding.code },
           defaultConfiguration: {
             level: finding.severity === 'error' ? 'error' : 'warning'
           }

package/src/colors.mjs

@@ -9,6 +9,7 @@ const CODES = {
 };
 
 let enabled = true;
+let asciiMode = false;
 
 function initColors(noColorFlag) {
   if (noColorFlag || !process.stderr.isTTY || process.env.NO_COLOR !== undefined) {
@@ -16,6 +17,10 @@ function initColors(noColorFlag) {
   }
 }
 
+function setAsciiMode(flag) {
+  asciiMode = Boolean(flag);
+}
+
 function wrap(code, text) {
   if (!enabled) return text;
   return `${code}${text}${CODES.reset}`;
@@ -30,6 +35,14 @@ const c = {
   bold: (t) => wrap(CODES.bold, t)
 };
 
+const icons = {
+  get pass() { return asciiMode ? '[PASS]' : '\u2713'; },
+  get fail() { return asciiMode ? '[FAIL]' : '\u2717'; },
+  get warn() { return asciiMode ? '[WARN]' : '\u26A0'; },
+  get info() { return asciiMode ? '[INFO]' : '\u2139'; },
+  get dot()  { return asciiMode ? '-' : '\u00B7'; }
+};
+
 function log(icon, message) {
   console.error(`  ${icon} ${message}`);
 }
@@ -38,12 +51,13 @@ function printBanner(fileCount, version) {
   console.error('');
   console.error(`  ${c.bold('Doclify Guardrail')} ${c.dim(`v${version || '?'}`)}`);
   console.error('');
-  log(c.cyan('ℹ'), `Scanning ${c.bold(String(fileCount))} file${fileCount === 1 ? '' : 's'}...`);
+  log(c.cyan(icons.info), `Scanning ${c.bold(String(fileCount))} file${fileCount === 1 ? '' : 's'}...`);
 }
 
 function printResults(output) {
+  const strict = output.strict;
   for (const fileResult of output.files) {
-    const icon = fileResult.pass ? c.green('\u2713') : c.red('\u2717');
+    const icon = fileResult.pass ? c.green(icons.pass) : c.red(icons.fail);
     const fileName = c.bold(fileResult.file);
     const score = fileResult.summary.healthScore != null ? c.dim(` [${fileResult.summary.healthScore}/100]`) : '';
     console.error(`  ${icon} ${fileName}${score}`);
@@ -55,16 +69,21 @@ function printResults(output) {
 
     for (const f of allFindings) {
       const lineStr = f.line != null ? c.dim(`:${f.line}`) : '';
-      const sevLabel = f.severity === 'error'
-        ? c.red(`\u2717 ${f.severity}`)
-        : c.yellow(`\u26A0 ${f.severity}`);
+      let sevLabel;
+      if (f.severity === 'error') {
+        sevLabel = c.red(`${icons.fail} error`);
+      } else if (strict) {
+        sevLabel = c.red(`${icons.fail} error [strict]`);
+      } else {
+        sevLabel = c.yellow(`${icons.warn} warning`);
+      }
       console.error(`      ${sevLabel}  ${c.cyan(f.code)}${lineStr}  ${f.message}`);
     }
   }
 
   if (output.fileErrors) {
     for (const fe of output.fileErrors) {
-      console.error(`  ${c.red('\u2717')} ${c.bold(fe.file)}  ${c.red(fe.error)}`);
+      console.error(`  ${c.red(icons.fail)} ${c.bold(fe.file)}  ${c.red(fe.error)}`);
     }
   }
 
@@ -72,11 +91,11 @@ function printResults(output) {
 
   const s = output.summary;
   const parts = [];
-  if (s.filesPassed > 0) parts.push(c.green(`\u2713 ${s.filesPassed} passed`));
-  if (s.filesFailed > 0) parts.push(c.red(`\u2717 ${s.filesFailed} failed`));
+  if (s.filesPassed > 0) parts.push(c.green(`${icons.pass} ${s.filesPassed} passed`));
+  if (s.filesFailed > 0) parts.push(c.red(`${icons.fail} ${s.filesFailed} failed`));
   if (s.filesErrored > 0) parts.push(c.red(`${s.filesErrored} errored`));
   console.error(
-    `  ${parts.join(c.dim(' \u00B7 '))} ${c.dim('\u00B7')} ${s.filesScanned} files scanned in ${c.dim(`${s.elapsed}s`)}`
+    `  ${parts.join(c.dim(` ${icons.dot} `))} ${c.dim(icons.dot)} ${s.filesScanned} files scanned in ${c.dim(`${s.elapsed}s`)}`
   );
 
   const scoreValue = s.healthScore != null ? s.healthScore : s.avgHealthScore;
@@ -93,4 +112,4 @@ function printResults(output) {
   console.error('');
 }
 
-export { initColors, c, log, printBanner, printResults };
+export { initColors, setAsciiMode, icons, c, log, printBanner, printResults };

package/src/fixer.mjs

@@ -14,20 +14,52 @@ function autoFixInsecureLinks(content) {
   const changes = [];
   const ambiguous = [];
 
-  const fixed = content.replace(/http:\/\/\S+/g, (raw) => {
-    const cleaned = raw.replace(/[),.;!?]+$/g, '');
-    if (isAmbiguousHttpUrl(cleaned)) {
-      ambiguous.push(cleaned);
-      return raw;
-    }
+  const lines = content.split('\n');
+  let inCodeBlock = false;
+  let fenceChar = null;
+  let fenceLen = 0;
 
-    const replaced = raw.replace('http://', 'https://');
-    if (replaced !== raw) {
-      changes.push({ from: raw, to: replaced });
+  const processedLines = lines.map((line) => {
+    // Track fenced code blocks (same logic as stripCodeBlocks in checker.mjs)
+    if (!inCodeBlock) {
+      const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+      if (fenceMatch) {
+        inCodeBlock = true;
+        fenceChar = fenceMatch[1][0];
+        fenceLen = fenceMatch[1].length;
+        return line;
+      }
+    } else {
+      const closeMatch = line.match(/^(`{3,}|~{3,})\s*$/);
+      if (closeMatch && closeMatch[1][0] === fenceChar && closeMatch[1].length >= fenceLen) {
+        inCodeBlock = false;
+        fenceChar = null;
+        fenceLen = 0;
+      }
+      return line;
     }
-    return replaced;
+
+    // Outside code blocks: replace http:// but skip inline code spans
+    return line.replace(/(`[^`]*`)|http:\/\/\S+/g, (match, inlineCode) => {
+      if (inlineCode) return inlineCode;
+
+      const raw = match;
+      const cleaned = raw.replace(/[),.;!?]+$/g, '');
+      if (isAmbiguousHttpUrl(cleaned)) {
+        ambiguous.push(cleaned);
+        return raw;
+      }
+
+      const replaced = raw.replace('http://', 'https://');
+      if (replaced !== raw) {
+        changes.push({ from: cleaned, to: cleaned.replace('http://', 'https://') });
+      }
+      return replaced;
+    });
   });
 
+  const fixed = processedLines.join('\n');
+
   return {
     content: fixed,
     modified: fixed !== content,
@@ -36,4 +68,176 @@ function autoFixInsecureLinks(content) {
   };
 }
 
-export { autoFixInsecureLinks, isAmbiguousHttpUrl };
+function autoFixFormatting(content) {
+  const changes = [];
+  let lines = content.split('\n');
+
+  // Track code blocks to skip them
+  let inCodeBlock = false;
+  let fenceChar = null;
+  let fenceLen = 0;
+  const inCode = lines.map((line) => {
+    if (!inCodeBlock) {
+      const fm = line.match(/^(`{3,}|~{3,})/);
+      if (fm) { inCodeBlock = true; fenceChar = fm[1][0]; fenceLen = fm[1].length; return true; }
+      return false;
+    }
+    const cm = line.match(/^(`{3,}|~{3,})\s*$/);
+    if (cm && cm[1][0] === fenceChar && cm[1].length >= fenceLen) {
+      inCodeBlock = false; fenceChar = null; fenceLen = 0;
+    }
+    return true;
+  });
+
+  // Pass 1: line-level fixes
+  lines = lines.map((line, i) => {
+    if (inCode[i]) return line;
+    let fixed = line;
+
+    // Fix: trailing spaces
+    const trimmed = fixed.replace(/[ \t]+$/, '');
+    if (trimmed !== fixed) { changes.push({ rule: 'no-trailing-spaces', line: i + 1 }); fixed = trimmed; }
+
+    // Fix: missing space after # in heading
+    const atxMatch = fixed.match(/^(#{1,6})([^\s#])/);
+    if (atxMatch) { changes.push({ rule: 'no-missing-space-atx', line: i + 1 }); fixed = atxMatch[1] + ' ' + fixed.slice(atxMatch[1].length); }
+
+    // Fix: indented heading
+    const indentMatch = fixed.match(/^(\s+)(#{1,6}\s)/);
+    if (indentMatch) { changes.push({ rule: 'heading-start-left', line: i + 1 }); fixed = fixed.trimStart(); }
+
+    // Fix: trailing punctuation in heading
+    const hMatch = fixed.match(/^(#{1,6}\s+.+?)([.,:;!])$/);
+    if (hMatch) { changes.push({ rule: 'no-trailing-punctuation-heading', line: i + 1 }); fixed = hMatch[1]; }
+
+    // Fix: reversed links (text)[url] → [text](url)
+    fixed = fixed.replace(/\(([^)]+)\)\[([^\]]+)\]/g, (match, text, url) => {
+      changes.push({ rule: 'no-reversed-links', line: i + 1 });
+      return `[${text}](${url})`;
+    });
+
+    // Fix: spaces in emphasis ** text ** → **text**
+    fixed = fixed.replace(/\*\*\s+([^*]+?)\s+\*\*/g, (match, inner) => {
+      changes.push({ rule: 'no-space-in-emphasis', line: i + 1 });
+      return `**${inner}**`;
+    });
+    fixed = fixed.replace(/(?<!\*)\*\s+([^*]+?)\s+\*(?!\*)/g, (match, inner) => {
+      changes.push({ rule: 'no-space-in-emphasis', line: i + 1 });
+      return `*${inner}*`;
+    });
+
+    // Fix: spaces in links [ text ](url) → [text](url)
+    fixed = fixed.replace(/\[\s+([^\]]*?)\s*\]\(/g, (match, text) => {
+      changes.push({ rule: 'no-space-in-links', line: i + 1 });
+      return `[${text}](`;
+    });
+    fixed = fixed.replace(/\]\(\s+([^)]*?)\s*\)/g, (match, url) => {
+      changes.push({ rule: 'no-space-in-links', line: i + 1 });
+      return `](${url})`;
+    });
+
+    // Fix: bare URLs → wrap in <>
+    fixed = fixed.replace(/(`[^`]*`)|(?<![(<\[])\bhttps?:\/\/[^\s>)]+/g, (match, code) => {
+      if (code) return code;
+      // Don't wrap if already inside markdown link or reference
+      changes.push({ rule: 'no-bare-urls', line: i + 1 });
+      return `<${match}>`;
+    });
+
+    return fixed;
+  });
+
+  // Pass 2: multi-line fixes (blanks around headings/lists/fences, multiple blanks)
+  const result = [];
+  const isListItem = (l) => /^\s*[-*+]\s|^\s*\d+[.)]\s/.test(l);
+  const isHeading = (l) => /^#{1,6}\s/.test(l);
+  const isFenceOpen = (l) => /^(`{3,}|~{3,})/.test(l);
+
+  // Rebuild inCode flags after line-level fixes
+  inCodeBlock = false;
+  fenceChar = null;
+  fenceLen = 0;
+  const inCode2 = lines.map((line) => {
+    if (!inCodeBlock) {
+      const fm = line.match(/^(`{3,}|~{3,})/);
+      if (fm) { inCodeBlock = true; fenceChar = fm[1][0]; fenceLen = fm[1].length; return true; }
+      return false;
+    }
+    const cm = line.match(/^(`{3,}|~{3,})\s*$/);
+    if (cm && cm[1][0] === fenceChar && cm[1].length >= fenceLen) {
+      inCodeBlock = false; fenceChar = null; fenceLen = 0;
+    }
+    return true;
+  });
+
+  let prevBlank = true; // treat start of file as blank
+  let consecutiveBlanks = 0;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const isBlank = line.trim() === '';
+    const codeFlag = inCode2[i];
+
+    // Fix: multiple consecutive blanks (outside code blocks)
+    if (isBlank && !codeFlag) {
+      consecutiveBlanks += 1;
+      if (consecutiveBlanks >= 2) {
+        changes.push({ rule: 'no-multiple-blanks', line: i + 1 });
+        continue; // skip extra blank
+      }
+    } else {
+      consecutiveBlanks = 0;
+    }
+
+    // Fix: blank before heading/list/fence (only if not already preceded by blank)
+    if (!codeFlag && !prevBlank && !isBlank) {
+      const needsBlankBefore = isHeading(line) || (isListItem(line) && i > 0 && !isListItem(lines[i - 1])) || isFenceOpen(line);
+      if (needsBlankBefore) {
+        const ruleId = isHeading(line) ? 'blanks-around-headings' : isListItem(line) ? 'blanks-around-lists' : 'blanks-around-fences';
+        changes.push({ rule: ruleId, line: i + 1 });
+        result.push('');
+      }
+    }
+
+    result.push(line);
+
+    // Fix: blank after heading/fence-close/last-list-item
+    if (!codeFlag && !isBlank) {
+      const nextLine = lines[i + 1];
+      const nextIsBlank = nextLine === undefined || nextLine.trim() === '';
+      if (!nextIsBlank && nextLine !== undefined) {
+        const nextCode = inCode2[i + 1];
+        if (!nextCode) {
+          const needsBlankAfter = isHeading(line) ||
+            (isListItem(line) && !isListItem(nextLine)) ||
+            (isFenceOpen(line) === false && i > 0 && /^(`{3,}|~{3,})\s*$/.test(line));
+          if (needsBlankAfter) {
+            const ruleId = isHeading(line) ? 'blanks-around-headings' : isListItem(line) ? 'blanks-around-lists' : 'blanks-around-fences';
+            changes.push({ rule: ruleId, line: i + 1 });
+            result.push('');
+          }
+        }
+      }
+    }
+
+    prevBlank = isBlank;
+  }
+
+  // Fix: single trailing newline
+  let fixed = result.join('\n');
+  if (fixed.length > 0) {
+    const trimmedEnd = fixed.replace(/\n+$/, '');
+    if (trimmedEnd + '\n' !== fixed) {
+      changes.push({ rule: 'single-trailing-newline', line: result.length });
+      fixed = trimmedEnd + '\n';
+    }
+  }
+
+  return {
+    content: fixed,
+    modified: fixed !== content,
+    changes
+  };
+}
+
+export { autoFixInsecureLinks, autoFixFormatting, isAmbiguousHttpUrl };

package/src/index.mjs

@@ -6,9 +6,9 @@ import { checkMarkdown, RULE_CATALOG } from './checker.mjs';
 import { resolveFileList } from './glob.mjs';
 import { generateReport } from './report.mjs';
 import { loadCustomRules } from './rules-loader.mjs';
-import { initColors, c, log, printBanner, printResults } from './colors.mjs';
+import { initColors, setAsciiMode, icons, c, log, printBanner, printResults } from './colors.mjs';
 import { checkDeadLinks } from './links.mjs';
-import { autoFixInsecureLinks } from './fixer.mjs';
+import { autoFixInsecureLinks, autoFixFormatting } from './fixer.mjs';
 import { computeDocHealthScore, checkDocFreshness } from './quality.mjs';
 import {
   generateJUnitReport,
@@ -17,6 +17,19 @@ import {
 } from './ci-output.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function writeJsonToStdout(data) {
+  return new Promise((resolve, reject) => {
+    const json = JSON.stringify(data, null, 2) + '\n';
+    const flushed = process.stdout.write(json, 'utf8');
+    if (flushed) {
+      resolve();
+    } else {
+      process.stdout.once('drain', resolve);
+      process.stdout.once('error', reject);
+    }
+  });
+}
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 const VERSION = pkg.version;
 
@@ -47,6 +60,8 @@ function printHelp() {
   ${y('CHECKS')}
     --check-links            Validate HTTP and local links
     --check-freshness        Warn on stale docs ${d('(>180 days)')}
+    --check-frontmatter      Require YAML frontmatter block
+    --link-allow-list <list> Skip URLs/domains for link checks ${d('(comma-separated)')}
 
   ${y('FIX')}
     --fix                    Auto-fix safe issues ${d('(http → https)')}
@@ -62,10 +77,12 @@ function printHelp() {
 
   ${y('SETUP')}
     init                     Generate a .doclify-guardrail.json config
+    init --force             Overwrite existing config
 
   ${y('OTHER')}
     --list-rules             List all built-in rules
     --no-color               Disable colored output
+    --ascii                  Use ASCII icons ${d('(for CI without UTF-8)')}
     --debug                  Show debug info
     -h, --help               Show this help
 
@@ -106,6 +123,7 @@ function parseArgs(argv) {
     maxLineLength: undefined,
     configPath: path.resolve('.doclify-guardrail.json'),
     help: false,
+    version: false,
     listRules: false,
     init: false,
     dir: null,
@@ -120,9 +138,14 @@ function parseArgs(argv) {
     exclude: [],
     checkLinks: false,
     checkFreshness: false,
+    checkFrontmatter: false,
+    checkInlineHtml: false,
+    linkAllowList: [],
     fix: false,
     dryRun: false,
-    json: false
+    json: false,
+    force: false,
+    ascii: false
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -133,6 +156,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '-v' || a === '--version') {
+      args.version = true;
+      continue;
+    }
+
     if (a === '--list-rules') {
       args.listRules = true;
       continue;
@@ -183,6 +211,26 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '--check-frontmatter') {
+      args.checkFrontmatter = true;
+      continue;
+    }
+
+    if (a === '--check-inline-html') {
+      args.checkInlineHtml = true;
+      continue;
+    }
+
+    if (a === '--link-allow-list') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error('Missing value for --link-allow-list');
+      }
+      args.linkAllowList.push(...value.split(',').map(s => s.trim()).filter(Boolean));
+      i += 1;
+      continue;
+    }
+
     if (a === '--fix') {
       args.fix = true;
       continue;
@@ -198,6 +246,16 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '--force') {
+      args.force = true;
+      continue;
+    }
+
+    if (a === '--ascii') {
+      args.ascii = true;
+      continue;
+    }
+
     if (a === '--config') {
       const value = argv[i + 1];
       if (!value || value.startsWith('-')) {
@@ -326,10 +384,19 @@ function resolveOptions(args) {
     throw new Error(`Invalid maxLineLength in config: ${cfg.maxLineLength}`);
   }
 
+  const checkFrontmatter = Boolean(args.checkFrontmatter || cfg.checkFrontmatter || args.checkFreshness || cfg.checkFreshness);
+  const cfgAllowList = Array.isArray(cfg.linkAllowList) ? cfg.linkAllowList : [];
+  const linkAllowList = [...args.linkAllowList, ...cfgAllowList];
+  const cfgExclude = Array.isArray(cfg.exclude) ? cfg.exclude : [];
+  const exclude = [...args.exclude, ...cfgExclude];
+
   return {
     maxLineLength,
     strict,
     ignoreRules,
+    checkFrontmatter,
+    linkAllowList,
+    exclude,
     configPath: args.configPath,
     configLoaded: fs.existsSync(args.configPath)
   };
@@ -385,6 +452,7 @@ function buildOutput(fileResults, fileErrors, opts, elapsed, fixSummary) {
   };
 
   summary.healthScore = avgHealthScore;
+  summary.avgHealthScore = avgHealthScore; // Backward-compatible alias for existing integrations/tests
 
   return {
     version: VERSION,
@@ -411,8 +479,14 @@ async function runCli(argv = process.argv.slice(2)) {
     return 0;
   }
 
+  if (args.version) {
+    console.log(VERSION);
+    return 0;
+  }
+
   if (args.listRules) {
     initColors(args.noColor);
+    setAsciiMode(args.ascii);
     console.log('');
     console.log(`  ${c.bold('Built-in rules')}`);
     console.log('');
@@ -426,11 +500,13 @@ async function runCli(argv = process.argv.slice(2)) {
 
   if (args.init) {
     initColors(args.noColor);
+    setAsciiMode(args.ascii);
     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.`);
+    const configExists = fs.existsSync(configPath);
+    if (configExists && !args.force) {
+      console.error(`  ${c.yellow(icons.warn)} ${c.bold(configFile)} already exists. Use ${c.bold('--force')} to overwrite.`);
       return 1;
     }
 
@@ -438,13 +514,16 @@ async function runCli(argv = process.argv.slice(2)) {
       strict: false,
       maxLineLength: 160,
       ignoreRules: [],
+      exclude: [],
       checkLinks: false,
-      checkFreshness: false
+      checkFreshness: false,
+      checkFrontmatter: false,
+      linkAllowList: []
     };
 
     fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
     console.error('');
-    console.error(`  ${c.green('✓')} Created ${c.bold(configFile)}`);
+    console.error(`  ${c.green(icons.pass)} ${configExists ? 'Overwrote' : '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 .')}`);
@@ -453,6 +532,7 @@ async function runCli(argv = process.argv.slice(2)) {
   }
 
   initColors(args.noColor);
+  setAsciiMode(args.ascii);
 
   let filePaths;
   try {
@@ -462,15 +542,24 @@ async function runCli(argv = process.argv.slice(2)) {
     return 2;
   }
 
-  if (args.exclude.length > 0) {
+  let resolved;
+  try {
+    resolved = resolveOptions(args);
+  } catch (err) {
+    console.error(err.message);
+    return 2;
+  }
+
+  if (resolved.exclude.length > 0) {
     filePaths = filePaths.filter(fp => {
       const rel = path.relative(process.cwd(), fp);
-      return !args.exclude.some(pattern => {
+      return !resolved.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;
+        const segments = rel.split(path.sep);
+        return segments.includes(pattern);
       });
     });
   }
@@ -480,14 +569,6 @@ async function runCli(argv = process.argv.slice(2)) {
     return 2;
   }
 
-  let resolved;
-  try {
-    resolved = resolveOptions(args);
-  } catch (err) {
-    console.error(err.message);
-    return 2;
-  }
-
   let customRules = [];
   if (args.rules) {
     try {
@@ -501,7 +582,7 @@ async function runCli(argv = process.argv.slice(2)) {
   printBanner(filePaths.length, VERSION);
 
   if (resolved.configLoaded) {
-    log(c.cyan('ℹ'), `Loaded config from ${c.dim(resolved.configPath)}`);
+    log(c.cyan(icons.info), `Loaded config from ${c.dim(resolved.configPath)}`);
   }
 
   const startTime = process.hrtime.bigint();
@@ -517,7 +598,17 @@ async function runCli(argv = process.argv.slice(2)) {
 
   let customRulesCount = customRules.length;
   if (customRulesCount > 0) {
-    log(c.cyan('ℹ'), `Loaded ${c.bold(String(customRulesCount))} custom rules from ${c.dim(args.rules)}`);
+    log(c.cyan(icons.info), `Loaded ${c.bold(String(customRulesCount))} custom rules from ${c.dim(args.rules)}`);
+  }
+
+  if (resolved.ignoreRules.size > 0) {
+    const knownIds = new Set(RULE_CATALOG.map(r => r.id));
+    for (const id of customRules) knownIds.add(id.id);
+    for (const id of resolved.ignoreRules) {
+      if (!knownIds.has(id)) {
+        log(c.yellow(icons.warn), `Unknown rule "${c.bold(id)}" in --ignore-rules (ignored)`);
+      }
+    }
   }
 
   console.error('');
@@ -525,12 +616,13 @@ async function runCli(argv = process.argv.slice(2)) {
   for (const filePath of filePaths) {
     const rel = path.relative(process.cwd(), filePath);
     const shortPath = rel.startsWith('..') ? filePath : rel || filePath;
-    log(c.cyan('ℹ'), `Checking ${c.bold(shortPath)}...`);
+    log(c.cyan(icons.info), `Checking ${c.bold(shortPath)}...`);
 
     try {
       let content = fs.readFileSync(filePath, 'utf8');
 
       if (args.fix) {
+        // 1. Insecure links fix (http:// → https://)
         log(c.dim('  ↳'), c.dim(`Auto-fixing insecure links...`));
         const fixed = autoFixInsecureLinks(content);
         if (fixed.modified) {
@@ -542,9 +634,8 @@ async function runCli(argv = process.argv.slice(2)) {
             }
           }
           if (!args.dryRun) {
-            fs.writeFileSync(filePath, fixed.content, 'utf8');
+            content = fixed.content;
           }
-          content = fixed.content;
         }
         if (fixed.ambiguous.length > 0) {
           fixSummary.ambiguousSkipped.push({
@@ -555,18 +646,35 @@ async function runCli(argv = process.argv.slice(2)) {
             log(c.dim('    '), c.dim(`⊘ skipped ${url} (localhost/custom port)`));
           }
         }
+
+        // 2. Formatting fixes (trailing spaces, blanks, headings, bare URLs, etc.)
+        const formatted = autoFixFormatting(content);
+        if (formatted.modified) {
+          if (!args.dryRun) {
+            content = formatted.content;
+          }
+          const ruleSet = new Set(formatted.changes.map(ch => ch.rule));
+          log(c.dim('  ↳'), c.dim(`Formatting: ${formatted.changes.length} fix${formatted.changes.length === 1 ? '' : 'es'} (${[...ruleSet].join(', ')})${args.dryRun ? ' [dry-run]' : ''}`));
+        }
+
+        // Write all changes to disk
+        if (!args.dryRun && (fixed.modified || formatted.modified)) {
+          fs.writeFileSync(filePath, content, 'utf8');
+        }
       }
 
       const relPath = toRelativePath(filePath);
       const analysis = checkMarkdown(content, {
         maxLineLength: resolved.maxLineLength,
         filePath: relPath,
-        customRules
+        customRules,
+        checkFrontmatter: resolved.checkFrontmatter,
+        checkInlineHtml: Boolean(args.checkInlineHtml)
       });
 
       if (args.checkLinks) {
         log(c.dim('  ↳'), c.dim(`Checking links...`));
-        const deadLinks = await checkDeadLinks(content, { sourceFile: filePath });
+        const deadLinks = await checkDeadLinks(content, { sourceFile: filePath, linkAllowList: resolved.linkAllowList });
         for (const dl of deadLinks) { dl.source = relPath; }
         analysis.errors.push(...deadLinks);
         analysis.summary.errors = analysis.errors.length;
@@ -597,21 +705,21 @@ async function runCli(argv = process.argv.slice(2)) {
   if (args.fix && fixSummary.replacements > 0) {
     const action = args.dryRun ? 'Would fix' : 'Fixed';
     log(
-      args.dryRun ? c.yellow('~') : c.green('✓'),
+      args.dryRun ? c.yellow('~') : c.green(icons.pass),
       `${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'));
+    log(c.dim(icons.info), c.dim('No insecure links to fix'));
   }
 
   if (args.json) {
-    console.log(JSON.stringify(output, null, 2));
+    await writeJsonToStdout(output);
   }
 
   if (args.report) {
     try {
       const reportPath = generateReport(output, { reportPath: args.report });
-      log(c.green('✓'), `Report written ${c.dim('→')} ${reportPath}`);
+      log(c.green(icons.pass), `Report written ${c.dim('→')} ${reportPath}`);
     } catch (err) {
       console.error(`Failed to write report: ${err.message}`);
       return 2;
@@ -621,7 +729,7 @@ async function runCli(argv = process.argv.slice(2)) {
   if (args.junit) {
     try {
       const junitPath = generateJUnitReport(output, { junitPath: args.junit });
-      log(c.green('✓'), `JUnit report written ${c.dim('→')} ${junitPath}`);
+      log(c.green(icons.pass), `JUnit report written ${c.dim('→')} ${junitPath}`);
     } catch (err) {
       console.error(`Failed to write JUnit report: ${err.message}`);
       return 2;
@@ -631,7 +739,7 @@ async function runCli(argv = process.argv.slice(2)) {
   if (args.sarif) {
     try {
       const sarifPath = generateSarifReport(output, { sarifPath: args.sarif });
-      log(c.green('✓'), `SARIF report written ${c.dim('→')} ${sarifPath}`);
+      log(c.green(icons.pass), `SARIF report written ${c.dim('→')} ${sarifPath}`);
     } catch (err) {
       console.error(`Failed to write SARIF report: ${err.message}`);
       return 2;
@@ -641,7 +749,7 @@ async function runCli(argv = process.argv.slice(2)) {
   if (args.badge) {
     try {
       const badge = generateBadge(output, { badgePath: args.badge, label: args.badgeLabel });
-      log(c.green('✓'), `Badge written ${c.dim('→')} ${badge.badgePath} ${c.dim(`(score ${badge.score})`)}`);
+      log(c.green(icons.pass), `Badge written ${c.dim('→')} ${badge.badgePath} ${c.dim(`(score ${badge.score})`)}`);
     } catch (err) {
       console.error(`Failed to write badge: ${err.message}`);
       return 2;

package/src/links.mjs

@@ -14,7 +14,7 @@ function extractLinks(content) {
     const line = stripInlineCode(lines[idx]);
     const lineNumber = idx + 1;
 
-    const inlineRx = /\[[^\]]*\]\(([^)]+)\)/g;
+    const inlineRx = /\[[^\]]*\]\(([^()\s]*(?:\([^)]*\)[^()\s]*)*)\)/g;
     let inline;
     while ((inline = inlineRx.exec(line)) !== null) {
       links.push({ url: inline[1].trim(), line: lineNumber, kind: 'inline' });
@@ -33,10 +33,10 @@ function extractLinks(content) {
     }
   }
 
-  // Remove trailing punctuation from bare URL captures
+  // Remove trailing punctuation from bare/reference URL captures (not inline — already delimited by markdown syntax)
   return links.map((l) => ({
     ...l,
-    url: l.url.replace(/[),.;!?]+$/g, '')
+    url: l.kind === 'inline' ? l.url : l.url.replace(/[),.;!?]+$/g, '')
   }));
 }
 
@@ -44,6 +44,28 @@ function isSkippableUrl(url) {
   return url.startsWith('mailto:') || url.startsWith('tel:') || url.startsWith('#');
 }
 
+function isAllowListed(url, allowList) {
+  if (!allowList || allowList.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(url); } catch { return false; }
+  for (const pattern of allowList) {
+    // Wildcard pattern: "https://wger.de/*" → prefix match
+    if (pattern.includes('/') && pattern.endsWith('*')) {
+      const prefix = pattern.slice(0, -1);
+      if (url.startsWith(prefix)) return true;
+      continue;
+    }
+    // Full URL match
+    if (pattern.includes('/')) {
+      if (url === pattern) return true;
+      continue;
+    }
+    // Domain-only: suffix match on hostname (e.g. "wger.de" matches "api.wger.de")
+    if (parsed.hostname === pattern || parsed.hostname.endsWith('.' + pattern)) return true;
+  }
+  return false;
+}
+
 async function checkRemoteUrl(url) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), LINK_TIMEOUT_MS);
@@ -95,7 +117,7 @@ async function runWithConcurrency(tasks, limit) {
   return results;
 }
 
-async function checkDeadLinks(content, { sourceFile }) {
+async function checkDeadLinks(content, { sourceFile, linkAllowList } = {}) {
   const links = extractLinks(content);
   const findings = [];
   const seen = new Set();
@@ -112,6 +134,7 @@ async function checkDeadLinks(content, { sourceFile }) {
     seen.add(dedupeKey);
 
     if (url.startsWith('http://') || url.startsWith('https://')) {
+      if (isAllowListed(url, linkAllowList)) continue;
       remoteChecks.push({ url, link });
       continue;
     }

package/src/quality.mjs

@@ -7,7 +7,11 @@ function clamp(value, min, max) {
 }
 
 function computeDocHealthScore({ errors = 0, warnings = 0 }) {
-  const raw = 100 - (errors * 25) - (warnings * 8);
+  const errorPenalty = errors * 20;
+  const warningPenalty = warnings > 0
+    ? 5 * Math.sqrt(warnings) + (warnings * 2)
+    : 0;
+  const raw = 100 - errorPenalty - warningPenalty;
   return clamp(Math.round(raw), 0, 100);
 }