create-zudo-doc 5.16.1 → 5.17.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `create-zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.17.0] - 2026-09-04
+
+### Features
+
+- `check-links` now reports protocol-relative hrefs (`//host/path`) as informational notices rather than passing over them silently (`67afa352f`).
+
+### Bug Fixes
+
+- `check-links` no longer treats protocol-relative URLs (`//host/path`) as broken local links (`319169bf3`).
+
+### Other Changes
+
+- Newly generated projects now use the zfb 2.15.0 package family (`d9f5b2f64`). `ts` and `typescript` code fences resolve to the TypeScript grammar and `tsx` to TypeScriptReact, where both previously fell back to JavaScript highlighting.
+
+## [5.16.2] - 2026-09-03
+
+- No package-specific changes.
+
 ## [5.16.1] - 2026-09-02
 
 ### Other Changes

package/dist/scaffold.d.ts

@@ -31,5 +31,5 @@ export declare function deriveDocSkillName(projectName: string): string;
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^5.16.1";
+export declare const ZUDO_DOC_PIN = "^5.17.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -47,7 +47,7 @@ export function deriveDocSkillName(projectName) {
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^5.16.1";
+export const ZUDO_DOC_PIN = "^5.17.0";
 /**
  * Files in `templates/base/**` that must not be copied by the unconditional
  * base mirror. Each entry is matched against the path relative to
@@ -748,9 +748,15 @@ function generatePackageJson(choices, localePlan) {
         // 2.14.3: lockstep release metadata and rebuilt md-wasm artifacts only.
         // Public APIs, exports, config defaults, engine requirements, and shipped
         // wasm byte sizes stay unchanged, so a fresh scaffold needs no migration.
-        "@takazudo/zfb": "2.14.3",
-        "@takazudo/zfb-runtime": "2.14.3",
-        "@takazudo/zfb-md-wasm": "2.14.3",
+        // 2.15.0: `ts`/`typescript` fences now resolve to the TypeScript grammar
+        // and `tsx` to TypeScriptReact, where both previously fell back to
+        // JavaScript. The content-pipeline fingerprint moves to v3, so the first
+        // build after upgrading re-renders cached content under the new grammar
+        // set. Token classes stay on the same semantic-role vocabulary, so themes
+        // need no new rules and a fresh scaffold needs no migration.
+        "@takazudo/zfb": "2.15.0",
+        "@takazudo/zfb-runtime": "2.15.0",
+        "@takazudo/zfb-md-wasm": "2.15.0",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -878,7 +884,7 @@ function generatePackageJson(choices, localePlan) {
         // `/exclude` at module scope from the always-bundled chrome graph; #3110
         // moved compileExclude into @takazudo/zudo-doc, so projects with both
         // docHistory and assetViewer off no longer need the package at all.
-        deps["@takazudo/zudo-doc-history-server"] = "^5.16.1";
+        deps["@takazudo/zudo-doc-history-server"] = "^5.17.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "5.16.1",
+  "version": "5.17.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/scripts/check-links.js

@@ -445,17 +445,39 @@ function decodeHtmlAttributeValue(value) {
   );
 }
 
-export function extractHtmlLinks(html) {
-  const links = [];
+// Single shared anchor scan. `extractHtmlLinks` and
+// `extractProtocolRelativeHtmlLinks` classify the SAME set of `<a href>`
+// matches into disjoint buckets, so the grammar and the incremental line
+// counting live here once — a fix to the anchor regex must never reach only
+// one of the two callers.
+function* iterateHtmlAnchorHrefs(html) {
   const regex = /<a(?=\s)[^>]*?\shref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`\\]+))[^>]*>/gi;
   let match;
   let lastIndex = 0;
   let line = 1;
   while ((match = regex.exec(html)) !== null) {
-    const href = decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]);
-    if (/^(?:https?:|mailto:|javascript:|data:|tel:)/i.test(href)) continue;
     for (let i = lastIndex; i < match.index; i += 1) if (html[i] === "\n") line += 1;
     lastIndex = match.index;
+    yield { href: decodeHtmlAttributeValue(match[1] ?? match[2] ?? match[3]), line };
+  }
+}
+
+export function extractHtmlLinks(html) {
+  const links = [];
+  for (const { href, line } of iterateHtmlAnchorHrefs(html)) {
+    if (/^(?:https?:|\/\/|mailto:|javascript:|data:|tel:)/i.test(href)) continue;
+    links.push({ href, line });
+  }
+  return links;
+}
+
+// Informational counterpart to extractHtmlLinks: same scan, but keeps only the
+// protocol-relative hrefs that extractHtmlLinks classifies as external and
+// skips (see #3921/#3930).
+export function extractProtocolRelativeHtmlLinks(html) {
+  const links = [];
+  for (const { href, line } of iterateHtmlAnchorHrefs(html)) {
+    if (!/^\/\//.test(href)) continue;
     links.push({ href, line });
   }
   return links;
@@ -547,12 +569,12 @@ export function extractMdxFragmentLinks(content) {
     let match;
     const markdownLink = /\]\(\s*([^\s)#]*#[^\s)]*)(?:\s+[^)]*)?\)/g;
     while ((match = markdownLink.exec(searchLine)) !== null) {
-      if (!/^(?:https?:|mailto:|javascript:|data:|tel:)/i.test(match[1])) links.push({ href: match[1], line: i + 1 });
+      if (!/^(?:https?:|\/\/|mailto:|javascript:|data:|tel:)/i.test(match[1])) links.push({ href: match[1], line: i + 1 });
     }
     const jsxHref = /\bhref\s*=\s*(?:"([^"]*#[^"]*)"|'([^']*#[^']*)')/g;
     while ((match = jsxHref.exec(searchLine)) !== null) {
       const href = match[1] ?? match[2];
-      if (!/^(?:https?:|mailto:|javascript:|data:|tel:)/i.test(href)) links.push({ href, line: i + 1 });
+      if (!/^(?:https?:|\/\/|mailto:|javascript:|data:|tel:)/i.test(href)) links.push({ href, line: i + 1 });
     }
   }
   return links;
@@ -731,6 +753,7 @@ export async function checkHtmlLinksAndTrailing(
   const broken = [];
   const anchors = [];
   const trailingSlash = [];
+  const protocolRelative = [];
   const idCache = new Map();
   const cache = new Map();
   const pages = [];
@@ -743,6 +766,13 @@ export async function checkHtmlLinksAndTrailing(
     scanned.ids += ids.length;
     idCache.set(file, new Set(ids));
     pages.push({ file, links });
+
+    // Informational-only: classified from the content already in memory — no
+    // second read of the file.
+    const relFile = relative(rootDir, file);
+    for (const { href, line } of extractProtocolRelativeHtmlLinks(content)) {
+      protocolRelative.push({ file: relFile, line, href });
+    }
   }
   for (const { file, links } of pages) {
     for (const { href, line } of links) {
@@ -777,7 +807,7 @@ export async function checkHtmlLinksAndTrailing(
       }
     }
   }
-  return { broken, anchors, trailingSlash, scanned };
+  return { broken, anchors, trailingSlash, protocolRelative, scanned };
 }
 
 export async function checkMdxLinks(
@@ -802,7 +832,21 @@ export async function checkMdxLinks(
   return warnings;
 }
 
-export function formatReport(brokenLinks, mdxWarnings, trailingSlashWarnings = [], anchorWarnings = []) {
+// The authority segment is everything after "//" up to the first "/", "?",
+// or "#". A dotless, colonless authority (no TLD-shaped or host:port-shaped
+// piece) is flagged as a likely internal-path typo — see formatReport below.
+function protocolRelativeAuthority(href) {
+  const rest = href.slice(2);
+  const end = rest.search(/[/?#]/);
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+function isLikelyInternalPathTypo(href) {
+  const authority = protocolRelativeAuthority(href);
+  return !authority.includes(".") && !authority.includes(":");
+}
+
+export function formatReport(brokenLinks, mdxWarnings, trailingSlashWarnings = [], anchorWarnings = [], protocolRelative = []) {
   const lines = [];
   const section = (title, entries, format) => {
     if (entries.length === 0) return;
@@ -814,6 +858,11 @@ export function formatReport(brokenLinks, mdxWarnings, trailingSlashWarnings = [
   section("=== Absolute Links Bypassing Base Path (MDX Source) ===", mdxWarnings, (e) => `${e.file}:${e.line}  ${e.href}`);
   section("=== Links Missing Trailing Slash ===", trailingSlashWarnings, (e) => `${e.file}:${e.line}  ${e.href}`);
   section("=== Invalid Anchors ===", anchorWarnings, (e) => `${e.file}:${e.line}  ${e.href}  (fragment: #${e.fragment}; ${e.reason})`);
+  // Informational only — excluded from `total` / the ✓/✗ line / the
+  // non-strict "Issues found" note below, deliberately (see #3934).
+  section("=== Protocol-Relative Links (informational) ===", protocolRelative, (e) =>
+    `${e.file}:${e.line}  ${e.href}${isLikelyInternalPathTypo(e.href) ? `  ← authority has no dot or colon; may be an internal-path typo (e.g. ${e.href} → ${e.href.slice(1)})` : ""}`,
+  );
   const total = brokenLinks.length + mdxWarnings.length + trailingSlashWarnings.length + anchorWarnings.length;
   if (total === 0) lines.push("✓ No broken links, invalid anchors, or absolute path issues found");
   else {
@@ -852,8 +901,8 @@ async function main() {
   console.log(`Checking links (base: ${config.basePath}, trailingSlash: ${config.trailingSlash})...`);
   console.log(`Source scan: ${contentDirs.map((dir) => relative(rootDir, dir) || ".").join(", ")}${hasDist ? "; dist/ pass enabled" : "; dist/ absent (source-only)"}\n`);
 
-  const [{ broken, anchors: htmlAnchors, trailingSlash, scanned }, mdxWarnings, mdxAnchors] = await Promise.all([
-    hasDist ? checkHtmlLinksAndTrailing(distDir, rootDir, config.basePath, excludePatterns, config.trailingSlash) : Promise.resolve({ broken: [], anchors: [], trailingSlash: [], scanned: { links: 0, ids: 0 } }),
+  const [{ broken, anchors: htmlAnchors, trailingSlash, protocolRelative, scanned }, mdxWarnings, mdxAnchors] = await Promise.all([
+    hasDist ? checkHtmlLinksAndTrailing(distDir, rootDir, config.basePath, excludePatterns, config.trailingSlash) : Promise.resolve({ broken: [], anchors: [], trailingSlash: [], protocolRelative: [], scanned: { links: 0, ids: 0 } }),
     checkMdxLinks(contentDirs, rootDir, hasDist ? distDir : null, config.basePath, config.localeKeys),
     checkMdxAnchors(contentDirs, rootDir, config.basePath, config.localeKeys, excludePatterns),
   ]);
@@ -865,8 +914,9 @@ async function main() {
   const realAbsolute = filter(mdxWarnings);
   const realAnchors = filter(anchorWarnings);
   const realTrailing = filter(trailingSlash);
-  console.log(formatReport(broken, mdxWarnings, trailingSlash, anchorWarnings));
+  console.log(formatReport(broken, mdxWarnings, trailingSlash, anchorWarnings, protocolRelative));
   if (hasDist) console.log(`\nBuilt HTML scan: ${scanned.links} internal link${scanned.links === 1 ? "" : "s"} and ${scanned.ids} ID attribute${scanned.ids === 1 ? "" : "s"} inspected.`);
+  if (protocolRelative.length > 0) console.log(`Protocol-relative links: ${protocolRelative.length} found (informational only — see "Protocol-Relative Links" section above; not counted as issues).`);
   const skipped = broken.length - realBroken.length + mdxWarnings.length - realAbsolute.length + anchorWarnings.length - realAnchors.length + trailingSlash.length - realTrailing.length;
   if (skipped > 0) console.log(`\nAllowlist: ${skipped} known exception${skipped === 1 ? "" : "s"} excluded from strict-mode counts (${allowlistPath}).`);
   let failed = false;