hm-doc-tool 0.3.0

package/dist/download/summary-generator.d.ts

@@ -0,0 +1,46 @@
+import type { FlatNode, OutputTask } from "../common/types.js";
+/** Summary 节点结构 */
+export interface SummaryNode {
+    nodeId: string;
+    nodeName: string;
+    relateDocument: string | null;
+    parent: string | null;
+    summary: string;
+}
+/**
+ * 从 Markdown 内容中提取第一行正文
+ *
+ * 排除：
+ * - yaml frontmatter（--- 包裹的部分）
+ * - 标题（# 开头）
+ * - 代码块（``` 包裹的部分）
+ * - 空行
+ * - 链接（只保留链接文本）
+ */
+export declare function extractFirstLine(content: string): string;
+/**
+ * 为下载任务生成 summary（只处理叶子节点）
+ *
+ * @param nodes - 所有平铺节点
+ * @param tasks - 下载任务列表（包含正确的文件路径）
+ */
+export declare function generateSummary(nodes: FlatNode[], tasks: OutputTask[]): Promise<SummaryNode[]>;
+/**
+ * 保存 summary JSON 文件
+ *
+ * @param summaryNodes - summary 节点列表
+ * @param outputPath - 输出文件路径
+ */
+export declare function saveSummaryJson(summaryNodes: SummaryNode[], outputPath: string): Promise<void>;
+/**
+ * 生成 summary JSON 文件（主入口）
+ *
+ * 直接使用下载流程返回的任务列表和节点数据，避免重复计算路径
+ *
+ * @param catalogName - catalog 名称
+ * @param outputDir - 输出目录（下载时使用的 actualOutputDir）
+ * @param tasks - 下载任务列表
+ * @param nodes - 平铺节点列表
+ * @param targetNodeName - 目标节点名称（用于文件名）
+ */
+export declare function generateSummaryFromTasks(catalogName: string, outputDir: string, tasks: OutputTask[], nodes: FlatNode[], targetNodeName?: string): Promise<void>;

package/dist/download/summary-generator.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFirstLine = extractFirstLine;
+exports.generateSummary = generateSummary;
+exports.saveSummaryJson = saveSummaryJson;
+exports.generateSummaryFromTasks = generateSummaryFromTasks;
+/**
+ * Summary 生成器
+ *
+ * 职责：
+ * 1. 从下载的 Markdown 文件中提取第一行正文作为摘要
+ * 2. 生成 summary JSON 文件
+ */
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+/**
+ * 从 Markdown 内容中提取第一行正文
+ *
+ * 排除：
+ * - yaml frontmatter（--- 包裹的部分）
+ * - 标题（# 开头）
+ * - 代码块（``` 包裹的部分）
+ * - 空行
+ * - 链接（只保留链接文本）
+ */
+function extractFirstLine(content) {
+    const lines = content.split("\n");
+    let inFrontmatter = false;
+    let inCodeBlock = false;
+    let frontmatterEnded = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // 处理 yaml frontmatter
+        if (trimmed === "---") {
+            if (!inFrontmatter && !frontmatterEnded) {
+                // 第一个 --- 开始 frontmatter
+                inFrontmatter = true;
+                continue;
+            }
+            else if (inFrontmatter) {
+                // 第二个 --- 结束 frontmatter
+                inFrontmatter = false;
+                frontmatterEnded = true;
+                continue;
+            }
+        }
+        if (inFrontmatter)
+            continue;
+        // 处理代码块
+        if (trimmed.startsWith("```")) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // 跳过空行、标题、表格
+        if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("|"))
+            continue;
+        // 提取正文，去掉链接标记
+        let text = trimmed;
+        // 去掉列表符号
+        text = text.replace(/^-\s+/, "");
+        // 处理图片链接: ![alt](url) -> alt（必须在链接之前，否则 ![alt](url) 会被链接正则误匹配）
+        text = text.replace(/!\[([^\]]*)\]\([^()]*(?:\([^)]*\)[^()]*)*\)/g, "$1");
+        // 处理 markdown 链接: [text](url) -> text
+        // url 中可能含括号（如文件名），用 [^()]*(?:\([^)]*\)[^()]*)* 匹配一层嵌套
+        text = text.replace(/\[([^\]]+)\]\([^()]*(?:\([^)]*\)[^()]*)*\)/g, "$1");
+        // 处理 html 链接: <a href="url">text</a> -> text
+        text = text.replace(/<a\s+[^>]*>([^<]+)<\/a>/gi, "$1");
+        // 去掉加粗符号
+        text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+        // 如果处理后还有内容，且不是"说明"或"注意"，返回
+        const cleaned = text.trim();
+        if (cleaned && cleaned !== "说明" && cleaned !== "注意") {
+            // 跳过 API 版本说明文本
+            if (/API version \d+开始支持.*后续版本.*起始版本/.test(cleaned)) {
+                continue;
+            }
+            return cleaned;
+        }
+    }
+    return "";
+}
+/**
+ * 为下载任务生成 summary（只处理叶子节点）
+ *
+ * @param nodes - 所有平铺节点
+ * @param tasks - 下载任务列表（包含正确的文件路径）
+ */
+async function generateSummary(nodes, tasks) {
+    const summaryNodes = [];
+    // 创建 nodeId 到节点的映射
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    // 只处理叶子节点的下载任务
+    const leafTasks = tasks.filter((t) => t.isLeaf);
+    for (const task of leafTasks) {
+        const node = nodeMap.get(task.nodeId);
+        if (!node)
+            continue;
+        let summary = "";
+        const filePath = path.join(task.outputDir, task.fileName);
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            summary = extractFirstLine(content);
+        }
+        catch {
+            // 文件不存在或读取失败，summary 为空
+        }
+        // 如果没有提取到摘要，使用 nodeName
+        if (!summary) {
+            summary = node.nodeName;
+        }
+        summaryNodes.push({
+            nodeId: node.nodeId,
+            nodeName: node.nodeName,
+            relateDocument: node.relateDocument,
+            parent: node.parent,
+            summary,
+        });
+    }
+    return summaryNodes;
+}
+/**
+ * 保存 summary JSON 文件
+ *
+ * @param summaryNodes - summary 节点列表
+ * @param outputPath - 输出文件路径
+ */
+async function saveSummaryJson(summaryNodes, outputPath) {
+    const json = JSON.stringify(summaryNodes, null, 2);
+    await fs.writeFile(outputPath, json, "utf-8");
+}
+/**
+ * 生成 summary JSON 文件（主入口）
+ *
+ * 直接使用下载流程返回的任务列表和节点数据，避免重复计算路径
+ *
+ * @param catalogName - catalog 名称
+ * @param outputDir - 输出目录（下载时使用的 actualOutputDir）
+ * @param tasks - 下载任务列表
+ * @param nodes - 平铺节点列表
+ * @param targetNodeName - 目标节点名称（用于文件名）
+ */
+async function generateSummaryFromTasks(catalogName, outputDir, tasks, nodes, targetNodeName) {
+    console.log("\n正在生成 summary ...");
+    const summaryNodes = await generateSummary(nodes, tasks);
+    // 构建文件名：catalog-nodename_summary.json 或 catalog_summary.json
+    let summaryFileName = `${catalogName}_summary.json`;
+    if (targetNodeName) {
+        summaryFileName = `${catalogName}-${targetNodeName}_summary.json`;
+    }
+    const summaryPath = path.join(outputDir, summaryFileName);
+    await saveSummaryJson(summaryNodes, summaryPath);
+    console.log(`已生成 summary (${summaryNodes.length} 个节点) -> ${summaryPath}`);
+}

package/dist/download/turndown-rules.d.ts

@@ -0,0 +1,2 @@
+import TurndownService from "turndown";
+export declare function addCustomRules(td: TurndownService): void;

package/dist/download/turndown-rules.js

@@ -0,0 +1,394 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addCustomRules = addCustomRules;
+// UI text to strip from code blocks and content
+const UI_TEXT = new Set([
+    "展开", "收起", "复制", "深色代码主题", "自动换行", "深色",
+    "代码主题", "收起代码", "Copy", "Collapse",
+]);
+function isUnwantedText(text) {
+    return UI_TEXT.has(text.trim());
+}
+// --- Cleanup rules ---
+const removeCodeUIContainers = {
+    filter(node) {
+        if (node.nodeType !== 1)
+            return false;
+        const cls = node.className?.toLowerCase() ?? "";
+        return [
+            "code-operate", "code-tools", "code-action", "code-copy",
+            "code-fold", "code-theme", "code-line-num",
+            "table-expand", "table-collapse", "expand-btn", "collapse-btn",
+        ].some((c) => cls.includes(c));
+    },
+    replacement() {
+        return "";
+    },
+};
+const removeUIParagraphs = {
+    filter(node) {
+        if (node.nodeType !== 1)
+            return false;
+        if (!["P", "DIV", "SPAN", "TD", "TH"].includes(node.nodeName))
+            return false;
+        const text = (node.textContent ?? "").trim();
+        return text.length <= 10 && isUnwantedText(text);
+    },
+    replacement() {
+        return "";
+    },
+};
+// Navigation short text that should be removed when appearing as exact content
+const NAV_SHORT_TEXT = new Set([
+    "简体中文", "English", "Рус中文", "下载 App",
+    "探索", "设计", "开发", "分发", "推广与变现", "生态合作", "支持", "更多",
+    "立即登录", "输入关键字搜索",
+    "Hello，", "欢迎来到开发者联盟",
+    "CTRL+K", "Created with Pixso",
+    // FAQ 特定导航文本
+    "版本说明", "指南", "API参考", "最佳实践", "FAQ", "变更预告",
+    "多设备场景", "手机", "Pura X常见问题",
+    "应用质量", "技术质量",
+    "开发者能力认证", "我的", "管理中心", "个人中心",
+    "我的学堂", "我的收藏", "我的活动", "我的工单",
+    // FAQ 侧边栏标签
+    "Stack", "HarmonyOS 6", "animation", "module.json5",
+    "layoutWeight", "Navigation", "bindPopup", "bindsheet",
+    "RelativeContainer", "CustomDialogController", "animateTo",
+]);
+const removeNavigation = {
+    filter(node) {
+        if (node.nodeType !== 1)
+            return false;
+        const text = (node.textContent ?? "").trim();
+        // Remove elements whose text exactly matches navigation short text
+        if (text.length <= 20 && NAV_SHORT_TEXT.has(text)) {
+            return true;
+        }
+        // Remove empty paragraphs (but keep those with images/tables/code)
+        if (node.nodeName === "P" && text.length === 0) {
+            const hasContent = node.querySelector("img, code, pre, table");
+            if (!hasContent)
+                return true;
+        }
+        const cls = node.className?.toLowerCase() ?? "";
+        const id = node.id?.toLowerCase() ?? "";
+        const unwantedClasses = [
+            "top-bar", "menu-bar", "sidebar", "search-bar", "breadcrumb", "toolbar", "footer-nav", "main-nav",
+            "side-nav", "nav-menu", "header-nav", "page-header",
+            "doc-nav", "related-links", "more-links",
+            "social-share", "social-links", "social-media",
+            "community-section", "feedback-section", "qrcode-section",
+        ];
+        const classList = cls.split(/\s+/);
+        const matchesClass = classList.some((c) => unwantedClasses.some((u) => c === u || c.startsWith(u + "-") || c.endsWith("-" + u)));
+        const matchesId = unwantedClasses.some((u) => id === u || id.startsWith(u + "-") || id.endsWith("-" + u));
+        return matchesClass || matchesId;
+    },
+    replacement() {
+        return "";
+    },
+};
+const removeCodeUI = {
+    filter(node) {
+        if (node.nodeType === 3) {
+            return isUnwantedText(node.textContent ?? "");
+        }
+        if (node.nodeType === 1 && ["P", "DIV", "SPAN"].includes(node.nodeName)) {
+            const text = (node.textContent ?? "").trim();
+            return isUnwantedText(text);
+        }
+        return false;
+    },
+    replacement() {
+        return "";
+    },
+};
+const removePlatformBadge = {
+    filter(node) {
+        return node.nodeType === 3 && node.textContent?.trim() === "PhonePC/2in1TabletTVWearable";
+    },
+    replacement() {
+        return "";
+    },
+};
+// --- Code block rules ---
+const huaweiCodeBlock = {
+    filter(node) {
+        return node.nodeName === "PRE" && !!node.querySelector("ol.linenums");
+    },
+    replacement(_content, node) {
+        const langMatch = (node.className ?? "").match(/language-(\w+)/);
+        const language = langMatch?.[1] ?? "";
+        const lines = [];
+        const ol = node.querySelector("ol.linenums");
+        if (ol) {
+            const lis = ol.querySelectorAll("li");
+            for (let i = 0; i < lis.length; i++) {
+                const li = lis[i];
+                const text = (li.textContent ?? "").replace(/\n+$/, "").trimEnd();
+                if (text && !isUnwantedText(text)) {
+                    lines.push(text);
+                }
+            }
+        }
+        return "\n```" + language + "\n" + lines.join("\n") + "\n```\n";
+    },
+};
+function inferLanguage(codeText) {
+    if (codeText.includes("import ") || codeText.includes("export ") || codeText.includes("interface ")) {
+        return "typescript";
+    }
+    if (codeText.includes("#include") || codeText.includes("int main")) {
+        return "cpp";
+    }
+    if (codeText.includes("public class")) {
+        return "java";
+    }
+    return "";
+}
+const genericPre = {
+    filter(node) {
+        return node.nodeName === "PRE" && !node.querySelector("ol.linenums");
+    },
+    replacement(content, node) {
+        const codeElem = node.querySelector("code");
+        let codeText = codeElem?.textContent ?? node.textContent ?? "";
+        if (content && content.trim().length > codeText.trim().length) {
+            codeText = content;
+        }
+        // Detect language from class
+        let language = "";
+        const clsMatch = (node.className ?? "").match(/language-(\w+)/);
+        if (clsMatch)
+            language = clsMatch[1];
+        if (!language && codeElem) {
+            const codeMatch = (codeElem.className ?? "").match(/language-(\w+)/);
+            if (codeMatch)
+                language = codeMatch[1];
+        }
+        // Infer language from content if not detected
+        if (!language && codeText) {
+            language = inferLanguage(codeText);
+        }
+        const cleanLines = codeText.split("\n").filter((line) => {
+            const trimmed = line.trim();
+            return !trimmed || !isUnwantedText(trimmed);
+        });
+        return "\n```" + language + "\n" + cleanLines.join("\n") + "\n```\n";
+    },
+};
+const standardCodeBlock = {
+    filter(node) {
+        return node.nodeName === "PRE"
+            && !!node.firstChild
+            && node.firstChild.nodeName === "CODE";
+    },
+    replacement(content, node) {
+        const codeNode = node.firstChild;
+        const lang = codeNode.className || codeNode.getAttribute("class") || "";
+        const langMatch = lang.match(/language-(\w+)|hljs language-(\w+)/);
+        const language = langMatch ? (langMatch[1] || langMatch[2]) : "";
+        const codeContent = codeNode.textContent || content;
+        const cleanContent = codeContent
+            .split("\n")
+            .filter((line) => {
+            const trimmed = line.trim();
+            return !isUnwantedText(trimmed);
+        })
+            .join("\n");
+        return "\n```" + language + "\n" + cleanContent + "\n```\n";
+    },
+};
+// --- Table rules ---
+/**
+ * 递归提取节点的富文本内容，保留链接、代码、图片等内联格式
+ */
+function richTextContent(node) {
+    let result = "";
+    for (const child of Array.from(node.childNodes)) {
+        if (child.nodeType === 3) {
+            result += child.textContent ?? "";
+        }
+        else if (child.nodeType === 1) {
+            const el = child;
+            if (el.nodeName === "A" && el.getAttribute("href")) {
+                const href = el.getAttribute("href");
+                const full = href.startsWith("#") ? href : href.startsWith("http") ? href : `https://developer.huawei.com${href}`;
+                result += `[${el.textContent?.trim() ?? ""}](${full})`;
+            }
+            else if (el.nodeName === "CODE") {
+                result += `\`${el.textContent?.trim() ?? ""}\``;
+            }
+            else if (el.nodeName === "SUP") {
+                result += `<sup>${el.textContent ?? ""}</sup>`;
+            }
+            else if (el.nodeName === "IMG") {
+                const src = el.getAttribute("src") ?? "";
+                const alt = el.getAttribute("alt") ?? "";
+                result += `![${alt}](${src})`;
+            }
+            else if (el.nodeName === "P" || el.nodeName === "DIV" || el.nodeName === "SPAN" || el.nodeName === "STRONG" || el.nodeName === "EM") {
+                // 递归处理容器元素，保留内部格式
+                const inner = richTextContent(el);
+                if (el.nodeName === "STRONG")
+                    result += `**${inner}**`;
+                else if (el.nodeName === "EM")
+                    result += `*${inner}*`;
+                else
+                    result += inner;
+            }
+            else {
+                result += richTextContent(el);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 提取单元格富文本内容，保留链接、代码、图片等内联格式
+ */
+function cellRichText(cell) {
+    return cleanCellText(richTextContent(cell));
+}
+function cleanCellText(text) {
+    let cleaned = text.replace(/\s+/g, " ");
+    for (const t of UI_TEXT) {
+        cleaned = cleaned.replaceAll(t, "");
+    }
+    return cleaned.trim();
+}
+const harmonyTable = {
+    filter(node) {
+        return node.nodeName === "TABLE";
+    },
+    replacement(_content, node) {
+        const rows = Array.from(node.querySelectorAll("tr"));
+        if (rows.length === 0)
+            return "";
+        let md = "\n";
+        rows.forEach((row, rowIndex) => {
+            const cells = Array.from(row.children)
+                .filter((c) => c.nodeName === "TH" || c.nodeName === "TD")
+                .map((cell) => {
+                return cellRichText(cell);
+            });
+            if (cells.length === 0)
+                return;
+            md += "| " + cells.join(" | ") + " |\n";
+            const isHeader = rowIndex === 0 &&
+                (Array.from(row.children).every((_, i) => row.children[i]?.nodeName === "TH") ||
+                    row.parentElement?.nodeName === "THEAD");
+            if (isHeader) {
+                md += "| " + cells.map(() => "---").join(" | ") + " |\n";
+            }
+        });
+        return md + "\n";
+    },
+};
+const divTable = {
+    filter(node) {
+        if (node.nodeType !== 1 || node.nodeName !== "DIV")
+            return false;
+        const cls = (node.className ?? "").toLowerCase();
+        const tableClasses = ["table", "tbl", "data-table", "table-container", "table-wrap"];
+        if (!tableClasses.some((c) => cls.includes(c)))
+            return false;
+        const rowDivs = Array.from(node.children).filter((child) => {
+            const childClass = (child.className ?? "").toLowerCase();
+            return childClass.includes("tr") || childClass.includes("row") || childClass.includes("table-row");
+        });
+        return rowDivs.length > 0;
+    },
+    replacement(content, node) {
+        const rows = Array.from(node.children).filter((child) => {
+            const childClass = (child.className ?? "").toLowerCase();
+            return childClass.includes("tr") || childClass.includes("row") || childClass.includes("table-row");
+        });
+        if (rows.length === 0)
+            return content;
+        let md = "\n";
+        rows.forEach((row, rowIndex) => {
+            const cells = Array.from(row.children)
+                .filter((child) => {
+                const childClass = (child.className ?? "").toLowerCase();
+                return childClass.includes("td") || childClass.includes("th") || childClass.includes("cell");
+            })
+                .map((cell) => {
+                return cellRichText(cell);
+            });
+            if (cells.length === 0)
+                return;
+            md += "| " + cells.join(" | ") + " |\n";
+            if (rowIndex === 0) {
+                md += "| " + cells.map(() => "---").join(" | ") + " |\n";
+            }
+        });
+        return md + "\n";
+    },
+};
+// --- Superscript rule ---
+const processSuperscript = {
+    filter(node) {
+        return node.nodeName === "SUP";
+    },
+    replacement(content) {
+        return ` <sup>${content}</sup>`;
+    },
+};
+// --- Image rules ---
+const processImages = {
+    filter(node) {
+        return node.nodeName === "IMG";
+    },
+    replacement(content, node) {
+        const src = node.getAttribute("src") ?? "";
+        const alt = node.getAttribute("alt") ?? "";
+        // 检查是否是特殊图标
+        if (src.includes("note_3.0-zh-cn.png")) {
+            return "**说明**";
+        }
+        if (src.includes("notice_3.0-zh-cn.png") || src.includes("caution_3.0-zh-cn.png")) {
+            return "**注意**";
+        }
+        // 普通图片，保持原有格式
+        return `![${alt}](${src})`;
+    },
+};
+// --- Link rule ---
+const processLinks = {
+    filter(node) {
+        return node.nodeName === "A" && !!node.getAttribute("href");
+    },
+    replacement(content, node) {
+        const href = node.getAttribute("href");
+        if (!href || href === "#" || href === "javascript:void(0)")
+            return content ?? "";
+        // 锚点链接保持原样，不拼域名
+        if (href.startsWith("#"))
+            return `[${content}](${href})`;
+        const full = href.startsWith("http") ? href : `https://developer.huawei.com${href}`;
+        return `[${content}](${full})`;
+    },
+};
+// --- Register all ---
+function addCustomRules(td) {
+    const rules = [
+        ["removeCodeUIContainers", removeCodeUIContainers],
+        ["removeUIParagraphs", removeUIParagraphs],
+        ["removeNavigation", removeNavigation],
+        ["removeCodeUI", removeCodeUI],
+        ["removePlatformBadge", removePlatformBadge],
+        ["huaweiCodeBlock", huaweiCodeBlock],
+        ["genericPre", genericPre],
+        ["standardCodeBlock", standardCodeBlock],
+        ["harmonyTable", harmonyTable],
+        ["divTable", divTable],
+        ["processSuperscript", processSuperscript],
+        ["processImages", processImages],
+        ["processLinks", processLinks],
+    ];
+    for (const [name, rule] of rules) {
+        td.addRule(name, rule);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};