doclify-guardrail 1.2.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doclify-guardrail",
-  "version": "1.2.1",
+  "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]));
@@ -89,6 +104,7 @@ function stripInlineCode(line) {
 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();
@@ -172,6 +188,19 @@ function isSuppressed(suppressions, finding) {
 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 = [];
 
@@ -341,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) => {
@@ -355,9 +561,11 @@ function checkMarkdown(rawContent, opts = {}) {
     });
   }
 
-  // Apply inline suppressions
-  const filteredErrors = errors.filter(f => !isSuppressed(suppressions, f));
-  const filteredWarnings = warnings.filter(f => !isSuppressed(suppressions, f));
+  // 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: filteredErrors,

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: cleaned, to: cleaned.replace('http://', 'https://') });
+  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;
 
@@ -64,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
 
@@ -124,10 +139,13 @@ function parseArgs(argv) {
     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) {
@@ -198,6 +216,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '--check-inline-html') {
+      args.checkInlineHtml = true;
+      continue;
+    }
+
     if (a === '--link-allow-list') {
       const value = argv[i + 1];
       if (!value || value.startsWith('-')) {
@@ -223,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('-')) {
@@ -354,6 +387,8 @@ function resolveOptions(args) {
   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,
@@ -361,6 +396,7 @@ function resolveOptions(args) {
     ignoreRules,
     checkFrontmatter,
     linkAllowList,
+    exclude,
     configPath: args.configPath,
     configLoaded: fs.existsSync(args.configPath)
   };
@@ -450,6 +486,7 @@ async function runCli(argv = process.argv.slice(2)) {
 
   if (args.listRules) {
     initColors(args.noColor);
+    setAsciiMode(args.ascii);
     console.log('');
     console.log(`  ${c.bold('Built-in rules')}`);
     console.log('');
@@ -463,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;
     }
 
@@ -475,6 +514,7 @@ async function runCli(argv = process.argv.slice(2)) {
       strict: false,
       maxLineLength: 160,
       ignoreRules: [],
+      exclude: [],
       checkLinks: false,
       checkFreshness: false,
       checkFrontmatter: false,
@@ -483,7 +523,7 @@ async function runCli(argv = process.argv.slice(2)) {
 
     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 .')}`);
@@ -492,6 +532,7 @@ async function runCli(argv = process.argv.slice(2)) {
   }
 
   initColors(args.noColor);
+  setAsciiMode(args.ascii);
 
   let filePaths;
   try {
@@ -501,10 +542,18 @@ 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);
@@ -520,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 {
@@ -541,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();
@@ -557,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('');
@@ -565,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) {
@@ -582,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({
@@ -595,6 +646,21 @@ 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);
@@ -602,7 +668,8 @@ async function runCli(argv = process.argv.slice(2)) {
         maxLineLength: resolved.maxLineLength,
         filePath: relPath,
         customRules,
-        checkFrontmatter: resolved.checkFrontmatter
+        checkFrontmatter: resolved.checkFrontmatter,
+        checkInlineHtml: Boolean(args.checkInlineHtml)
       });
 
       if (args.checkLinks) {
@@ -638,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;
@@ -662,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;
@@ -672,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;
@@ -682,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, '')
   }));
 }
 

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);
 }