docnest 0.1.4 → 0.1.6

package/README.md

@@ -84,6 +84,13 @@ startServer(3000)
 
 存储适配器实现 `name`、`readDir`、`fileExists`、`readFile`、`readAsset`，可选实现 `ready`；这样文档内容仍由宿主项目提供，DocNest 只负责展示和交互。
 
+## 静态构建中的文档附件
+
+如果宿主项目需要生成静态站点，可使用 `docnest/attachments` 提供的
+`collectDocumentAttachmentPaths` 和 `copyDocumentAttachments`。它们只复制
+Markdown 或 HTML 中明确引用的本地附件，不按文件扩展名设置业务白名单；外链、文档链接、隐藏路径、路径穿越和代码块中的伪引用会被忽略，缺失的附件默认会让构建失败。
+常见凭据文件（如 `.env`、私钥和证书容器）属于公共安全阻断项，即使被误写进文档链接也不会进入静态产物。
+
 ## 开发
 
 ```bash

package/dist/attachments.d.ts

@@ -0,0 +1,11 @@
+export type DocumentAttachmentOptions = {
+    /**
+     * Whether a missing, non-Markdown local reference should fail collection.
+     * Defaults to true so static builds cannot silently publish broken assets.
+     */
+    failOnMissing?: boolean;
+};
+/** Collect every existing, explicitly referenced local document attachment. */
+export declare function collectDocumentAttachmentPaths(docsRoot: string, options?: DocumentAttachmentOptions): string[];
+/** Copy collected attachments while preserving their paths relative to docsRoot. */
+export declare function copyDocumentAttachments(sourceRoot: string, destinationRoot: string, options?: DocumentAttachmentOptions): string[];

package/dist/attachments.js

@@ -0,0 +1,148 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDocumentAttachmentPaths = collectDocumentAttachmentPaths;
+exports.copyDocumentAttachments = copyDocumentAttachments;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const MARKDOWN_SOURCE_EXTENSIONS = new Set(['.md', '.markdown']);
+const SENSITIVE_ATTACHMENT_EXTENSIONS = new Set([
+    '.env',
+    '.pem',
+    '.key',
+    '.p12',
+    '.pfx',
+    '.jks',
+    '.keystore',
+    '.secret',
+    '.secrets',
+]);
+const SENSITIVE_ATTACHMENT_NAMES = new Set([
+    'id_rsa',
+    'id_dsa',
+    'id_ecdsa',
+    'id_ed25519',
+]);
+const MARKDOWN_LINK_PATTERN = /!?\[[^\]]*\]\(\s*(?:<([^>\n]+)>|([^\s)]+))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g;
+const MARKDOWN_REFERENCE_PATTERN = /^\s{0,3}\[[^\]]+\]:\s*(?:<([^>\n]+)>|(\S+))/gm;
+const HTML_ASSET_PATTERN = /\b(?:src|href)=["']([^"']+)["']/gi;
+const FENCED_CODE_PATTERN = /(```|~~~)[^\n]*\n[\s\S]*?\n\1\s*/g;
+function collectMarkdownPaths(root, base = '') {
+    const results = [];
+    for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(root, base), { withFileTypes: true })) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+            continue;
+        const relativePath = base ? node_path_1.default.join(base, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownPaths(root, relativePath));
+        }
+        else if (entry.isFile() && MARKDOWN_SOURCE_EXTENSIONS.has(node_path_1.default.extname(entry.name).toLowerCase())) {
+            results.push(relativePath.replace(/\\/g, '/'));
+        }
+    }
+    return results;
+}
+function isLocalRelativeTarget(target) {
+    return !/^(?:[a-z][a-z0-9+.-]*:|\/\/|#|\/)/i.test(target);
+}
+function stripTargetSuffix(target) {
+    return target.split(/[?#]/, 1)[0];
+}
+function isSensitiveAttachment(target) {
+    const baseName = node_path_1.default.basename(target).toLowerCase();
+    return SENSITIVE_ATTACHMENT_EXTENSIONS.has(node_path_1.default.extname(baseName))
+        || SENSITIVE_ATTACHMENT_NAMES.has(baseName)
+        || baseName.startsWith('.env.');
+}
+function extractTargets(markdown) {
+    const source = markdown.replace(FENCED_CODE_PATTERN, '');
+    const targets = [];
+    MARKDOWN_LINK_PATTERN.lastIndex = 0;
+    for (const match of source.matchAll(MARKDOWN_LINK_PATTERN)) {
+        targets.push(match[1] || match[2] || '');
+    }
+    MARKDOWN_REFERENCE_PATTERN.lastIndex = 0;
+    for (const match of source.matchAll(MARKDOWN_REFERENCE_PATTERN)) {
+        targets.push(match[1] || match[2] || '');
+    }
+    HTML_ASSET_PATTERN.lastIndex = 0;
+    for (const match of source.matchAll(HTML_ASSET_PATTERN)) {
+        targets.push(match[1] || '');
+    }
+    return targets;
+}
+function resolveAttachmentPath(docsRoot, realDocsRoot, markdownPath, rawTarget, failOnMissing) {
+    if (!rawTarget || !isLocalRelativeTarget(rawTarget))
+        return null;
+    let decodedTarget;
+    try {
+        decodedTarget = decodeURIComponent(stripTargetSuffix(rawTarget));
+    }
+    catch {
+        return null;
+    }
+    if (!decodedTarget)
+        return null;
+    const extension = node_path_1.default.extname(decodedTarget).toLowerCase();
+    if (MARKDOWN_SOURCE_EXTENSIONS.has(extension))
+        return null;
+    if (isSensitiveAttachment(decodedTarget))
+        return null;
+    const resolved = node_path_1.default.resolve(docsRoot, node_path_1.default.dirname(markdownPath), decodedTarget);
+    const relative = node_path_1.default.relative(docsRoot, resolved);
+    if (!relative || node_path_1.default.isAbsolute(relative) || relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`)) {
+        return null;
+    }
+    const relativeSegments = relative.split(node_path_1.default.sep);
+    if (relativeSegments.some((segment) => segment.startsWith('.')))
+        return null;
+    if (!node_fs_1.default.existsSync(resolved)) {
+        if (failOnMissing) {
+            throw new Error(`文档附件不存在: ${markdownPath} -> ${rawTarget}`);
+        }
+        return null;
+    }
+    if (!node_fs_1.default.statSync(resolved).isFile())
+        return null;
+    // Do not follow a symlink out of the document root.
+    const realResolved = node_fs_1.default.realpathSync(resolved);
+    const realRelative = node_path_1.default.relative(realDocsRoot, realResolved);
+    if (node_path_1.default.isAbsolute(realRelative) || realRelative === '..' || realRelative.startsWith(`..${node_path_1.default.sep}`)) {
+        return null;
+    }
+    return relative.replace(/\\/g, '/');
+}
+/** Collect every existing, explicitly referenced local document attachment. */
+function collectDocumentAttachmentPaths(docsRoot, options = {}) {
+    const root = node_path_1.default.resolve(docsRoot);
+    if (!node_fs_1.default.statSync(root).isDirectory()) {
+        throw new Error(`文档目录不存在: ${docsRoot}`);
+    }
+    const realRoot = node_fs_1.default.realpathSync(root);
+    const failOnMissing = options.failOnMissing ?? true;
+    const results = new Set();
+    for (const markdownPath of collectMarkdownPaths(root)) {
+        const markdown = node_fs_1.default.readFileSync(node_path_1.default.join(root, markdownPath), 'utf8');
+        for (const rawTarget of extractTargets(markdown)) {
+            const attachmentPath = resolveAttachmentPath(root, realRoot, markdownPath, rawTarget, failOnMissing);
+            if (attachmentPath)
+                results.add(attachmentPath);
+        }
+    }
+    return [...results].sort();
+}
+/** Copy collected attachments while preserving their paths relative to docsRoot. */
+function copyDocumentAttachments(sourceRoot, destinationRoot, options = {}) {
+    const attachmentPaths = collectDocumentAttachmentPaths(sourceRoot, options);
+    const source = node_path_1.default.resolve(sourceRoot);
+    const destination = node_path_1.default.resolve(destinationRoot);
+    for (const relativePath of attachmentPaths) {
+        const sourcePath = node_path_1.default.join(source, relativePath);
+        const destinationPath = node_path_1.default.join(destination, relativePath);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(destinationPath), { recursive: true });
+        node_fs_1.default.copyFileSync(sourcePath, destinationPath);
+    }
+    return attachmentPaths;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docnest",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "可复用的本地 Markdown 文档中心",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
   },
   "exports": {
     "./config": "./dist/config.js",
+    "./attachments": "./dist/attachments.js",
     "./server": "./dist/server.js",
     ".": "./dist/config.js"
   },