@takazudo/zudo-doc 5.22.1 → 5.24.0

package/dist/home-page/index.js

@@ -3,7 +3,7 @@ import { Fragment as Fragment2 } from "preact";
 import { Island } from "@takazudo/zfb";
 import { AutoLogo } from "../auto-logo/index.js";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
-import { CompactProse, resolveHomeIntro } from "../home-intro/index.js";
+import { CompactProse, HOME_SECTION_HEADING_CLASS, resolveHomeIntro } from "../home-intro/index.js";
 import { SiteTreeNav } from "../site-tree-nav-island/index.js";
 import { TagNav } from "../nav-indexing/tag-nav.js";
 import { CategoryLinkIcon } from "../tree-nav-shared/index.js";
@@ -14,7 +14,7 @@ import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 import { prepareHomeData } from "./prepare-home-data.js";
 function HomeSectionHeading({ children }) {
-  return /* @__PURE__ */ jsx("h2", { class: "text-title font-bold mb-vsp-md", children });
+  return /* @__PURE__ */ jsx("h2", { class: `${HOME_SECTION_HEADING_CLASS} mb-vsp-md`, children });
 }
 function cssUrl(url) {
   return `url("${url.replace(/[\\"]/g, "\\$&")}")`;
@@ -161,47 +161,50 @@ function createHomePageView(ctx) {
               )
             })
           ] }),
-          settings.docTags && tagCount > 0 && /* @__PURE__ */ jsx("section", { class: "mt-vsp-xl", children: tags && tags.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.tags", locale) }),
-            /* @__PURE__ */ jsx(
-              TagNav,
-              {
-                variant: "all",
-                tags: tags.slice(0, tagLimit),
-                labels: {
-                  tags: t("doc.tags", locale),
-                  taggedWith: t("doc.taggedWith", locale)
-                }
-              }
-            ),
-            tags.length > tagLimit && /* @__PURE__ */ jsx("div", { class: "mt-vsp-sm text-title text-muted", "aria-hidden": "true", children: "\u2026" }),
-            /* @__PURE__ */ jsx("div", { class: "mt-vsp-md", children: /* @__PURE__ */ jsxs(
-              "a",
-              {
-                href: withBase(`${prefix}/docs/tags`),
-                class: "group inline-flex items-center gap-hsp-xs text-accent hover:underline",
-                children: [
-                  /* @__PURE__ */ jsx(CategoryLinkIcon, { className: "w-icon-sm text-accent" }),
-                  /* @__PURE__ */ jsx("span", { children: t("doc.seeAllTags", locale) })
-                ]
-              }
-            ) })
-          ] }) : (
-            // Legacy fallback: caller passed only `tagCount` (no tag list) —
-            // reproduce the pre-#3027 single "All Tags" link so existing
-            // `@takazudo/zudo-doc/home-page` consumers are unaffected.
-            /* @__PURE__ */ jsxs(Fragment, { children: [
-              /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.allTags", locale) }),
+          settings.docTags && tagCount > 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx("hr", { class: "zd-home-rule", "data-home-rule": "tags" }),
+            /* @__PURE__ */ jsx("section", { class: "zd-home-tags", children: tags && tags.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.tags", locale) }),
               /* @__PURE__ */ jsx(
+                TagNav,
+                {
+                  variant: "all",
+                  tags: tags.slice(0, tagLimit),
+                  labels: {
+                    tags: t("doc.tags", locale),
+                    taggedWith: t("doc.taggedWith", locale)
+                  }
+                }
+              ),
+              tags.length > tagLimit && /* @__PURE__ */ jsx("div", { class: "mt-vsp-sm text-title text-muted", "aria-hidden": "true", children: "\u2026" }),
+              /* @__PURE__ */ jsx("div", { class: "mt-vsp-md", children: /* @__PURE__ */ jsxs(
                 "a",
                 {
                   href: withBase(`${prefix}/docs/tags`),
-                  class: "text-accent underline hover:text-accent-hover",
-                  children: t("doc.allTags", locale)
+                  class: "group inline-flex items-center gap-hsp-xs text-accent hover:underline",
+                  children: [
+                    /* @__PURE__ */ jsx(CategoryLinkIcon, { className: "w-icon-sm text-accent" }),
+                    /* @__PURE__ */ jsx("span", { children: t("doc.seeAllTags", locale) })
+                  ]
                 }
-              )
-            ] })
-          ) })
+              ) })
+            ] }) : (
+              // Legacy fallback: caller passed only `tagCount` (no tag list) —
+              // reproduce the pre-#3027 single "All Tags" link so existing
+              // `@takazudo/zudo-doc/home-page` consumers are unaffected.
+              /* @__PURE__ */ jsxs(Fragment, { children: [
+                /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.allTags", locale) }),
+                /* @__PURE__ */ jsx(
+                  "a",
+                  {
+                    href: withBase(`${prefix}/docs/tags`),
+                    class: "text-accent underline hover:text-accent-hover",
+                    children: t("doc.allTags", locale)
+                  }
+                )
+              ] })
+            ) })
+          ] })
         ]
       }
     );

package/dist/plugins/internal/claude-resources/generate.js

@@ -6,9 +6,8 @@ import {
   downgradeRepoRelativeLinks,
   ensureDir,
   escapeForMdx,
-  escapeTitle,
-  findNamedFiles,
   formatFrontmatterString,
+  findNamedFiles,
   generateSkillsCategory,
   parseFrontmatter,
   removeGeneratedIndex,
@@ -36,10 +35,6 @@ function defaultResourceLabel(config, key, fallbackLiteral) {
     fallbackLiteral
   );
 }
-function formatClaudeFrontmatterString(value) {
-  const formatted = formatFrontmatterString(value);
-  return formatted === value ? JSON.stringify(value) : formatted;
-}
 function generateClaudemdDocs(config) {
   const projectRoot = config.projectRoot ?? config.claudeDir;
   const scanRoot = config.scanRoot ?? projectRoot;
@@ -81,10 +76,10 @@ function generateClaudemdDocs(config) {
     emittedSlugs.set(item.slug, item.relPath);
     const content = fs.readFileSync(item.absPath, "utf8");
     const mdx = `---
-title: "${escapeTitle(item.displayPath)}"
-description: "CLAUDE.md at ${escapeTitle(item.displayPath)}"
+title: ${formatFrontmatterString(item.displayPath)}
+description: ${formatFrontmatterString(`CLAUDE.md at ${item.displayPath}`)}
 sidebar_position: ${index + 1}
-sidebar_label: "${escapeTitle(item.relPath)}"
+sidebar_label: ${formatFrontmatterString(item.relPath)}
 generated: true
 ---
 
@@ -102,7 +97,8 @@ ${escapeForMdx(downgradeRepoRelativeLinks(content.trim()))}
       config,
       "resource.claudeMd.description",
       "Project-specific instructions"
-    )
+    ),
+    formatFrontmatterString
   );
   return items;
 }
@@ -127,9 +123,9 @@ function generateCommandsDocs(config) {
     const description = parsed.data.description || "";
     items.push({ name, description });
     const mdx = `---
-title: "${escapeTitle(name)}"
-description: "${escapeTitle(description)}"
-sidebar_label: "${escapeTitle(name)}"
+title: ${formatFrontmatterString(name)}
+description: ${formatFrontmatterString(description)}
+sidebar_label: ${formatFrontmatterString(name)}
 generated: true
 ---
 
@@ -146,7 +142,8 @@ ${escapeForMdx(downgradeRepoRelativeLinks(parsed.content.trim()))}
       config,
       "resource.claudeCommands.description",
       "Custom slash commands"
-    )
+    ),
+    formatFrontmatterString
   );
   return items;
 }
@@ -161,7 +158,8 @@ function generateSkillsDocs(config) {
       "resource.claudeSkills.description",
       "Skill packages"
     ),
-    sourceLabel: ".claude/skills"
+    sourceLabel: ".claude/skills",
+    renderFrontmatterString: formatFrontmatterString
   });
 }
 function generateAgentsDocs(config) {
@@ -189,9 +187,9 @@ function generateAgentsDocs(config) {
     const modelBadge = model ? `**Model:** \`${model}\`
 ` : "";
     const mdx = `---
-title: "${escapeTitle(name)}"
-description: "${escapeTitle(description)}"
-sidebar_label: "${escapeTitle(name)}"
+title: ${formatFrontmatterString(name)}
+description: ${formatFrontmatterString(description)}
+sidebar_label: ${formatFrontmatterString(name)}
 generated: true
 ---
 
@@ -209,7 +207,8 @@ ${escapeForMdx(downgradeRepoRelativeLinks(parsed.content.trim()))}
       config,
       "resource.claudeAgents.description",
       "Custom subagents"
-    )
+    ),
+    formatFrontmatterString
   );
   return items;
 }
@@ -259,8 +258,8 @@ function generateOverviewIndex(config, {
 }
 function renderOverviewIndex(config, locale, categorySlugs) {
   return `---
-title: ${formatClaudeFrontmatterString(resourceLabel(config, locale, "resource.claude.title", "Claude"))}
-description: ${formatClaudeFrontmatterString(resourceLabel(
+title: ${formatFrontmatterString(resourceLabel(config, locale, "resource.claude.title", "Claude"))}
+description: ${formatFrontmatterString(resourceLabel(
     config,
     locale,
     "resource.claude.description",
@@ -341,7 +340,7 @@ function writeLocaleCategoryIndex(config, locale, localeDir, categoryDir, presen
     resourceLabel(config, locale, labelKey, fallbackLabel),
     position,
     resourceLabel(config, locale, descriptionKey, fallbackDescription),
-    formatClaudeFrontmatterString,
+    formatFrontmatterString,
     (absolutePath, content) => writeGeneratedIndex(absolutePath, content, `/docs/${categoryDir}/`)
   );
 }

package/dist/plugins/internal/img-src-check/index.d.ts

@@ -8,8 +8,10 @@ export interface ImgSrcCheckLogger {
 export interface BrokenImgSrc {
     /** HTML page path relative to the build output directory. */
     pagePath: string;
-    /** The decoded attribute value as authored in the rendered HTML. */
+    /** The individual URL value as authored in the rendered HTML. */
     src: string;
+    /** The element and attribute that supplied `src` (for example `img[src]`). */
+    element?: string;
     /** Why the reference was considered broken. */
     reason: string;
 }
@@ -17,7 +19,7 @@ export interface BrokenImgSrc {
 export interface ImgSrcCheckResult {
     /** Number of HTML files visited under `outDir`. */
     htmlFileCount: number;
-    /** Number of site-absolute `src` attributes inspected. */
+    /** Number of local media/asset references inspected. */
     imageCount: number;
     /** Every broken occurrence, including duplicate references. */
     broken: BrokenImgSrc[];
@@ -46,7 +48,7 @@ export declare function extractImgSrcs(html: string): string[];
 /** Normalize a zfb base to a slash-delimited URL prefix. */
 export declare function normalizeImgSrcBase(base: string | undefined): string;
 /**
- * Walk every built HTML file and validate its site-absolute image sources.
+ * Walk every built HTML file and validate its local media/asset references.
  *
  * This is intentionally synchronous: zfb's postBuild hook is async-compatible
  * but the operation is a deterministic local filesystem walk, and a sync

package/dist/plugins/internal/img-src-check/index.js

@@ -2,7 +2,9 @@ import { realpathSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { parse } from "parse5";
 const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
 const SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/u;
+const SCANNER_ORIGIN = "https://zudo-doc-img-src-check.invalid";
 function extractImgSrcs(html) {
   const document = parse(html);
   const srcs = [];
@@ -32,27 +34,241 @@ function isWithin(root, candidate) {
   const rel = relative(root, candidate);
   return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep);
 }
-function stripQueryAndFragment(src) {
-  const query = src.indexOf("?");
-  const fragment = src.indexOf("#");
-  const end = [query, fragment].filter((index) => index >= 0).sort((a, b) => a - b)[0];
-  return end === void 0 ? src : src.slice(0, end);
+function attributeValue(element, name) {
+  return element.attrs.find((attribute) => {
+    const qualifiedName = attribute.prefix ? `${attribute.prefix}:${attribute.name}` : attribute.name;
+    return qualifiedName.toLowerCase() === name;
+  })?.value;
 }
-function resolveImgSrc(src, outDir, base, canonicalOutDir) {
+function addAssetReference(references, element, attribute, value) {
+  if (value !== void 0) references.push({ src: value, element: `${element}[${attribute}]` });
+}
+function isHtmlElement(element, tagName) {
+  return element.namespaceURI === HTML_NAMESPACE && element.tagName.toLowerCase() === tagName;
+}
+function isSvgElement(element, tagName) {
+  return element.namespaceURI === SVG_NAMESPACE && element.tagName.toLowerCase() === tagName;
+}
+function parseSrcsetCandidates(value) {
+  const candidates = [];
+  let position = 0;
+  const isAsciiWhitespace = (character) => character === " " || character === "	" || character === "\n" || character === "\f" || character === "\r";
+  const skipSplittingWhitespaceAndCommas = () => {
+    while (position < value.length) {
+      const character = value[position];
+      if (!isAsciiWhitespace(character) && character !== ",") break;
+      position += 1;
+    }
+  };
+  const parseDescriptors = (descriptors) => {
+    let width;
+    let density;
+    let futureCompatH = false;
+    for (const descriptor of descriptors) {
+      if (/^\d+w$/u.test(descriptor)) {
+        if (width !== void 0 || density !== void 0) return false;
+        const parsed = Number.parseInt(descriptor.slice(0, -1), 10);
+        if (!Number.isFinite(parsed) || parsed === 0) return false;
+        width = parsed;
+        continue;
+      }
+      if (/^-?(?:\d+(?:\.\d+)?|\.\d+)(?:[Ee][+-]?\d+)?x$/u.test(descriptor)) {
+        if (width !== void 0 || density !== void 0 || futureCompatH) return false;
+        const parsed = Number.parseFloat(descriptor.slice(0, -1));
+        if (!Number.isFinite(parsed) || parsed < 0) return false;
+        density = parsed;
+        continue;
+      }
+      if (/^\d+h$/u.test(descriptor)) {
+        if (futureCompatH || density !== void 0) return false;
+        const parsed = Number.parseInt(descriptor.slice(0, -1), 10);
+        if (!Number.isFinite(parsed) || parsed === 0) return false;
+        futureCompatH = true;
+        continue;
+      }
+      return false;
+    }
+    return !futureCompatH || width !== void 0;
+  };
+  while (position < value.length) {
+    skipSplittingWhitespaceAndCommas();
+    if (position >= value.length) break;
+    const urlStart = position;
+    while (position < value.length && !isAsciiWhitespace(value[position])) position += 1;
+    let url = value.slice(urlStart, position);
+    const hadTrailingComma = url.endsWith(",");
+    if (hadTrailingComma) url = url.replace(/,+$/u, "");
+    if (url.length === 0) {
+      continue;
+    }
+    const descriptors = [];
+    if (!hadTrailingComma) {
+      let current = "";
+      let inParens = false;
+      let descriptorDone = false;
+      while (!descriptorDone) {
+        const character = value[position];
+        if (inParens) {
+          if (character === void 0) {
+            if (current) descriptors.push(current);
+            descriptorDone = true;
+          } else {
+            current += character;
+            position += 1;
+            if (character === ")") inParens = false;
+          }
+          continue;
+        }
+        if (isAsciiWhitespace(character)) {
+          if (current) {
+            descriptors.push(current);
+            current = "";
+          }
+          while (isAsciiWhitespace(value[position])) position += 1;
+          if (value[position] === "," || position >= value.length) {
+            descriptorDone = true;
+          }
+          continue;
+        }
+        if (character === ",") {
+          position += 1;
+          if (current) descriptors.push(current);
+          descriptorDone = true;
+          continue;
+        }
+        if (character === void 0) {
+          if (current) descriptors.push(current);
+          descriptorDone = true;
+          continue;
+        }
+        current += character;
+        position += 1;
+        if (character === "(") inParens = true;
+      }
+    }
+    if (parseDescriptors(descriptors)) candidates.push(url);
+  }
+  return candidates;
+}
+function extractAssetReferences(document) {
+  const references = [];
+  const baseHrefs = [];
+  const visit = (node, insideTemplate) => {
+    if (!("tagName" in node)) return;
+    const element = node;
+    if (!insideTemplate && isHtmlElement(element, "base")) {
+      const href = attributeValue(element, "href");
+      if (href !== void 0) baseHrefs.push(href);
+    }
+    if (isHtmlElement(element, "img")) {
+      addAssetReference(references, "img", "src", attributeValue(element, "src"));
+      const srcset = attributeValue(element, "srcset");
+      if (srcset !== void 0) {
+        for (const candidate of parseSrcsetCandidates(srcset)) {
+          addAssetReference(references, "img", "srcset", candidate);
+        }
+      }
+    } else if (isHtmlElement(element, "source")) {
+      addAssetReference(references, "source", "src", attributeValue(element, "src"));
+      const srcset = attributeValue(element, "srcset");
+      if (srcset !== void 0) {
+        for (const candidate of parseSrcsetCandidates(srcset)) {
+          addAssetReference(references, "source", "srcset", candidate);
+        }
+      }
+    } else if (isHtmlElement(element, "video")) {
+      addAssetReference(references, "video", "src", attributeValue(element, "src"));
+      addAssetReference(references, "video", "poster", attributeValue(element, "poster"));
+    } else if (isHtmlElement(element, "audio")) {
+      addAssetReference(references, "audio", "src", attributeValue(element, "src"));
+    } else if (isHtmlElement(element, "track")) {
+      addAssetReference(references, "track", "src", attributeValue(element, "src"));
+    } else if (isHtmlElement(element, "input")) {
+      const type = attributeValue(element, "type");
+      if (type?.trim().toLowerCase() === "image") {
+        addAssetReference(references, "input", "src", attributeValue(element, "src"));
+      }
+    } else if (isSvgElement(element, "image")) {
+      addAssetReference(references, "image", "href", attributeValue(element, "href"));
+      addAssetReference(references, "image", "xlink:href", attributeValue(element, "xlink:href"));
+    }
+    for (const child of element.childNodes) visit(child, insideTemplate);
+    if (element.nodeName === "template") {
+      const template = element;
+      for (const child of template.content.childNodes) visit(child, true);
+    }
+  };
+  for (const child of document.childNodes) visit(child, false);
+  return { references, baseHrefs };
+}
+function makePageUrl(pagePath, base) {
+  const pageName = /(?:^|\/)index\.html$/iu.test(pagePath) ? pagePath.slice(0, -"index.html".length) : pagePath;
+  const pathname = `${base}${pageName}`;
+  const pageUrl = new URL(SCANNER_ORIGIN);
+  const filePathname = (pathname.startsWith("/") ? pathname : `/${pathname}`).replaceAll(
+    "%",
+    "%25"
+  );
+  pageUrl.pathname = filePathname;
+  return pageUrl;
+}
+function effectiveDocumentBase(pageUrl, hrefs) {
+  for (const href of hrefs) {
+    const value = href.trim();
+    try {
+      return new URL(value, pageUrl);
+    } catch {
+    }
+  }
+  return pageUrl;
+}
+function hasAbsolutePathTraversal(value) {
+  if (!value.startsWith("/") || value.startsWith("//")) return false;
+  const pathPart = value.split(/[?#]/u, 1)[0] ?? value;
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(pathPart);
+  } catch {
+    return false;
+  }
+  const stack = [];
+  for (const segment of decodedPath.replaceAll("\\", "/").split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (stack.length === 0) return true;
+      stack.pop();
+    } else {
+      stack.push(segment);
+    }
+  }
+  return false;
+}
+function resolveImgSrc(src, outDir, base, canonicalOutDir, documentBase) {
   const value = src.trim();
-  if (!value.startsWith("/") || value.startsWith("//") || SCHEME_RE.test(value)) {
+  if (!value || value.startsWith("#") || value.startsWith("//") || SCHEME_RE.test(value)) {
     return { kind: "skip" };
   }
-  const pathPart = stripQueryAndFragment(value);
+  if (documentBase.origin !== SCANNER_ORIGIN) return { kind: "skip" };
+  let resolvedUrl;
+  try {
+    resolvedUrl = new URL(value, documentBase);
+  } catch {
+    return { kind: "broken", reason: "invalid URL" };
+  }
+  if (resolvedUrl.origin !== SCANNER_ORIGIN) return { kind: "skip" };
+  if (hasAbsolutePathTraversal(value)) {
+    return { kind: "broken", reason: "resolves outside the build output directory" };
+  }
   let decodedPath;
   try {
-    decodedPath = decodeURIComponent(pathPart);
+    decodedPath = decodeURIComponent(resolvedUrl.pathname);
   } catch {
     return { kind: "broken", reason: "malformed percent escape" };
   }
   if (decodedPath.includes("\0")) {
     return { kind: "broken", reason: "invalid path" };
   }
+  decodedPath = decodedPath.replaceAll("\\", "/");
   let relativeUrlPath;
   if (base === "/") {
     relativeUrlPath = decodedPath.slice(1).replace(/^\/+/, "");
@@ -129,20 +345,24 @@ function scanImgSrcs(options) {
   for (const htmlFile of htmlFiles) {
     const pagePath = relative(outDir, htmlFile).split(sep).join("/");
     const html = readFileSync(htmlFile, "utf8");
-    if (!/<img\b/iu.test(html)) continue;
-    for (const src of extractImgSrcs(html)) {
-      const resolved = resolveImgSrc(src, outDir, base, canonicalOutDir);
+    if (!/<(?:img|source|video|audio|track|input|image)\b/iu.test(html)) continue;
+    const document = parse(html);
+    const parsed = extractAssetReferences(document);
+    const documentBase = effectiveDocumentBase(makePageUrl(pagePath, base), parsed.baseHrefs);
+    for (const reference of parsed.references) {
+      const resolved = resolveImgSrc(reference.src, outDir, base, canonicalOutDir, documentBase);
       if (resolved.kind === "skip") continue;
       imageCount += 1;
       if (resolved.kind === "broken") {
-        broken.push({ pagePath, src, reason: resolved.reason });
+        broken.push({ pagePath, src: reference.src, element: reference.element, reason: resolved.reason });
       }
     }
   }
   return { htmlFileCount: htmlFiles.length, imageCount, broken };
 }
 function formatBrokenImgSrc(reference) {
-  return `[img-src-check] Broken image source in ${reference.pagePath}: ${reference.src} (${reference.reason})`;
+  const element = reference.element ? `${reference.element} ` : "";
+  return `[img-src-check] Broken image source in ${reference.pagePath}: ${element}${reference.src} (${reference.reason})`;
 }
 function checkImgSrcs(options) {
   const severity = options.onBroken ?? "warn";

package/dist/plugins/internal/resource-docs-shared/mdx.js

@@ -12,13 +12,14 @@ function escapeTitle(s) {
   return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 function formatFrontmatterString(value) {
+  const formatterRequiresQuotes = /["']/.test(value) || /^[?:-]/.test(value) || /^(?:yes|no|on|off)$/iu.test(value) || /^\+?(?:nan|inf(?:inity)?)$/iu.test(value);
   if (!/[\r\n]/.test(value)) {
     try {
       const parsed = matter(`---
 value: ${value}
 ---
 `).data.value;
-      if (parsed === value) return value;
+      if (parsed === value && !formatterRequiresQuotes) return value;
     } catch {
     }
   }