book-kit 0.0.0-stage → 0.6.0

package/validators/smallcaps.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import { GENERATED_FILES, KNOWN_ACRONYMS } from '../lib/validate.js';
+
+/**
+ * Validate that known acronyms use [ACRONYM]{.smallcaps} formatting.
+ * Reports warnings for bare acronyms found outside code blocks and URLs.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateSmallcaps(indexFiles) {
+  const warnings = [];
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+    if (GENERATED_FILES.has(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Track code blocks
+      if (line.trim().startsWith('```')) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+      if (inCodeBlock) continue;
+
+      for (const acr of KNOWN_ACRONYMS) {
+        // Build regex for bare acronym with word boundaries. The trailing `s?`
+        // catches bare *plurals* ("ICs", "Q&As"): `\bIC\b` can't match inside
+        // "ICs" — C and s are both word characters, so there's no boundary
+        // between them — which left an entire class of misses invisible. The
+        // correct form keeps the "s" outside the span ([IC]{.smallcaps}s), so
+        // the leading lookbehind still skips properly-marked-up plurals.
+        const pattern = new RegExp(`(?<!\\[)(?<!\\\\\\[)\\b${acr}s?\\b(?!\\]\\{)(?![^[]*\\{\\.)`, 'g');
+        let m;
+        while ((m = pattern.exec(line)) !== null) {
+          const before = line.slice(0, m.index);
+
+          // Skip if inside inline code (odd number of backticks before)
+          if ((before.match(/`/g) || []).length % 2 === 1) continue;
+
+          // Skip if inside a URL
+          if (/https?:\/\/\S*$/.test(before)) continue;
+
+          // Skip if inside a markdown link URL: [text](http...ACRONYM
+          if (/\]\([^)]*$/.test(before)) continue;
+
+          warnings.push(
+            `Bare acronym "${acr}" without smallcaps in ${file}:${i + 1}`
+          );
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'smallcaps',
+  tags: ['style'],
+  defaults: {},
+  run: (ctx) => validateSmallcaps(ctx.indexFiles),
+};

package/validators/tldr-length.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import { optionsFor } from '../lib/validate.js';
+
+const defaults = {
+  // Bounds on a TL;DR's word count: past max_words it's a paragraph, under
+  // min_words it's a fragment.
+  min_words: 8,
+  max_words: 80,
+};
+
+/**
+ * Validate TL;DR sections are reasonable length (1-3 sentences).
+ * Flags TL;DRs that are too long (likely paragraph-length) or suspiciously short.
+ * @param {string[]} indexFiles - Files listed in index.yml
+ * @param {{min_words?: number, max_words?: number}} [options]
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateTldrLength(indexFiles, options = optionsFor('tldr-length', defaults)) {
+  const warnings = [];
+  const MAX_WORDS = options.max_words;
+  const MIN_WORDS = options.min_words;
+
+  for (const file of indexFiles) {
+    if (!fs.existsSync(file)) continue;
+
+    const content = fs.readFileSync(file, 'utf8');
+
+    // Extract TL;DR content between ::: {.tldr ...} and :::
+    const tldrMatch = content.match(
+      /:::\s*\{\.tldr[^}]*\}\s*\n([\s\S]*?)\n\s*:::/
+    );
+    if (!tldrMatch) continue;
+
+    const tldrText = tldrMatch[1].trim();
+    if (!tldrText) continue;
+
+    const wordCount = tldrText.split(/\s+/).length;
+
+    if (wordCount > MAX_WORDS) {
+      warnings.push(
+        `TL;DR too long (${wordCount} words, max ${MAX_WORDS}) in ${file}`
+      );
+    } else if (wordCount < MIN_WORDS) {
+      warnings.push(
+        `TL;DR too short (${wordCount} words, min ${MIN_WORDS}) in ${file}`
+      );
+    }
+  }
+
+  return { errors: [], warnings };
+}
+
+export default {
+  name: 'tldr-length',
+  tags: ['style'],
+  defaults,
+  run: (ctx) => validateTldrLength(ctx.indexFiles, ctx.options),
+};