Auto: Content & Presence Updates (June-July 2026)

code-fence-lint.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * code-fence-lint.js
+ *
+ * Lint fenced code blocks in Markdown files — the structural mistakes that wreck
+ * how a README renders on GitHub. The classic one: an unclosed fence that turns the
+ * entire rest of your document into a giant grey code block. This is the formatting
+ * companion to the rest of the lint family (link-check.js, heading-lint.js,
+ * frontmatter-lint.js): it tracks fenced blocks the same way they do, then reports
+ * the ones that are broken.
+ *
+ * Checks (each rule can be toggled off):
+ *
+ *   1. unclosed-fence   A code fence that opens but never closes (an odd number of
+ *                       matching fences). On GitHub this swallows everything after it
+ *                       into one code block. ALWAYS an error.
+ *   2. missing-language An opening ``` / ~~~ with no language identifier (```\n vs
+ *                       ```js\n). No syntax highlighting, and many linters/renderers
+ *                       prefer an explicit info string. WARNING by default — promote
+ *                       to an error with --strict-language, silence with
+ *                       --no-require-language.
+ *   3. mismatched-fence A closing fence SHORTER than the one that opened the block,
+ *                       where detectable. A block opened with ```` (4 backticks) is
+ *                       only closed by 4+ backticks; a bare ``` inside it is content,
+ *                       not a close. We flag the case where the block never closes
+ *                       because the only candidate closers were too short. (Reported
+ *                       as part of unclosed-fence with an explanatory message.)
+ *
+ * How fences are matched (CommonMark-aligned, pragmatically):
+ *   - A fence is a line whose first non-space run is 3+ backticks OR 3+ tildes.
+ *   - The opening fence's character (` or ~) and length set the block. A closing
+ *     fence must use the SAME character and be AT LEAST as long, and carry no info
+ *     string. This is what lets a ```` block legitimately contain ``` lines, and a
+ *     ``` block legitimately contain ~~~ lines — they don't close each other.
+ *   - Up to 3 leading spaces of indentation are allowed (CommonMark). This is what
+ *     makes fences inside list items work; deeply-indented ``` inside an indented
+ *     code context is a known limitation (see below).
+ *   - Inline code (single/double backticks within a line, like `x`) is never a
+ *     fence — only a line that STARTS (after ≤3 spaces) with the fence run counts.
+ *
+ * Known limitations (honest, not over-claimed):
+ *   - No full CommonMark block parser. A ``` that is itself inside an *indented*
+ *     (4-space) code block, or inside a blockquote with unusual nesting, may be
+ *     read as a real fence. The common cases — top-level fences and fences inside
+ *     list items — are handled correctly.
+ *   - "Missing language" only inspects the OPENING fence's info string; it can't
+ *     know whether a blank info string was intentional (e.g. plain text output).
+ *     That's exactly why it's a warning, not an error, by default.
+ *
+ * Zero dependencies. Network-free. Works on any Node >= 14.
+ *
+ * Usage:
+ *   node code-fence-lint.js README.md                    # lint one file
+ *   node code-fence-lint.js README.md docs/*.md           # lint several
+ *   node code-fence-lint.js README.md --json              # machine-readable report
+ *   node code-fence-lint.js README.md --strict-language   # missing-language is an error
+ *   node code-fence-lint.js README.md --no-require-language # don't report missing-language
+ *   node code-fence-lint.js --help
+ *
+ * Exit codes (CI / pre-commit friendly):
+ *   0  no problems (warnings alone do not fail the build)
+ *   1  one or more errors found (unclosed/mismatched fences, or missing-language
+ *      under --strict-language)
+ *   2  usage error (no files, missing file, bad flag)
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+function printHelp() {
+  console.log(`code-fence-lint.js — lint fenced code blocks in Markdown
+
+Usage:
+  node code-fence-lint.js <file.md> [more.md ...] [options]
+
+Options:
+  --json                  Emit a JSON report instead of human-readable text.
+  --quiet                 Only print files with problems (nothing on a clean file).
+  --strict-language       Treat a missing language tag as an ERROR (fails the build),
+                          not just a warning.
+  --no-require-language   Don't report fences missing a language tag at all.
+  --help                  Show this help.
+
+Checks: unclosed-fence (error), missing-language (warning by default),
+        mismatched-fence (error, reported via unclosed-fence).
+
+Exit codes:
+  0  clean (warnings alone do not fail)
+  1  error(s) found
+  2  usage error
+
+Examples:
+  node code-fence-lint.js README.md
+  node code-fence-lint.js README.md docs/*.md --json
+  node code-fence-lint.js README.md --strict-language`);
+}
+
+/**
+ * Match a fence line. Returns null if the line is not a fence, otherwise
+ * { char, len, info } where:
+ *   char  '`' or '~'
+ *   len   number of fence characters in the opening run
+ *   info  the info string after the run, trimmed (language tag etc.)
+ *
+ * CommonMark: up to 3 leading spaces; the fence is a run of >= 3 identical
+ * backticks or tildes. A backtick fence's info string may not itself contain a
+ * backtick (that would be inline code, not a fence).
+ */
+function matchFence(line) {
+  const m = line.match(/^( {0,3})(`{3,}|~{3,})(.*)$/);
+  if (!m) return null;
+  const run = m[2];
+  const char = run[0];
+  const info = m[3].trim();
+  // A backtick info string containing a backtick isn't a valid opening fence.
+  if (char === '`' && info.indexOf('`') !== -1) return null;
+  return { char, len: run.length, info };
+}
+
+/**
+ * Walk a Markdown document and report fenced-code-block problems.
+ *
+ * Returns an array of problem objects: { rule, severity, line, message }.
+ *   rule      'unclosed-fence' | 'missing-language'
+ *   severity  'error' | 'warning'
+ *
+ * `opts.requireLanguage` (default true) toggles missing-language reporting.
+ * `opts.strictLanguage` (default false) makes missing-language an error.
+ */
+function lintFences(markdown, opts) {
+  const o = Object.assign({ requireLanguage: true, strictLanguage: false }, opts);
+  const lines = markdown.split('\n');
+  const problems = [];
+
+  // Active fence state: null when outside a code block, otherwise the open fence's
+  // { char, len, info, line }.
+  let open = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const fence = matchFence(lines[i]);
+    if (!fence) continue;
+
+    if (open === null) {
+      // This fence OPENS a block.
+      open = { char: fence.char, len: fence.len, info: fence.info, line: i + 1 };
+
+      if (o.requireLanguage && fence.info === '') {
+        const severity = o.strictLanguage ? 'error' : 'warning';
+        problems.push({
+          rule: 'missing-language',
+          severity,
+          line: i + 1,
+          message: `Code fence opened with no language tag (${fence.char.repeat(fence.len)} with no info string). Add a language (e.g. \`${fence.char.repeat(fence.len)}js\`) for syntax highlighting.`,
+        });
+      }
+      continue;
+    }
+
+    // We're inside a block. A line is a CLOSING fence only if it uses the SAME
+    // character, is AT LEAST as long as the opener, and carries no info string.
+    if (fence.char === open.char && fence.len >= open.len && fence.info === '') {
+      open = null; // block closed cleanly
+      continue;
+    }
+    // Otherwise this fence line is CONTENT of the open block (a shorter same-char
+    // fence, a different-char fence, or a closer with a stray info string). Ignore.
+  }
+
+  // End of file with a block still open: unclosed.
+  if (open !== null) {
+    const opener = `${open.char.repeat(open.len)}${open.info ? ' ' + open.info : ''}`;
+    let message = `Code fence opened at line ${open.line} (${opener.trim()}) is never closed before end of file. On GitHub this turns the rest of the document into one code block.`;
+    if (open.len > 3) {
+      message += ` Note: this block opened with ${open.len} ${open.char === '`' ? 'backticks' : 'tildes'}, so only a fence of ${open.len}+ ${open.char === '`' ? 'backticks' : 'tildes'} closes it — a shorter ${open.char.repeat(3)} inside it counts as content, not a close.`;
+    }
+    problems.push({
+      rule: 'unclosed-fence',
+      severity: 'error',
+      line: open.line,
+      message,
+    });
+  }
+
+  return problems;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    json: false,
+    quiet: false,
+    requireLanguage: true,
+    strictLanguage: false,
+    help: false,
+  };
+  const files = [];
+  for (const arg of argv) {
+    switch (arg) {
+      case '--json': opts.json = true; break;
+      case '--quiet': opts.quiet = true; break;
+      case '--strict-language': opts.strictLanguage = true; opts.requireLanguage = true; break;
+      case '--no-require-language': opts.requireLanguage = false; break;
+      case '--help': case '-h': opts.help = true; break;
+      default:
+        if (arg.startsWith('-')) { opts.badFlag = arg; return { opts, files }; }
+        files.push(arg);
+    }
+  }
+  return { opts, files };
+}
+
+function main() {
+  const { opts, files } = parseArgs(process.argv.slice(2));
+
+  if (opts.help) { printHelp(); process.exit(0); }
+  if (opts.badFlag) { console.error(`Unknown flag: ${opts.badFlag}\n`); printHelp(); process.exit(2); }
+  if (files.length === 0) { console.error('Error: no Markdown files given.\n'); printHelp(); process.exit(2); }
+
+  const report = [];
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let usageError = false;
+
+  for (const file of files) {
+    let markdown;
+    try {
+      markdown = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      console.error(`Error: cannot read ${file} (${e.code || e.message})`);
+      usageError = true;
+      continue;
+    }
+    const problems = lintFences(markdown, opts);
+    const errors = problems.filter((p) => p.severity === 'error').length;
+    const warnings = problems.filter((p) => p.severity === 'warning').length;
+    totalErrors += errors;
+    totalWarnings += warnings;
+    report.push({ file, problems, errors, warnings });
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      ok: totalErrors === 0 && !usageError,
+      usageError,
+      errors: totalErrors,
+      warnings: totalWarnings,
+      files: report,
+    }, null, 2));
+  } else {
+    for (const { file, problems, errors, warnings } of report) {
+      if (problems.length === 0) {
+        if (!opts.quiet) console.log(`✓ ${file} — fenced code blocks OK`);
+        continue;
+      }
+      const counts = [];
+      if (errors) counts.push(`${errors} error(s)`);
+      if (warnings) counts.push(`${warnings} warning(s)`);
+      console.log(`✗ ${file} — ${counts.join(', ')}:`);
+      for (const p of problems) {
+        const tag = p.severity === 'error' ? 'error' : 'warn';
+        console.log(`    [${tag}: ${p.rule}] line ${p.line}: ${p.message}`);
+      }
+    }
+    if (!opts.quiet && totalErrors === 0 && totalWarnings === 0) {
+      console.log('\nAll fenced code blocks check out.');
+    } else if (totalErrors === 0 && totalWarnings > 0) {
+      console.log(`\n${totalWarnings} warning(s), no errors.`);
+    }
+  }
+
+  if (usageError) process.exit(2);
+  process.exit(totalErrors === 0 ? 0 : 1);
+}
+
+if (require.main === module) main();
+
+module.exports = { matchFence, lintFences };