hexo-text-pipeline 0.2.0

package/lib/core/loaders/command.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+const DEFAULT_TIMEOUT_MS = 10000;
+const MAX_BUFFER = 32 * 1024 * 1024;
+
+/**
+ * command hook → node：外部命令，正文从 stdin 进、变换结果从 stdout 出，任何语言。
+ * 上下文走环境变量：HTP_STAGE / HTP_SLOT 恒有；post 类 stage 给
+ * HTP_POST_SOURCE / HTP_POST_PATH / HTP_POST_TITLE，string 类给 HTP_FILE_PATH——
+ * 与 ctx.post / ctx.file 的分流一一对应，不再用空的 POST 变量冒充。
+ * 非零退出 / 启动失败 → 抛错，由 runtime checker 隔离（跳过该 node，原文继续）。
+ */
+function createCommandNode(hook) {
+  return {
+    name: 'hook:' + hook.name,
+    stage: hook.stage,
+    slot: hook.slot,
+    priority: hook.priority,
+    origin: 'hook:command',
+    convert(content, ctx) {
+      const env = Object.assign({}, process.env, {
+        HTP_STAGE: hook.stage,
+        HTP_SLOT: hook.slot
+      });
+      if (ctx && ctx.post) {
+        env.HTP_POST_SOURCE = ctx.post.source || '';
+        env.HTP_POST_PATH = ctx.post.path || '';
+        env.HTP_POST_TITLE = ctx.post.title || '';
+      }
+      if (ctx && ctx.file) {
+        env.HTP_FILE_PATH = ctx.file.path || '';
+      }
+      const result = spawnSync(hook.command, {
+        input: content,
+        shell: true,
+        encoding: 'utf8',
+        timeout: hook.timeout || DEFAULT_TIMEOUT_MS,
+        maxBuffer: MAX_BUFFER,
+        env
+      });
+
+      if (result.error) {
+        throw new Error('command failed to start: ' + result.error.message);
+      }
+      if (result.status !== 0) {
+        const stderr = (result.stderr || '').trim().slice(0, 500);
+        throw new Error('command exited with ' + result.status + (stderr ? ': ' + stderr : ''));
+      }
+      return result.stdout;
+    }
+  };
+}
+
+module.exports = { createCommandNode, DEFAULT_TIMEOUT_MS };

package/lib/core/loaders/hooks.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const { resolvePlacement } = require('../node-contract');
+const { createCommandNode } = require('./command');
+const { createScriptNode } = require('./script');
+
+/**
+ * 解析配置里的 hooks 数组（用户随时插入的自定义脚本），两种形态：
+ *
+ * text_pipeline:
+ *   hooks:
+ *     - command: python scripts/furigana.py   # 外部命令（stdin → stdout）
+ *       stage: before_post_render             # 可选，默认 before_post_render
+ *       priority: 20                          # 可选，默认 10，小者先跑
+ *       name: furigana                        # 可选，日志标识
+ *       timeout: 10000                        # 可选，毫秒（仅 command）
+ *     - script: scripts/toc.js                # 本地 JS：module.exports = (text, ctx) => text
+ *       match: '\\[\\[toc\\]\\]'              # 可选：正则预判，文本不命中就跳过（command 可省一次 spawn）
+ *       slot: late                            # 可选：默认 late（在 hexo 内置/其他插件之后，
+ *                                             #   看到最终文本）；slot: early 抢到它们之前
+ *
+ * stage / slot / priority / match 的默认值与校验在 node-contract.js，
+ * 与 textPipeline.register、preset 加载共用同一套规则。
+ * 非法条目收集为 issue（warn 或 strict 下报错），不中断其他条目。
+ */
+function normalizeHookEntry(raw, index) {
+  if (!raw || typeof raw !== 'object') {
+    return { error: 'hooks[' + index + '] must be an object with a command or script field' };
+  }
+  if (raw.enable === false) {
+    return null;
+  }
+
+  const command = typeof raw.command === 'string' ? raw.command.trim() : '';
+  const script = typeof raw.script === 'string' ? raw.script.trim() : '';
+  if (!command && !script) {
+    return { error: 'hooks[' + index + '] is missing a command or script' };
+  }
+  if (command && script) {
+    return { error: 'hooks[' + index + '] sets both command and script; pick one' };
+  }
+
+  const resolved = resolvePlacement(raw, 'hook');
+  if (resolved.error) {
+    return { error: 'hooks[' + index + '] has ' + resolved.error };
+  }
+
+  return {
+    hook: {
+      name: typeof raw.name === 'string' && raw.name ? raw.name : 'hook-' + index,
+      stage: resolved.placement.stage,
+      slot: resolved.placement.slot,
+      priority: resolved.placement.priority,
+      test: resolved.placement.test,
+      command,
+      script,
+      timeout: Number.isFinite(raw.timeout) && raw.timeout > 0 ? raw.timeout : undefined
+    }
+  };
+}
+
+function loadHooks(rawHooks, baseDir) {
+  const nodes = [];
+  const issues = [];
+
+  (rawHooks || []).forEach((raw, index) => {
+    const parsed = normalizeHookEntry(raw, index);
+    if (!parsed) return;
+    if (parsed.error) {
+      issues.push({ level: 'error', message: parsed.error });
+      return;
+    }
+    const node = parsed.hook.command ? createCommandNode(parsed.hook) : createScriptNode(parsed.hook, baseDir);
+    if (parsed.hook.test) {
+      node.test = parsed.hook.test;
+    }
+    nodes.push(node);
+  });
+
+  return { nodes, issues };
+}
+
+module.exports = { loadHooks, _internal: { normalizeHookEntry } };

package/lib/core/loaders/plugin-dir.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { nodeConfig, isNodeEnabled } = require('../config');
+const { resolvePlacement, resolveConvert } = require('../node-contract');
+const { invalidateModuleTree } = require('./script');
+const { suggest } = require('../checker/static');
+
+/**
+ * 单文件插件目录（第四条注册路径，role 'plugin'）——写插件 = 写一个文件：
+ *
+ *   <hexo 根>/text-pipeline/arrow.js
+ *   module.exports = { replace: [[/-->/g, '→']] };
+ *
+ * 约定：
+ * - 目录里每个顶层 .js 文件自动挂载，零配置生效；`_` 前缀文件跳过（共享辅助模块）；
+ *   按文件名排序保证注册顺序确定。
+ * - 导出单个 node 对象（与统一契约同形；name 缺省取文件名）或 node 数组
+ *   （数组元素必须显式 name）。不收裸函数——`(text, ctx) => text` 的函数语义
+ *   由 hooks 的 script 条目承载。
+ * - name 不加前缀（用户自己起的名）；origin 为 'plugin:<文件名>'。
+ * - _config.yml 的 text_pipeline.plugins.<name> 可覆盖 enable / slot / priority，
+ *   其余键随整个子对象进 ctx.config（语义与 preset 子配置一致）；stage 不可覆盖。
+ *
+ * 热重载（与 script hook 同一套失效语义）：convert / replace / test / match
+ * 即改即用——每次执行重新 require 文件取新声明；stage / slot / priority / name /
+ * css / js / enabledByDefault 在注册期固化，改动需重启；目录增删文件同样需重启。
+ */
+function listPluginFiles(root) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (err) {
+    return null; // 目录不存在：零配置默认值不该制造噪音
+  }
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.js') && !entry.name.startsWith('_'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function freshPrecheckPasses(decl, content) {
+  if (typeof decl.test === 'function' && !decl.test(content)) return false;
+  if (decl.match !== undefined) {
+    const regex = decl.match instanceof RegExp ? decl.match : new RegExp(decl.match);
+    if (!regex.test(content)) return false;
+  }
+  return true;
+}
+
+function buildPluginNode(entry, { fileName, scriptPath, shortName, sub, placement }) {
+  return {
+    name: shortName,
+    stage: placement.stage,
+    slot: placement.slot,
+    priority: placement.priority,
+    origin: 'plugin:' + fileName,
+    scriptPath,
+    config: sub,
+    css: entry.css,
+    js: entry.js,
+    // 热重载入口：每次执行取文件的最新声明（test/match 预判也吃最新值），
+    // guard 跟随注册期固化的 stage——声明里改 stage 不会生效，必须重启。
+    convert(content, ctx) {
+      invalidateModuleTree(scriptPath);
+      const fresh = require(scriptPath);
+      const decl = Array.isArray(fresh) ? fresh.find((n) => n && n.name === shortName) : fresh;
+      if (!decl || typeof decl !== 'object') {
+        throw new Error('node "' + shortName + '" no longer found in ' + fileName + ' — restart hexo to re-discover plugins');
+      }
+      if (!freshPrecheckPasses(decl, content)) return content;
+      const converted = resolveConvert(Object.assign({}, decl, { stage: placement.stage }));
+      if (converted.error) {
+        throw new Error(converted.error);
+      }
+      return converted.convert(content, ctx);
+    }
+  };
+}
+
+function checkDanglingOverrides(pluginsOverrides, discoveredNames, issues) {
+  for (const key of Object.keys(pluginsOverrides || {})) {
+    if (!discoveredNames.includes(key)) {
+      issues.push({
+        level: 'warn',
+        message: 'text_pipeline.plugins.' + key + ' matches no discovered plugin' + suggest(key, discoveredNames)
+      });
+    }
+  }
+}
+
+function loadPluginDir(pluginsDir, pluginsOverrides, baseDir) {
+  const nodes = [];
+  const issues = [];
+  const root = path.resolve(baseDir || process.cwd(), pluginsDir);
+
+  const files = listPluginFiles(root);
+  if (!files) {
+    // 目录不存在本身不是问题（零配置默认值），但悬空的覆盖配置要告警
+    checkDanglingOverrides(pluginsOverrides, [], issues);
+    return { nodes, issues };
+  }
+
+  const discoveredNames = [];
+  for (const fileName of files) {
+    const scriptPath = path.join(root, fileName);
+    let exported;
+    try {
+      exported = require(scriptPath);
+    } catch (err) {
+      issues.push({
+        level: 'error',
+        message: 'plugin "' + fileName + '" failed to load: ' + (err && err.message) + ' (fix the file and restart hexo)'
+      });
+      continue;
+    }
+
+    if (typeof exported === 'function') {
+      issues.push({
+        level: 'error',
+        message:
+          'plugin "' + fileName + '" exports a function — plugin files export a node object; for a plain (text, ctx) => text transform use a hooks script entry instead'
+      });
+      continue;
+    }
+    if (!exported || typeof exported !== 'object') {
+      issues.push({
+        level: 'error',
+        message: 'plugin "' + fileName + '" must export a node object or an array of nodes'
+      });
+      continue;
+    }
+
+    const entries = Array.isArray(exported) ? exported : [exported];
+    entries.forEach((entry, index) => {
+      if (!entry || typeof entry !== 'object') {
+        issues.push({ level: 'error', message: 'plugin "' + fileName + '" node [' + index + '] must be an object' });
+        return;
+      }
+      const explicitName = typeof entry.name === 'string' && entry.name ? entry.name : '';
+      if (Array.isArray(exported) && !explicitName) {
+        issues.push({
+          level: 'error',
+          message: 'plugin "' + fileName + '" node [' + index + '] is missing a name (array exports must name every node)'
+        });
+        return;
+      }
+      const shortName = explicitName || path.basename(fileName, '.js');
+      discoveredNames.push(shortName);
+
+      const sub = nodeConfig(pluginsOverrides, shortName);
+      if (!isNodeEnabled(entry, sub)) return;
+
+      const placed = resolvePlacement(
+        {
+          stage: entry.stage,
+          slot: sub.slot !== undefined ? sub.slot : entry.slot,
+          priority: sub.priority !== undefined ? sub.priority : entry.priority
+        },
+        'plugin'
+      );
+      if (placed.error) {
+        issues.push({ level: 'error', message: 'plugin "' + fileName + '" node "' + shortName + '" has ' + placed.error });
+        return;
+      }
+      // 注册期预检 convert/replace 的合法性；编译结果丢弃，执行时按最新声明重新解析
+      const converted = resolveConvert(Object.assign({}, entry, { stage: placed.placement.stage }));
+      if (converted.error) {
+        issues.push({ level: 'error', message: 'plugin "' + fileName + '" node "' + shortName + '" ' + converted.error });
+        return;
+      }
+
+      nodes.push(buildPluginNode(entry, { fileName, scriptPath, shortName, sub, placement: placed.placement }));
+    });
+  }
+
+  checkDanglingOverrides(pluginsOverrides, discoveredNames, issues);
+
+  return { nodes, issues };
+}
+
+module.exports = { loadPluginDir, _internal: { listPluginFiles } };

package/lib/core/loaders/preset.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { normalizePresetEntry, nodeConfig, isNodeEnabled } = require('../config');
+const { resolvePlacement, resolveConvert } = require('../node-contract');
+
+/**
+ * preset loader —— "插件的插件"。一个 preset 是一组打包好的 node：
+ *
+ * module.exports = {
+ *   name: 'obsidian',
+ *   nodes: [ ...node对象（与统一契约同形，name 用短名）... ],
+ *   init(hexo) {}          // 可选：一次性副作用（如注册缓存失效 filter）
+ * };
+ *
+ * 配置：
+ * text_pipeline:
+ *   presets:
+ *     - obsidian                       # 内置（lib/presets/<name>）或 npm 包名
+ *     - ./pipeline/my-preset           # 站点本地目录/文件（相对 Hexo 根目录）
+ *     - name: obsidian                 # 完整形态：带 preset 级配置
+ *       config:
+ *         domain_prefix: ''
+ *         callout: { enable: true, priority: 15 }   # node 级覆盖：enable / slot / priority / 其他子配置
+ *
+ * node 的 enable 解析顺序：用户配置 > node.enabledByDefault > 默认开。
+ */
+function resolvePresetModule(name, baseDir) {
+  if (name.startsWith('.') || path.isAbsolute(name)) {
+    return require(path.resolve(baseDir || process.cwd(), name));
+  }
+  const builtIn = path.join(__dirname, '..', '..', 'presets', name);
+  if (fs.existsSync(builtIn) || fs.existsSync(builtIn + '.js')) {
+    return require(builtIn);
+  }
+  return require(name); // npm 包
+}
+
+function wrapPresetNode(node, presetName, presetConfig) {
+  const sub = nodeConfig(presetConfig, node.name);
+  // 用户配置覆盖 node 自带声明；默认值与校验和其他注册路径同一套（node-contract.js）
+  const resolved = resolvePlacement(
+    {
+      stage: node.stage,
+      slot: sub.slot !== undefined ? sub.slot : node.slot,
+      priority: sub.priority !== undefined ? sub.priority : node.priority
+    },
+    'preset'
+  );
+  if (resolved.error) {
+    return { error: 'preset node "' + presetName + ':' + node.name + '" has ' + resolved.error };
+  }
+  const converted = resolveConvert(node);
+  if (converted.error) {
+    return { error: 'preset node "' + presetName + ':' + node.name + '" ' + converted.error };
+  }
+  return {
+    node: Object.assign({}, node, {
+      name: presetName + ':' + node.name,
+      shortName: node.name,
+      origin: 'preset:' + presetName,
+      stage: resolved.placement.stage,
+      slot: resolved.placement.slot,
+      priority: resolved.placement.priority,
+      convert: converted.convert,
+      config: sub,
+      presetConfig
+    })
+  };
+}
+
+function loadPresets(rawPresets, baseDir) {
+  const nodes = [];
+  const inits = [];
+  const issues = [];
+
+  (rawPresets || []).forEach((rawEntry, index) => {
+    const entry = normalizePresetEntry(rawEntry);
+    if (!entry || !entry.name) {
+      issues.push({ level: 'error', message: 'presets[' + index + '] must be a name string or { name, config }' });
+      return;
+    }
+
+    let mod;
+    try {
+      mod = resolvePresetModule(entry.name, baseDir);
+    } catch (err) {
+      issues.push({
+        level: 'error',
+        message: 'preset "' + entry.name + '" failed to load: ' + (err && err.message)
+      });
+      return;
+    }
+
+    const presetName = (mod && mod.name) || entry.name;
+    const presetNodes = Array.isArray(mod) ? mod : mod && Array.isArray(mod.nodes) ? mod.nodes : null;
+    if (!presetNodes) {
+      issues.push({
+        level: 'error',
+        message: 'preset "' + entry.name + '" must export { nodes: [...] } or an array of nodes'
+      });
+      return;
+    }
+
+    for (const node of presetNodes) {
+      if (!node || typeof node.name !== 'string') {
+        issues.push({
+          level: 'error',
+          message: 'preset "' + presetName + '" contains an invalid node (need { name, stage, convert | replace })'
+        });
+        continue;
+      }
+      if (!isNodeEnabled(node, nodeConfig(entry.config, node.name))) continue;
+      const wrapped = wrapPresetNode(node, presetName, entry.config);
+      if (wrapped.error) {
+        issues.push({ level: 'error', message: wrapped.error });
+        continue;
+      }
+      nodes.push(wrapped.node);
+    }
+
+    if (mod && typeof mod.init === 'function') {
+      inits.push({ name: presetName, init: mod.init });
+    }
+  });
+
+  return { nodes, inits, issues };
+}
+
+module.exports = { loadPresets, _internal: { resolvePresetModule, wrapPresetNode } };

package/lib/core/loaders/script.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const path = require('node:path');
+
+/**
+ * script hook → node：本地 JS 文件，module.exports = (text, ctx) => text。
+ * 相对 Hexo 根目录解析；每次执行重新 require —— 即改即用，hexo server 下
+ * 改完脚本下一次渲染就生效，不用重启。
+ */
+function resolveScriptPath(scriptPath, baseDir) {
+  return path.resolve(baseDir || process.cwd(), scriptPath);
+}
+
+/**
+ * 精确失效脚本及其本地依赖树（不碰 node_modules）：
+ * 脚本 require 的辅助模块改了也要即改即用，但不能误伤无关缓存。
+ */
+function invalidateModuleTree(modulePath, seen = new Set()) {
+  const cached = require.cache[modulePath];
+  if (!cached || seen.has(modulePath)) return;
+  seen.add(modulePath);
+  for (const child of cached.children) {
+    if (!child.filename.includes(path.sep + 'node_modules' + path.sep)) {
+      invalidateModuleTree(child.filename, seen);
+    }
+  }
+  delete require.cache[modulePath];
+}
+
+function createScriptNode(hook, baseDir) {
+  const resolved = resolveScriptPath(hook.script, baseDir);
+  return {
+    name: 'hook:' + hook.name,
+    stage: hook.stage,
+    slot: hook.slot,
+    priority: hook.priority,
+    origin: 'hook:script',
+    scriptPath: resolved,
+    convert(content, ctx) {
+      invalidateModuleTree(resolved);
+      const fn = require(resolved);
+      if (typeof fn !== 'function') {
+        throw new Error('script must export a function (text, ctx) => text');
+      }
+      return fn(content, ctx);
+    }
+  };
+}
+
+module.exports = { createScriptNode, resolveScriptPath, invalidateModuleTree, _internal: { invalidateModuleTree } };

package/lib/core/markdown-guard.js

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * Markdown 阶段的代码保护工具：converter 在 before_post_render 做行内替换时，
+ * 用 replaceOutsideCode 包住 replacer，避免改写 fenced code / inline code 里的内容。
+ * HTML 阶段（after_post_render）不需要本模块——代码已渲染为 <pre>/<code>。
+ */
+/** 把单行拆成 { isCode, text } 片段序列，isCode 为 true 的片段是行内代码（含反引号）。 */
+function segmentInlineCode(line) {
+  const segments = [];
+  let cursor = 0;
+
+  while (cursor < line.length) {
+    const open = line.indexOf('`', cursor);
+    if (open === -1) {
+      segments.push({ isCode: false, text: line.slice(cursor) });
+      break;
+    }
+
+    if (open > cursor) {
+      segments.push({ isCode: false, text: line.slice(cursor, open) });
+    }
+
+    let ticks = 1;
+    while (open + ticks < line.length && line[open + ticks] === '`') {
+      ticks += 1;
+    }
+
+    const closingToken = '`'.repeat(ticks);
+    const close = line.indexOf(closingToken, open + ticks);
+    if (close === -1) {
+      segments.push({ isCode: false, text: line.slice(open) });
+      break;
+    }
+
+    segments.push({ isCode: true, text: line.slice(open, close + ticks) });
+    cursor = close + ticks;
+  }
+
+  return segments;
+}
+
+function replaceOutsideInlineCode(line, replacer) {
+  return segmentInlineCode(line)
+    .map((seg) => (seg.isCode ? seg.text : replacer(seg.text)))
+    .join('');
+}
+
+function replaceOutsideCode(content, replacer) {
+  const lines = content.split('\n');
+  let inFence = false;
+  let fenceChar = '';
+  let fenceLen = 0;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const match = line.match(/^ {0,3}([`~]{3,})/);
+
+    if (match) {
+      const token = match[1];
+      const marker = token[0];
+      const length = token.length;
+
+      if (!inFence) {
+        inFence = true;
+        fenceChar = marker;
+        fenceLen = length;
+      } else if (marker === fenceChar && length >= fenceLen) {
+        inFence = false;
+        fenceChar = '';
+        fenceLen = 0;
+      }
+
+      continue;
+    }
+
+    if (!inFence) {
+      lines[i] = replaceOutsideInlineCode(line, replacer);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  segmentInlineCode,
+  replaceOutsideInlineCode,
+  replaceOutsideCode
+};