doclify-guardrail 1.2.0 → 1.2.1

package/package.json

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

package/src/checker.mjs

@@ -32,10 +32,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,6 +86,89 @@ 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*-->/;
+
+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;
@@ -97,8 +180,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 +200,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 +225,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',
@@ -249,18 +349,22 @@ 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
+  const filteredErrors = errors.filter(f => !isSuppressed(suppressions, f));
+  const filteredWarnings = warnings.filter(f => !isSuppressed(suppressions, 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/fixer.mjs

@@ -23,7 +23,7 @@ function autoFixInsecureLinks(content) {
 
     const replaced = raw.replace('http://', 'https://');
     if (replaced !== raw) {
-      changes.push({ from: raw, to: replaced });
+      changes.push({ from: cleaned, to: cleaned.replace('http://', 'https://') });
     }
     return replaced;
   });

package/src/index.mjs

@@ -47,6 +47,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)')}
@@ -106,6 +108,7 @@ function parseArgs(argv) {
     maxLineLength: undefined,
     configPath: path.resolve('.doclify-guardrail.json'),
     help: false,
+    version: false,
     listRules: false,
     init: false,
     dir: null,
@@ -120,6 +123,8 @@ function parseArgs(argv) {
     exclude: [],
     checkLinks: false,
     checkFreshness: false,
+    checkFrontmatter: false,
+    linkAllowList: [],
     fix: false,
     dryRun: false,
     json: false
@@ -133,6 +138,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '-v' || a === '--version') {
+      args.version = true;
+      continue;
+    }
+
     if (a === '--list-rules') {
       args.listRules = true;
       continue;
@@ -183,6 +193,21 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (a === '--check-frontmatter') {
+      args.checkFrontmatter = 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;
@@ -326,10 +351,16 @@ 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];
+
   return {
     maxLineLength,
     strict,
     ignoreRules,
+    checkFrontmatter,
+    linkAllowList,
     configPath: args.configPath,
     configLoaded: fs.existsSync(args.configPath)
   };
@@ -385,6 +416,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,6 +443,11 @@ async function runCli(argv = process.argv.slice(2)) {
     return 0;
   }
 
+  if (args.version) {
+    console.log(VERSION);
+    return 0;
+  }
+
   if (args.listRules) {
     initColors(args.noColor);
     console.log('');
@@ -439,7 +476,9 @@ async function runCli(argv = process.argv.slice(2)) {
       maxLineLength: 160,
       ignoreRules: [],
       checkLinks: false,
-      checkFreshness: false
+      checkFreshness: false,
+      checkFrontmatter: false,
+      linkAllowList: []
     };
 
     fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
@@ -470,7 +509,8 @@ async function runCli(argv = process.argv.slice(2)) {
           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);
       });
     });
   }
@@ -561,12 +601,13 @@ async function runCli(argv = process.argv.slice(2)) {
       const analysis = checkMarkdown(content, {
         maxLineLength: resolved.maxLineLength,
         filePath: relPath,
-        customRules
+        customRules,
+        checkFrontmatter: resolved.checkFrontmatter
       });
 
       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;

package/src/links.mjs

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