jamdesk 1.1.127 → 1.1.129

package/vendored/scripts/validate-links.cjs

@@ -20,6 +20,11 @@
 
 const fs = require('fs');
 const path = require('path');
+// Byte-for-byte copy of github-slugger@2's removal regex (ESM->CJS). Generated
+// by scripts/gen-github-slugger-regex.cjs; this is the SAME regex rehype-slug
+// uses to assign real heading ids, so #fragment validation matches the true
+// DOM anchors. Drift-guarded by validate-links-slug.test.ts.
+const { regex: GITHUB_SLUGGER_REGEX } = require('./github-slugger-regex.cjs');
 
 // Parse command line arguments
 const args = process.argv.slice(2);
@@ -208,23 +213,125 @@ function isInCodeBlock(lineNumber, ranges) {
 }
 
 /**
- * Generate URL-friendly slug. Must match generateSlug in heading-extractor.ts.
+ * Stateless slug — exact port of github-slugger@2's `slug()`:
+ * lowercase, remove the chars matched by GITHUB_SLUGGER_REGEX, then turn each
+ * remaining space into a hyphen. NO trimming or dash-collapsing (matches the lib).
+ * This is what rehype-slug assigns as the real heading `id`, so the validator
+ * checks #fragments against the true DOM ids.
+ */
+function githubSlug(value) {
+  if (typeof value !== 'string') return '';
+  return value.toLowerCase().replace(GITHUB_SLUGGER_REGEX, '').replace(/ /g, '-');
+}
+
+/**
+ * Generate URL-friendly slug. Must match generateSlug in heading-extractor.ts
+ * (both delegate to github-slugger).
  */
 function generateSlug(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+  return githubSlug(text);
+}
+
+/**
+ * Build a stateful slugger that mirrors github-slugger@2's class: repeated
+ * values get `-1`, `-2`, ... suffixes in call order — exactly how rehype-slug
+ * de-duplicates real heading ids within a page. One slugger per page.
+ */
+function createSlugger() {
+  const occurrences = Object.create(null);
+  return function slug(value) {
+    let result = githubSlug(value);
+    const originalSlug = result;
+    while (Object.prototype.hasOwnProperty.call(occurrences, result)) {
+      occurrences[originalSlug]++;
+      result = originalSlug + '-' + occurrences[originalSlug];
+    }
+    occurrences[result] = 0;
+    return result;
+  };
+}
+
+/**
+ * Levenshtein edit distance (iterative two-row DP). Inlined rather than pulling
+ * a dependency: validate-links.cjs is vendored into the CLI as a self-contained
+ * script (only ./github-slugger-regex.cjs ships alongside it), so it must not
+ * add runtime requires.
+ */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array(b.length + 1);
+  let curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 0; i < a.length; i++) {
+    curr[0] = i + 1;
+    for (let j = 0; j < b.length; j++) {
+      const cost = a[i] === b[j] ? 0 : 1;
+      curr[j + 1] = Math.min(curr[j] + 1, prev[j + 1] + 1, prev[j] + cost);
+    }
+    const tmp = prev;
+    prev = curr;
+    curr = tmp;
+  }
+  return prev[b.length];
+}
+
+/**
+ * Maximum edit distance for a "Did you mean #X?" suggestion. Deliberately small
+ * (precision over recall): the dominant real cases — apostrophe slips
+ * (reset-a-user-s-password → reset-a-users-password) and accent slips
+ * (pagina → página) — are distance 1. A larger cap starts suggesting
+ * real-but-wrong anchors, which is worse than no suggestion.
+ */
+const MAX_SUGGESTION_DISTANCE = 2;
+
+/**
+ * Find the closest valid heading slug to a fragment that wasn't found, for a
+ * "Did you mean #X?" hint. Precision over recall — only returns a slug for an
+ * UNAMBIGUOUS near-miss: within MAX_SUGGESTION_DISTANCE AND strictly closer than
+ * every other candidate. So apostrophe/accent/typo slips get a suggestion, but a
+ * fragment equidistant from several similar headings (step-1/step-2/…,
+ * setup/setup-1, changelog versions) yields NO suggestion rather than an
+ * arbitrary, confidently-wrong one. Returns null when nothing qualifies.
+ */
+function closestSlug(fragment, slugSet) {
+  if (!fragment || !slugSet || slugSet.size === 0) return null;
+  let best = null;
+  let bestDist = Infinity;
+  let secondDist = Infinity;
+  for (const slug of slugSet) {
+    // Edit distance can't be below the length gap; skip candidates that can't
+    // beat the cap. Also bounds the Levenshtein work on very large pages, and
+    // can't hide a true tie (a distance ≤2 tie implies a length gap ≤2).
+    if (Math.abs(fragment.length - slug.length) > MAX_SUGGESTION_DISTANCE) continue;
+    const d = levenshtein(fragment, slug);
+    if (d < bestDist) {
+      secondDist = bestDist;
+      bestDist = d;
+      best = slug;
+    } else if (d < secondDist) {
+      secondDist = d;
+    }
+  }
+  // Unambiguous near-miss: within the cap, not an exact match (≥1), and strictly
+  // closer than the runner-up (ties → no suggestion).
+  return best !== null &&
+    bestDist >= 1 &&
+    bestDist <= MAX_SUGGESTION_DISTANCE &&
+    bestDist < secondDist
+    ? best
+    : null;
 }
 
 /**
- * Mirrors uniquifySlug in lib/heading-extractor.ts. First occurrence keeps the
- * bare slug; later collisions get -2, -3, ... suffixes in source order.
+ * Build the "Fragment #X not found in headings" warning message, appending a
+ * "Did you mean #Y?" hint when closestSlug found an unambiguous near-miss.
+ * Shared by both fragment-not-found sites in validateFile().
  */
-function uniquifySlug(seen, base) {
-  const count = seen.get(base) || 0;
-  seen.set(base, count + 1);
-  return count === 0 ? base : `${base}-${count + 1}`;
+function fragmentNotFoundMessage(fragment, suggestion) {
+  return 'Fragment #' + fragment + ' not found in headings' +
+    (suggestion ? '. Did you mean #' + suggestion + '?' : '');
 }
 
 /**
@@ -239,7 +346,7 @@ function uniquifySlug(seen, base) {
  */
 function extractHeadingSlugs(content) {
   const slugs = new Set();
-  const seen = new Map();
+  const slugger = createSlugger();
   const lines = content.split('\n');
   let inCodeBlock = false;
   let fencePattern = '';
@@ -275,20 +382,20 @@ function extractHeadingSlugs(content) {
 
     const headingMatch = line.match(/^#{1,6}\s+(.+)$/);
     if (headingMatch) {
-      const base = generateSlug(headingMatch[1].trim());
-      if (base) slugs.add(uniquifySlug(seen, base));
+      const text = headingMatch[1].trim();
+      if (generateSlug(text)) slugs.add(slugger(text));
     }
 
     const updateMatch = line.match(/<Update\s+label=["']([^"']+)["']/);
     if (updateMatch) {
-      const base = generateSlug(updateMatch[1]);
-      if (base) slugs.add(uniquifySlug(seen, base));
+      const text = updateMatch[1];
+      if (generateSlug(text)) slugs.add(slugger(text));
     }
 
     if (inStepsBlock) {
       for (const match of line.matchAll(STEP_TITLE_REGEX)) {
-        const base = generateSlug(match[1] ?? match[2]);
-        if (base) slugs.add(uniquifySlug(seen, base));
+        const text = match[1] ?? match[2];
+        if (generateSlug(text)) slugs.add(slugger(text));
       }
     }
 
@@ -387,12 +494,13 @@ function validateFile(filePath, contentDir, results, headingMap) {
       if (!linkPath && fragment) {
         const currentSlugs = headingMap.get(currentPagePath);
         if (currentSlugs && !currentSlugs.has(fragment)) {
+          const suggestion = closestSlug(fragment, currentSlugs);
           results.push({
             type: 'broken_link',
             file: relativePath,
             line: lineNumber,
             link: rawHref,
-            message: 'Fragment #' + fragment + ' not found in headings',
+            message: fragmentNotFoundMessage(fragment, suggestion),
           });
         }
         continue;
@@ -421,12 +529,13 @@ function validateFile(filePath, contentDir, results, headingMap) {
       if (fragment) {
         const targetSlugs = getTargetHeadingSlugs(targetPath, contentDir, headingMap);
         if (targetSlugs && !targetSlugs.has(fragment)) {
+          const suggestion = closestSlug(fragment, targetSlugs);
           results.push({
             type: 'broken_link',
             file: relativePath,
             line: lineNumber,
             link: rawHref,
-            message: 'Fragment #' + fragment + ' not found in headings',
+            message: fragmentNotFoundMessage(fragment, suggestion),
           });
         }
       }
@@ -552,7 +661,10 @@ if (require.main === module) {
       const location = w.line ? `${w.file}:${w.line}` : w.file;
       console.log(`  ${location}`);
       if (w.message) {
-        console.log(`    ${w.message}: ${w.link}`);
+        // message is a full sentence (may end in "…?"); keep the link on its
+        // own line so the output reads cleanly rather than "…mean #y?: #x".
+        console.log(`    ${w.message}`);
+        console.log(`    Link: ${w.link}`);
       } else {
         console.log(`    Missing page: ${w.link}`);
       }
@@ -566,4 +678,6 @@ if (require.main === module) {
 }
 
 // Export for programmatic use
-module.exports = { validateProject };
+// generateSlug + createSlugger are exported for the drift test
+// (validate-links-slug.test.ts), which asserts they match the live github-slugger.
+module.exports = { validateProject, generateSlug, createSlugger, closestSlug, levenshtein };

package/vendored/themes/jam/variables.css

@@ -247,6 +247,14 @@ html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]):not([data-d
   background-color: transparent !important;
 }
 
+/* Embed render (widget modal): the LayoutWrapper embed branch wraps content in
+   a solid-bg div (for decoration:"none"/dark/non-jam readability). In gradient
+   mode, make that wrapper transparent so the body decoration shows through —
+   same as the chrome wrappers above. */
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]):not([data-decoration="grid"]) [data-embed="true"] {
+  background-color: transparent !important;
+}
+
 html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]):not([data-decoration="grid"]) header {
   background-color: transparent !important;
   background: transparent !important;