skill-family-doc-render 0.2.1 → 0.4.0

package/scripts/lib/markdown-v1.mjs

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// 将受限 markdown-v1 编译为 editorial 模板的语义内容块。
+import { Lexer } from 'marked';
+
+const TOKEN = /@[A-Z0-9_]+@/g;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+export class MarkdownV1Error extends TypeError {
+  constructor(message) {
+    super(`markdown-v1: ${message}`);
+  }
+}
+
+const fail = (message) => { throw new MarkdownV1Error(message); };
+
+/** Replace configured facts as literal data, never as Markdown syntax. */
+export function replaceMarkdownTokens(value, tokens, label = 'text') {
+  if (typeof value !== 'string') fail(`${label} must be a string`);
+  const replaced = value.replace(TOKEN, (match) => (
+    Object.hasOwn(tokens, match) ? String(tokens[match]) : match
+  ));
+  const residual = replaced.match(TOKEN);
+  if (residual) fail(`${label} contains unresolved token(s): ${[...new Set(residual)].join(', ')}`);
+  return replaced;
+}
+
+function inline(tokens, facts, label) {
+  const result = [];
+  for (const token of tokens || []) {
+    switch (token.type) {
+      case 'text':
+        if (token.tokens?.length) result.push(...inline(token.tokens, facts, label));
+        else result.push(replaceMarkdownTokens(token.text, facts, label));
+        break;
+      case 'escape':
+        result.push(replaceMarkdownTokens(token.text, facts, label));
+        break;
+      case 'strong':
+      case 'em':
+        result.push({ type: token.type, content: inline(token.tokens, facts, label) });
+        break;
+      case 'codespan':
+        result.push({ type: 'code', text: replaceMarkdownTokens(token.text, facts, label) });
+        break;
+      case 'link':
+        if (token.title) fail(`${label} link titles are not supported`);
+        result.push({
+          type: 'link',
+          href: replaceMarkdownTokens(token.href, facts, `${label} link`),
+          content: inline(token.tokens, facts, label),
+        });
+        break;
+      case 'image':
+        fail(`${label} images must be the only content in their paragraph`);
+        break;
+      case 'html':
+        fail(`${label} raw HTML is not supported`);
+        break;
+      default:
+        fail(`${label} uses unsupported inline syntax: ${token.type}`);
+    }
+  }
+  return result;
+}
+
+function listItem(item, facts, label) {
+  if (item.task || item.checked !== undefined) fail(`${label} task lists are not supported`);
+  const content = item.tokens.filter((token) => token.type !== 'space');
+  if (content.length !== 1 || !['text', 'paragraph'].includes(content[0].type)) {
+    fail(`${label} nested or multi-paragraph list items are not supported`);
+  }
+  const token = content[0];
+  return inline(token.tokens || Lexer.lexInline(token.text, { gfm: true }), facts, label);
+}
+
+function explicitHeading(token) {
+  const match = /^(.*\S)\s+\{#([A-Za-z0-9][A-Za-z0-9_-]*)\}\s*$/.exec(token.text);
+  if (!match) {
+    if (/\s+\{[^}]*\}\s*$/.test(token.text)) fail('heading contains an unsupported or invalid attribute extension');
+    return null;
+  }
+  return { title: match[1], id: match[2] };
+}
+
+function slug(title) {
+  const value = title
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return value || 'section';
+}
+
+function callout(token, facts, label) {
+  const meaningful = token.tokens.filter((item) => item.type !== 'space');
+  if (meaningful.length !== 1 || meaningful[0].type !== 'paragraph') {
+    fail(`${label} callout must contain one paragraph`);
+  }
+  const match = /^\[!(NOTE|TIP|WARNING)\]\s*\n([\s\S]*\S)\s*$/.exec(meaningful[0].text);
+  if (!match) fail(`${label} blockquotes must use NOTE, TIP, or WARNING callout syntax`);
+  return {
+    type: 'callout',
+    tone: match[1],
+    content: inline(Lexer.lexInline(match[2], { gfm: true }), facts, label),
+  };
+}
+
+/**
+ * @param {string} source
+ * @param {{pageId:string,tokens?:Record<string,string|number|boolean>}} options
+ * @returns {{blocks:object[],images:string[]}}
+ */
+export function compileMarkdownV1(source, { pageId, tokens = {} }) {
+  if (typeof source !== 'string' || source.includes('\u0000')) fail(`${pageId}.md must be UTF-8 text without NUL`);
+  if (!SAFE_ID.test(pageId)) fail(`invalid page ID: ${pageId}`);
+
+  let lexed;
+  try {
+    lexed = Lexer.lex(source, { gfm: true, breaks: false, pedantic: false });
+  } catch (cause) {
+    throw new MarkdownV1Error(`${pageId}.md cannot be tokenized: ${cause.message}`);
+  }
+
+  const explicitIds = new Set([pageId]);
+  for (const token of lexed) {
+    if (token.type !== 'heading') continue;
+    if (token.depth === 1) fail(`${pageId}.md must not contain an H1`);
+    if (![2, 3, 4].includes(token.depth)) fail(`${pageId}.md heading levels must be H2-H4`);
+    const explicit = explicitHeading(token);
+    if (!explicit) continue;
+    if (explicit.id.startsWith('editorial-')) fail(`${pageId}.md uses a reserved heading ID: ${explicit.id}`);
+    if (explicitIds.has(explicit.id)) fail(`${pageId}.md contains duplicate heading ID: ${explicit.id}`);
+    explicitIds.add(explicit.id);
+  }
+
+  const usedIds = new Set(explicitIds);
+  const blocks = [];
+  const images = new Set();
+  for (const token of lexed) {
+    const label = `${pageId}.md`;
+    switch (token.type) {
+      case 'space':
+        break;
+      case 'paragraph': {
+        if (token.tokens.length === 1 && token.tokens[0].type === 'image') {
+          const image = token.tokens[0];
+          if (image.title) fail(`${label} image titles are not supported`);
+          const src = replaceMarkdownTokens(image.href, tokens, `${label} image`);
+          const alt = replaceMarkdownTokens(image.text, tokens, `${label} image alt`);
+          blocks.push({ type: 'image', src, alt });
+          images.add(src);
+        } else {
+          blocks.push({ type: 'paragraph', content: inline(token.tokens, tokens, label) });
+        }
+        break;
+      }
+      case 'heading': {
+        const explicit = explicitHeading(token);
+        const title = explicit?.title ?? token.text;
+        let headingId = explicit?.id;
+        if (!headingId) {
+          const candidate = slug(title);
+          const base = candidate.startsWith('editorial-') ? `section-${candidate}` : candidate;
+          headingId = base;
+          let suffix = 2;
+          while (usedIds.has(headingId)) {
+            headingId = `${base}-${suffix}`;
+            suffix += 1;
+          }
+          usedIds.add(headingId);
+        }
+        const headingTokens = Lexer.lexInline(title, { gfm: true });
+        blocks.push({ type: 'heading', level: token.depth, id: headingId, content: inline(headingTokens, tokens, label) });
+        break;
+      }
+      case 'list':
+        if (token.ordered && token.start !== 1) fail(`${label} ordered lists must start at 1`);
+        blocks.push({
+          type: 'list',
+          ordered: token.ordered,
+          items: token.items.map((item, index) => listItem(item, tokens, `${label} list item ${index + 1}`)),
+        });
+        break;
+      case 'table':
+        blocks.push({
+          type: 'table',
+          headers: token.header.map((cell) => inline(cell.tokens, tokens, label)),
+          rows: token.rows.map((row) => row.map((cell) => inline(cell.tokens, tokens, label))),
+        });
+        break;
+      case 'code':
+        if (!token.lang || token.codeBlockStyle === 'indented') fail(`${label} code fences require a language marker`);
+        blocks.push({
+          type: 'code',
+          language: token.lang,
+          text: replaceMarkdownTokens(token.text, tokens, `${label} code`),
+        });
+        break;
+      case 'blockquote':
+        blocks.push(callout(token, tokens, label));
+        break;
+      case 'html':
+        fail(`${label} raw HTML is not supported`);
+        break;
+      case 'def':
+        fail(`${label} reference definitions are not supported`);
+        break;
+      default:
+        fail(`${label} uses unsupported block syntax: ${token.type}`);
+    }
+  }
+  return { blocks, images: [...images].sort() };
+}

package/scripts/lib/rendered-links.mjs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// 只读检查已渲染站点的相对页面、资源、CSS 依赖与页内锚点。
+import { dirname, extname, relative, resolve } from 'node:path';
+import { readFileContained, resolveContained } from 'skill-family-harness-node';
+
+export class RenderedLinksError extends Error {
+  constructor(failures) {
+    super(`${failures.length} 个链接失败:\n  - ${failures.join('\n  - ')}`);
+    this.failures = failures;
+  }
+}
+
+function isExternal(value) {
+  return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value);
+}
+
+function anchorsOf(html) {
+  const anchors = new Set();
+  for (const match of html.matchAll(/\s(?:id|name)\s*=\s*["']([^"']+)["']/gi)) anchors.add(match[1]);
+  return anchors;
+}
+
+function referencesOf(html) {
+  const refs = [];
+  for (const match of html.matchAll(/\s(?:href|src)\s*=\s*["']([^"']+)["']/gi)) refs.push(match[1].trim());
+  return refs;
+}
+
+function cssReferencesOf(css) {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const refs = [];
+  for (const match of withoutComments.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)) refs.push(match[2].trim());
+  for (const match of withoutComments.matchAll(/@import\s+(?!url\()(["'])(.*?)\1/gi)) refs.push(match[2].trim());
+  return refs;
+}
+
+/**
+ * @param {{targetRoot:string,pageIds:string[]}} input
+ * @returns {Promise<{pages:number}>}
+ */
+export async function checkRenderedLinks({ targetRoot, pageIds }) {
+  const targetDir = resolve(targetRoot);
+  const htmlFiles = pageIds.map((id) => `${id}.html`);
+  const textCache = new Map();
+  const loadText = async (path) => {
+    if (!textCache.has(path)) {
+      textCache.set(path, await readFileContained(targetDir, relative(targetDir, path), { encoding: 'utf8' }));
+    }
+    return textCache.get(path);
+  };
+  const failures = [];
+  const visitedCss = new Set();
+  const visitedHtml = new Set();
+
+  async function inspectReference({ originPath, originLabel, raw }) {
+    if (!raw || raw === '#' || isExternal(raw)) return;
+    if (raw.startsWith('/')) {
+      failures.push(`${originLabel}: ${raw} 使用站点根绝对路径，部署到仓库子路径后会失效`);
+      return;
+    }
+    const [withoutFragment, fragment = ''] = raw.split('#', 2);
+    const pathPart = withoutFragment.split('?', 1)[0];
+    let decoded;
+    try {
+      decoded = decodeURIComponent(pathPart);
+    } catch {
+      failures.push(`${originLabel}: ${raw} 含无效 URL 编码`);
+      return;
+    }
+    const candidate = decoded ? resolve(dirname(originPath), decoded) : originPath;
+    let target;
+    try {
+      target = candidate === originPath
+        ? originPath
+        : await resolveContained(targetDir, relative(targetDir, candidate));
+      await readFileContained(targetDir, relative(targetDir, target));
+    } catch {
+      failures.push(`${originLabel}: ${raw} 指向不存在、越界或经过不安全符号链接的页面或资源`);
+      return;
+    }
+    const extension = extname(target).toLowerCase();
+    if (fragment && extension === '.html') {
+      const targetHtml = await loadText(target);
+      let decodedFragment;
+      try {
+        decodedFragment = decodeURIComponent(fragment);
+      } catch {
+        failures.push(`${originLabel}: ${raw} 含无效锚点编码`);
+        return;
+      }
+      if (!anchorsOf(targetHtml).has(decodedFragment)) failures.push(`${originLabel}: ${raw} 指向不存在的页内锚点`);
+    }
+    if (extension === '.html') await inspectHtml(target, relative(targetDir, target).replaceAll('\\', '/'));
+    if (extension === '.css') {
+      const cssRel = relative(targetDir, target).replaceAll('\\', '/');
+      if (visitedCss.has(cssRel)) return;
+      visitedCss.add(cssRel);
+      const css = await loadText(target);
+      for (const cssRef of cssReferencesOf(css)) {
+        await inspectReference({ originPath: target, originLabel: cssRel, raw: cssRef });
+      }
+    }
+  }
+
+  async function inspectHtml(pagePath, htmlFile, required = false) {
+    if (visitedHtml.has(htmlFile)) return;
+    visitedHtml.add(htmlFile);
+    let html;
+    try {
+      html = await loadText(pagePath);
+    } catch {
+      if (required) failures.push(`${htmlFile}: 生成页面不存在`);
+      return;
+    }
+    for (const raw of referencesOf(html)) await inspectReference({ originPath: pagePath, originLabel: htmlFile, raw });
+  }
+
+  for (const htmlFile of htmlFiles) {
+    await inspectHtml(resolve(targetDir, htmlFile), htmlFile, true);
+  }
+
+  if (failures.length) throw new RenderedLinksError(failures);
+  return { pages: htmlFiles.length };
+}

package/scripts/lib/svg-safety.mjs

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// 对项目内容 SVG 做保守的主动内容检查；模板自带图标不走此入口。
+
+export class SvgSafetyError extends TypeError {
+  constructor(path, message) {
+    super(`unsafe SVG ${path}: ${message}`);
+  }
+}
+
+const reject = (path, message) => { throw new SvgSafetyError(path, message); };
+
+function decodeCssEscapes(value) {
+  return value
+    .replace(/\\([0-9a-f]{1,6})\s?/gi, (_match, digits) => {
+      const codePoint = Number.parseInt(digits, 16);
+      return codePoint === 0 || codePoint > 0x10ffff ? '\uFFFD' : String.fromCodePoint(codePoint);
+    })
+    .replace(/\\([^\r\n\f])/g, '$1');
+}
+
+export function assertSafeSvg(text, path) {
+  if (typeof text !== 'string' || !text.trim()) reject(path, 'file must be nonempty UTF-8 text');
+  if (text.includes('\u0000')) reject(path, 'NUL is not allowed');
+  if (!/^\s*(?:<\?xml\s[^?]*\?>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg(?:\s|>)/i.test(text)) {
+    reject(path, 'root element must be svg');
+  }
+  if (/<!\s*(?:DOCTYPE|ENTITY)\b/i.test(text)) reject(path, 'DTD and entity declarations are not allowed');
+  if (/<\/?(?:[A-Za-z_][\w.-]*:)?(?:script|foreignObject)(?:\s|\/?>)/i.test(text)) {
+    reject(path, 'script and foreignObject elements are not allowed');
+  }
+  if (/\s(?:[A-Za-z_][\w.-]*:)?on[a-z0-9_.:-]*\s*=/i.test(text)) reject(path, 'event attributes are not allowed');
+  if (/<\?(?!xml\s)[\s\S]*?\?>/i.test(text)) reject(path, 'processing instructions are not allowed');
+  if (/\b(?:href|xlink:href|src)\s*=\s*(["'])(?!#)[\s\S]*?\1/i.test(text)) {
+    reject(path, 'external resource references are not allowed');
+  }
+  if (/\b(?:href|xlink:href|src)\s*=\s*[^\s"'=<>`]+/i.test(text)) {
+    reject(path, 'resource references must be quoted local fragments');
+  }
+  const decodedCss = decodeCssEscapes(text);
+  if (/@import\b/i.test(decodedCss)) reject(path, 'CSS imports are not allowed');
+  for (const match of decodedCss.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)) {
+    if (!/^#[A-Za-z0-9][A-Za-z0-9_-]*$/.test(match[2])) reject(path, 'CSS URLs must be local fragments');
+  }
+  return text;
+}