@nebulaaa/auditor 0.0.0-stage → 1.0.0

package/dist/auditor.cjs

@@ -0,0 +1,405 @@
+'use strict';
+
+var dict = require('@nebulaaa/dict');
+var lru = require('@nebulaaa/lru');
+var plugin = require('@nebulaaa/plugin');
+
+/** AC 自动机 */
+class ACAutomaton {
+    constructor(ignoreCase = false) {
+        this._root = {
+            Children: new Map(),
+            Fail: null,
+            Words: [],
+            Output: [],
+        };
+        this._built = false;
+        this._interferenceWords = new Set();
+        this._ignoreCase = ignoreCase;
+    }
+    /**
+     * 大小写归一（仅 ASCII 字母，逐码点等长替换，保证匹配位置与原始文本索引一致）
+     */
+    normalize(text) {
+        if (!this._ignoreCase) {
+            return text;
+        }
+        let out = '';
+        for (const ch of text) {
+            const code = ch.codePointAt(0);
+            out += code >= 65 && code <= 90 ? String.fromCharCode(code + 32) : ch;
+        }
+        return out;
+    }
+    /**
+     * 添加敏感词
+     * @param word 敏感词
+     */
+    AddWord(word) {
+        if (!word || word.length === 0) {
+            return;
+        }
+        let current = this._root;
+        const chars = Array.from(this.normalize(word)); // 归一后分词(IgnoreCase 关闭时原样返回)
+        for (const char of chars) {
+            let child = current.Children.get(char);
+            if (!child) {
+                child = {
+                    Children: new Map(),
+                    Fail: null,
+                    Words: [],
+                    Output: [],
+                };
+                current.Children.set(char, child);
+            }
+            current = child;
+        }
+        if (!current.Words.includes(word)) {
+            // 同词重复添加幂等：自身词独立存放，output 由 build 重新生成
+            current.Words.push(word);
+        }
+        this._built = false; // 标记需要重新构建 fail 指针
+    }
+    /**
+     * 构建 fail 指针（使用 BFS）
+     */
+    Build() {
+        if (this._built) {
+            return;
+        }
+        const queue = [];
+        // 第一层节点的 fail 指针指向 root
+        for (const child of this._root.Children.values()) {
+            child.Fail = this._root;
+            child.Output = [...child.Words]; // 由自身词重新生成（fail 为 root，无合并项）
+            queue.push(child);
+        }
+        // BFS 构建 fail 指针（头指针索引出队：array.shift 为 O(n)，万级节点的大词库构建退化为 O(n²)）
+        let head = 0;
+        while (head < queue.length) {
+            const current = queue[head++];
+            for (const [char, child] of current.Children) {
+                queue.push(child);
+                // 查找 fail 指针
+                let fail = current.Fail;
+                while (fail && !fail.Children.has(char)) {
+                    fail = fail.Fail;
+                }
+                child.Fail = fail ? fail.Children.get(char) || this._root : this._root;
+                // 合并 output：由自身词重新生成（幂等，重复构建不再累积；fail 节点层级更浅、已先构建完成）
+                child.Output = [...child.Words, ...child.Fail.Output];
+            }
+        }
+        this._built = true;
+    }
+    /**
+     * 匹配文本，返回所有匹配结果
+     * @param text 待匹配的文本
+     * @returns 匹配结果列表
+     */
+    Match(text) {
+        if (!this._built) {
+            this.Build();
+        }
+        const results = [];
+        let current = this._root;
+        const chars = Array.from(this.normalize(text)); // 归一后分词(逐码点等长,位置索引不变)
+        // 记录匹配时的原始位置
+        for (let i = 0; i < chars.length; i++) {
+            const char = chars[i];
+            // 如果是干扰字符，跳过
+            if (this._interferenceWords.has(char)) {
+                continue;
+            }
+            // 沿着 fail 指针查找匹配的子节点
+            while (current !== this._root && !current.Children.has(char)) {
+                current = current.Fail;
+            }
+            if (current.Children.has(char)) {
+                current = current.Children.get(char);
+                // 输出所有匹配的敏感词
+                for (const word of current.Output) {
+                    // 计算在原始文本中的起始位置（跳过干扰字符）
+                    let j = i;
+                    // 从当前位置向前查找匹配的起始位置
+                    const wordChars = Array.from(this.normalize(word));
+                    let wordIndex = wordChars.length - 1;
+                    // 从后向前匹配，找到原始文本中的位置
+                    while (j >= 0 && wordIndex >= 0) {
+                        if (this._interferenceWords.has(chars[j])) {
+                            j--;
+                            continue;
+                        }
+                        if (chars[j] === wordChars[wordIndex]) {
+                            wordIndex--;
+                        }
+                        j--;
+                    }
+                    results.push({
+                        Word: word,
+                        Start: j + 1,
+                        End: i + 1,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * 检测文本是否包含敏感词
+     * @param text 待检测的文本
+     * @returns 是否包含敏感词
+     */
+    Test(text) {
+        if (!this._built) {
+            this.Build();
+        }
+        let current = this._root;
+        const chars = Array.from(this.normalize(text));
+        for (let i = 0; i < chars.length; i++) {
+            const char = chars[i];
+            // 如果是干扰字符，跳过
+            if (this._interferenceWords.has(char)) {
+                continue;
+            }
+            while (current !== this._root && !current.Children.has(char)) {
+                current = current.Fail;
+            }
+            if (current.Children.has(char)) {
+                current = current.Children.get(char);
+                if (current.Output.length > 0) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * 清空所有节点
+     */
+    Clear() {
+        this._root = {
+            Children: new Map(),
+            Fail: null,
+            Words: [],
+            Output: [],
+        };
+        this._built = false;
+    }
+    /**
+     * 注入干扰词（仅单字符生效：匹配按单字符查表）
+     * @param words 干扰词列表
+     */
+    AddInterferenceWords(words) {
+        for (const word of words) {
+            if (!word || word.length === 0) {
+                continue;
+            }
+            const chars = Array.from(this.normalize(word));
+            if (chars.length !== 1) {
+                // 多字符干扰词在按字符匹配的查表中永不命中——显式告警而非静默失效
+                console.warn(`addInterferenceWords: 干扰词须为单个字符，已忽略 "${word}"`);
+                continue;
+            }
+            this._interferenceWords.add(chars[0]);
+        }
+    }
+    /**
+     * 清空干扰词
+     */
+    ClearInterferenceWords() {
+        this._interferenceWords.clear();
+    }
+    /**
+     * 获取干扰词数量
+     */
+    GetInterferenceWordCount() {
+        return this._interferenceWords.size;
+    }
+}
+/**
+ * 敏感词审计员插件
+ */
+class AuditorPlugin extends plugin.Plugin {
+    constructor(deps, cfg) {
+        // 默认值填充必须在 super 之前：基类构造会冻结 cfg，冻结后 defineProperty 会抛错
+        dict.Override(cfg, {
+            Replacement: '█',
+            IgnoreCase: false,
+            CacheSize: 1000,
+        });
+        super(deps, cfg);
+        this._acAutomaton = new ACAutomaton(cfg.IgnoreCase);
+        this._sensitiveWords = new Set();
+        this._acAutomaton.AddInterferenceWords(' \t\r\n'.split(''));
+        if (cfg.EnableCache) {
+            // 缓存容量须为正整数：非法配置构造期显式失败，错误信息带插件上下文便于定位
+            if (!Number.isInteger(cfg.CacheSize) || cfg.CacheSize <= 0) {
+                throw new Error(`AuditorPlugin CacheSize 须为正整数 >>> ${cfg.CacheSize}`);
+            }
+            this._testCache = new lru.LRU(cfg.CacheSize);
+            this._findCache = new lru.LRU(cfg.CacheSize);
+            this._replaceCache = new lru.LRU(cfg.CacheSize);
+        }
+        else {
+            this._testCache = null;
+            this._findCache = null;
+            this._replaceCache = null;
+        }
+        // 构建敏感词自动机
+        this.buildAutomaton();
+    }
+    Test(text) {
+        if (!text || text.length === 0) {
+            return false;
+        }
+        // 检查缓存
+        if (this._testCache) {
+            const cached = this._testCache.Get(text);
+            if (cached !== null) {
+                return cached;
+            }
+        }
+        const result = this._acAutomaton.Test(text);
+        // 更新缓存
+        if (this._testCache) {
+            this._testCache.Set(text, result);
+        }
+        return result;
+    }
+    Find(text) {
+        if (!text || text.length === 0) {
+            return { Matched: false, Words: [], Matches: [] };
+        }
+        // 检查缓存
+        if (this._findCache) {
+            const cached = this._findCache.Get(text);
+            if (cached !== null) {
+                // 返回浅拷贝，防止外部修改影响缓存
+                return {
+                    Matched: cached.Matched,
+                    Words: [...cached.Words],
+                    Matches: cached.Matches.map((m) => (Object.assign({}, m))),
+                };
+            }
+        }
+        // 匹配文本，自动跳过干扰词
+        const matches = this._acAutomaton.Match(text);
+        // 去重敏感词
+        const wordSet = new Set();
+        for (const match of matches) {
+            wordSet.add(match.Word);
+        }
+        const result = {
+            Matched: matches.length > 0,
+            Words: Array.from(wordSet),
+            Matches: matches,
+        };
+        // 更新缓存（存储副本，防止后续修改影响缓存）
+        if (this._findCache) {
+            this._findCache.Set(text, {
+                Matched: result.Matched,
+                Words: [...result.Words],
+                Matches: result.Matches.map((m) => (Object.assign({}, m))),
+            });
+        }
+        return result;
+    }
+    Replace(text, replacement) {
+        var _a;
+        if (!text || text.length === 0) {
+            return text;
+        }
+        // 检查缓存（JSON 编码组合键：字符串拼接的 "_" 分隔符可出现在 text/replacement 中造成碰撞）
+        const cacheKey = JSON.stringify([text, replacement !== null && replacement !== void 0 ? replacement : this.Cfg.Replacement]);
+        if (this._replaceCache) {
+            const cached = this._replaceCache.Get(cacheKey);
+            if (cached !== null) {
+                return cached;
+            }
+        }
+        const result = this.Find(text);
+        if (!result.Matched) {
+            // 干净文本是最高频流量，同样入缓存（组合键已防碰撞），避免反复全量匹配
+            (_a = this._replaceCache) === null || _a === void 0 ? void 0 : _a.Set(cacheKey, text);
+            return text;
+        }
+        // 在码点数组上操作：matches 的位置基于 Array.from 分词（码点索引），
+        // 直接对原字符串 slice 会因代理对（emoji 等）长度不一致而切错位置
+        const chars = Array.from(text);
+        // 合并重叠区间：重叠匹配若逐个替换，从后向前切片会互相错位（吞字或残留敏感片段）
+        const sorted = [...result.Matches].sort((a, b) => a.Start - b.Start);
+        const ranges = [];
+        for (const match of sorted) {
+            const last = ranges[ranges.length - 1];
+            if (last && match.Start < last.end) {
+                last.end = Math.max(last.end, match.End); // 重叠：并入上一区间
+            }
+            else {
+                ranges.push({ start: match.Start, end: match.End });
+            }
+        }
+        // 每个合并区间整体替换为一个 replacement 串（非逐字符屏蔽）；空串为合法替换值（删除敏感词）
+        const replaceChar = replacement !== null && replacement !== void 0 ? replacement : this.Cfg.Replacement;
+        for (let i = ranges.length - 1; i >= 0; i--) {
+            const { start, end } = ranges[i];
+            chars.splice(start, end - start, replaceChar); // 从后向前，前面的索引不受影响
+        }
+        const replacedText = chars.join('');
+        // 更新缓存
+        if (this._replaceCache) {
+            this._replaceCache.Set(cacheKey, replacedText);
+        }
+        return replacedText;
+    }
+    InjectSensitiveWords(words) {
+        for (const word of words) {
+            if (word && word.length > 0) {
+                this._sensitiveWords.add(word);
+            }
+        }
+        this.buildAutomaton();
+        this.clearCache();
+    }
+    InjectInterferenceWords(words) {
+        this._acAutomaton.AddInterferenceWords(words);
+        this.clearCache();
+    }
+    GetSensitiveWordCount() {
+        return this._sensitiveWords.size;
+    }
+    GetInterferenceWordCount() {
+        return this._acAutomaton.GetInterferenceWordCount();
+    }
+    ClearSensitiveWords() {
+        this._sensitiveWords.clear();
+        this.buildAutomaton();
+        this.clearCache();
+    }
+    ClearInterferenceWords() {
+        this._acAutomaton.ClearInterferenceWords();
+        this.clearCache();
+    }
+    /**
+     * 构建 AC 自动机
+     */
+    buildAutomaton() {
+        this._acAutomaton.Clear();
+        const words = this._sensitiveWords;
+        for (const word of words) {
+            this._acAutomaton.AddWord(word);
+        }
+        this._acAutomaton.Build();
+    }
+    /**
+     * 清空缓存
+     */
+    clearCache() {
+        var _a, _b, _c;
+        (_a = this._testCache) === null || _a === void 0 ? void 0 : _a.Clear();
+        (_b = this._findCache) === null || _b === void 0 ? void 0 : _b.Clear();
+        (_c = this._replaceCache) === null || _c === void 0 ? void 0 : _c.Clear();
+    }
+}
+
+exports.AuditorPlugin = AuditorPlugin;

package/dist/auditor.d.ts

@@ -0,0 +1,155 @@
+import { PluginCfg, PluginDeps, IPlugin, Plugin } from '@nebulaaa/plugin';
+
+/** 敏感词审计员插件依赖 */
+interface AuditorDeps extends PluginDeps {
+}
+/** 敏感词审计员插件配置 */
+interface AuditorCfg extends PluginCfg {
+    /**
+     * 敏感词替换字符
+     * @default '█'
+     */
+    readonly Replacement?: string;
+    /**
+     * 是否启用缓存
+     * @default true
+     */
+    readonly EnableCache?: boolean;
+    /**
+     * 缓存大小
+     * @default 1000
+     * @tip 须为正整数，非法值构造期显式报错
+     */
+    readonly CacheSize?: number;
+    /**
+     * 是否忽略大小写
+     * @default false
+     * @tip 仅归一 ASCII 字母（A-Z↔a-z），逐码点等长替换不影响位置索引；
+     *      全角字母/数字等全半角变体不归一
+     */
+    readonly IgnoreCase?: boolean;
+}
+/** 匹配位置信息 */
+interface IAuditorMatchPosition {
+    /** 匹配到的敏感词 */
+    Word: string;
+    /** 起始位置（字符索引） */
+    Start: number;
+    /** 结束位置（字符索引，不包含） */
+    End: number;
+}
+/** 匹配结果 */
+interface IAuditorMatchResult {
+    /** 是否匹配到敏感词 */
+    Matched: boolean;
+    /** 匹配到的敏感词列表（去重，按首次出现顺序） */
+    Words: string[];
+    /** 所有匹配位置信息 */
+    Matches: IAuditorMatchPosition[];
+}
+/** AC 自动机节点接口 */
+interface IACNode {
+    /** 子节点映射 */
+    Children: Map<string, IACNode>;
+    /** 失败指针 */
+    Fail: IACNode | null;
+    /** 该节点自身的完整敏感词（词尾节点非空） */
+    Words: string[];
+    /** 匹配输出（自身词 + fail 链词，构建时由 words 重新生成） */
+    Output: string[];
+}
+/** AC 自动机匹配结果 */
+interface IACMatchResult {
+    /** 匹配到的敏感词 */
+    Word: string;
+    /** 起始位置 */
+    Start: number;
+    /** 结束位置 */
+    End: number;
+}
+/** 敏感词审计员插件接口 */
+interface IAuditorPlugin extends IPlugin<AuditorDeps, AuditorCfg> {
+    /**
+     * 检测文本是否包含敏感词
+     * @param text 待检测的文本
+     * @returns 是否包含敏感词
+     */
+    Test(text: string): boolean;
+    /**
+     * 查找文本中的所有敏感词
+     * @param text 待查找的文本
+     * @returns 匹配结果
+     */
+    Find(text: string): IAuditorMatchResult;
+    /**
+     * 替换文本中的敏感词
+     *
+     * - 每个匹配区间（重叠匹配先合并为不重叠区间）整体替换为一个
+     *   replacement 串（非逐字符屏蔽）
+     * - 区间内的干扰字符一并被替换（变体表达整体屏蔽）
+     * @param text 待替换的文本
+     * @param replacement 替换串，缺省使用配置的替换字符；传空串为删除敏感词语义
+     * @returns 替换后的文本
+     */
+    Replace(text: string, replacement?: string): string;
+    /**
+     * 注入敏感词
+     * @param words 敏感词列表
+     */
+    InjectSensitiveWords(words: string[]): void;
+    /**
+     * 注入干扰词
+     *
+     * - 干扰词在匹配时被跳过（如 "敏 感 词" 仍命中），仅单字符
+     *   生效，多字符词将被忽略并告警
+     * - 敏感词本身包含干扰字符时该词将无法命中，注入时须避开词库字符
+     * @param words 干扰词列表
+     */
+    InjectInterferenceWords(words: string[]): void;
+    /**
+     * 获取当前敏感词数量
+     * @returns 敏感词数量
+     */
+    GetSensitiveWordCount(): number;
+    /**
+     * 获取当前干扰词数量
+     * @returns 干扰词数量
+     */
+    GetInterferenceWordCount(): number;
+    /** 清空所有敏感词 */
+    ClearSensitiveWords(): void;
+    /** 清空所有干扰词 */
+    ClearInterferenceWords(): void;
+}
+
+/**
+ * 敏感词审计员插件
+ */
+declare class AuditorPlugin extends Plugin<AuditorDeps, AuditorCfg> implements IAuditorPlugin {
+    private _acAutomaton;
+    private _testCache;
+    private _findCache;
+    private _replaceCache;
+    private _sensitiveWords;
+    constructor(deps: AuditorDeps, cfg: AuditorCfg);
+    Test(text: string): boolean;
+    Find(text: string): IAuditorMatchResult;
+    Replace(text: string, replacement?: string): string;
+    InjectSensitiveWords(words: string[]): void;
+    InjectInterferenceWords(words: string[]): void;
+    GetSensitiveWordCount(): number;
+    GetInterferenceWordCount(): number;
+    ClearSensitiveWords(): void;
+    ClearInterferenceWords(): void;
+    /**
+     * 构建 AC 自动机
+     */
+    private buildAutomaton;
+    /**
+     * 清空缓存
+     */
+    private clearCache;
+}
+
+export { AuditorPlugin };
+export type { AuditorCfg, AuditorDeps, IACMatchResult, IACNode, IAuditorMatchPosition, IAuditorMatchResult, IAuditorPlugin };

package/dist/auditor.min.cjs

@@ -0,0 +1 @@
+"use strict";var t=require("@nebulaaa/dict"),e=require("@nebulaaa/lru"),r=require("@nebulaaa/plugin");class n{constructor(t=!1){this._root={Children:new Map,Fail:null,Words:[],Output:[]},this._built=!1,this._interferenceWords=new Set,this._ignoreCase=t}normalize(t){if(!this._ignoreCase)return t;let e="";for(const r of t){const t=r.codePointAt(0);e+=t>=65&&t<=90?String.fromCharCode(t+32):r}return e}AddWord(t){if(!t||0===t.length)return;let e=this._root;const r=Array.from(this.normalize(t));for(const t of r){let r=e.Children.get(t);r||(r={Children:new Map,Fail:null,Words:[],Output:[]},e.Children.set(t,r)),e=r}e.Words.includes(t)||e.Words.push(t),this._built=!1}Build(){if(this._built)return;const t=[];for(const e of this._root.Children.values())e.Fail=this._root,e.Output=[...e.Words],t.push(e);let e=0;for(;e<t.length;){const r=t[e++];for(const[e,n]of r.Children){t.push(n);let s=r.Fail;for(;s&&!s.Children.has(e);)s=s.Fail;n.Fail=s&&s.Children.get(e)||this._root,n.Output=[...n.Words,...n.Fail.Output]}}this._built=!0}Match(t){this._built||this.Build();const e=[];let r=this._root;const n=Array.from(this.normalize(t));for(let t=0;t<n.length;t++){const s=n[t];if(!this._interferenceWords.has(s)){for(;r!==this._root&&!r.Children.has(s);)r=r.Fail;if(r.Children.has(s)){r=r.Children.get(s);for(const s of r.Output){let r=t;const i=Array.from(this.normalize(s));let o=i.length-1;for(;r>=0&&o>=0;)this._interferenceWords.has(n[r])||n[r]===i[o]&&o--,r--;e.push({Word:s,Start:r+1,End:t+1})}}}}return e}Test(t){this._built||this.Build();let e=this._root;const r=Array.from(this.normalize(t));for(let t=0;t<r.length;t++){const n=r[t];if(!this._interferenceWords.has(n)){for(;e!==this._root&&!e.Children.has(n);)e=e.Fail;if(e.Children.has(n)&&(e=e.Children.get(n),e.Output.length>0))return!0}}return!1}Clear(){this._root={Children:new Map,Fail:null,Words:[],Output:[]},this._built=!1}AddInterferenceWords(t){for(const e of t){if(!e||0===e.length)continue;const t=Array.from(this.normalize(e));1===t.length?this._interferenceWords.add(t[0]):console.warn(`addInterferenceWords: 干扰词须为单个字符，已忽略 "${e}"`)}}ClearInterferenceWords(){this._interferenceWords.clear()}GetInterferenceWordCount(){return this._interferenceWords.size}}class s extends r.Plugin{constructor(r,s){if(t.Override(s,{Replacement:"█",IgnoreCase:!1,CacheSize:1e3}),super(r,s),this._acAutomaton=new n(s.IgnoreCase),this._sensitiveWords=new Set,this._acAutomaton.AddInterferenceWords(" \t\r\n".split("")),s.EnableCache){if(!Number.isInteger(s.CacheSize)||s.CacheSize<=0)throw new Error(`AuditorPlugin CacheSize 须为正整数 >>> ${s.CacheSize}`);this._testCache=new e.LRU(s.CacheSize),this._findCache=new e.LRU(s.CacheSize),this._replaceCache=new e.LRU(s.CacheSize)}else this._testCache=null,this._findCache=null,this._replaceCache=null;this.buildAutomaton()}Test(t){if(!t||0===t.length)return!1;if(this._testCache){const e=this._testCache.Get(t);if(null!==e)return e}const e=this._acAutomaton.Test(t);return this._testCache&&this._testCache.Set(t,e),e}Find(t){if(!t||0===t.length)return{Matched:!1,Words:[],Matches:[]};if(this._findCache){const e=this._findCache.Get(t);if(null!==e)return{Matched:e.Matched,Words:[...e.Words],Matches:e.Matches.map(t=>Object.assign({},t))}}const e=this._acAutomaton.Match(t),r=new Set;for(const t of e)r.add(t.Word);const n={Matched:e.length>0,Words:Array.from(r),Matches:e};return this._findCache&&this._findCache.Set(t,{Matched:n.Matched,Words:[...n.Words],Matches:n.Matches.map(t=>Object.assign({},t))}),n}Replace(t,e){var r;if(!t||0===t.length)return t;const n=JSON.stringify([t,null!=e?e:this.Cfg.Replacement]);if(this._replaceCache){const t=this._replaceCache.Get(n);if(null!==t)return t}const s=this.Find(t);if(!s.Matched)return null===(r=this._replaceCache)||void 0===r||r.Set(n,t),t;const i=Array.from(t),o=[...s.Matches].sort((t,e)=>t.Start-e.Start),h=[];for(const t of o){const e=h[h.length-1];e&&t.Start<e.end?e.end=Math.max(e.end,t.End):h.push({start:t.Start,end:t.End})}const a=null!=e?e:this.Cfg.Replacement;for(let t=h.length-1;t>=0;t--){const{start:e,end:r}=h[t];i.splice(e,r-e,a)}const c=i.join("");return this._replaceCache&&this._replaceCache.Set(n,c),c}InjectSensitiveWords(t){for(const e of t)e&&e.length>0&&this._sensitiveWords.add(e);this.buildAutomaton(),this.clearCache()}InjectInterferenceWords(t){this._acAutomaton.AddInterferenceWords(t),this.clearCache()}GetSensitiveWordCount(){return this._sensitiveWords.size}GetInterferenceWordCount(){return this._acAutomaton.GetInterferenceWordCount()}ClearSensitiveWords(){this._sensitiveWords.clear(),this.buildAutomaton(),this.clearCache()}ClearInterferenceWords(){this._acAutomaton.ClearInterferenceWords(),this.clearCache()}buildAutomaton(){this._acAutomaton.Clear();const t=this._sensitiveWords;for(const e of t)this._acAutomaton.AddWord(e);this._acAutomaton.Build()}clearCache(){var t,e,r;null===(t=this._testCache)||void 0===t||t.Clear(),null===(e=this._findCache)||void 0===e||e.Clear(),null===(r=this._replaceCache)||void 0===r||r.Clear()}}exports.AuditorPlugin=s;

package/dist/auditor.min.mjs

@@ -0,0 +1 @@
+import{Override as t}from"@nebulaaa/dict";import{LRU as e}from"@nebulaaa/lru";import{Plugin as r}from"@nebulaaa/plugin";class n{constructor(t=!1){this._root={Children:new Map,Fail:null,Words:[],Output:[]},this._built=!1,this._interferenceWords=new Set,this._ignoreCase=t}normalize(t){if(!this._ignoreCase)return t;let e="";for(const r of t){const t=r.codePointAt(0);e+=t>=65&&t<=90?String.fromCharCode(t+32):r}return e}AddWord(t){if(!t||0===t.length)return;let e=this._root;const r=Array.from(this.normalize(t));for(const t of r){let r=e.Children.get(t);r||(r={Children:new Map,Fail:null,Words:[],Output:[]},e.Children.set(t,r)),e=r}e.Words.includes(t)||e.Words.push(t),this._built=!1}Build(){if(this._built)return;const t=[];for(const e of this._root.Children.values())e.Fail=this._root,e.Output=[...e.Words],t.push(e);let e=0;for(;e<t.length;){const r=t[e++];for(const[e,n]of r.Children){t.push(n);let s=r.Fail;for(;s&&!s.Children.has(e);)s=s.Fail;n.Fail=s&&s.Children.get(e)||this._root,n.Output=[...n.Words,...n.Fail.Output]}}this._built=!0}Match(t){this._built||this.Build();const e=[];let r=this._root;const n=Array.from(this.normalize(t));for(let t=0;t<n.length;t++){const s=n[t];if(!this._interferenceWords.has(s)){for(;r!==this._root&&!r.Children.has(s);)r=r.Fail;if(r.Children.has(s)){r=r.Children.get(s);for(const s of r.Output){let r=t;const i=Array.from(this.normalize(s));let o=i.length-1;for(;r>=0&&o>=0;)this._interferenceWords.has(n[r])||n[r]===i[o]&&o--,r--;e.push({Word:s,Start:r+1,End:t+1})}}}}return e}Test(t){this._built||this.Build();let e=this._root;const r=Array.from(this.normalize(t));for(let t=0;t<r.length;t++){const n=r[t];if(!this._interferenceWords.has(n)){for(;e!==this._root&&!e.Children.has(n);)e=e.Fail;if(e.Children.has(n)&&(e=e.Children.get(n),e.Output.length>0))return!0}}return!1}Clear(){this._root={Children:new Map,Fail:null,Words:[],Output:[]},this._built=!1}AddInterferenceWords(t){for(const e of t){if(!e||0===e.length)continue;const t=Array.from(this.normalize(e));1===t.length?this._interferenceWords.add(t[0]):console.warn(`addInterferenceWords: 干扰词须为单个字符，已忽略 "${e}"`)}}ClearInterferenceWords(){this._interferenceWords.clear()}GetInterferenceWordCount(){return this._interferenceWords.size}}class s extends r{constructor(r,s){if(t(s,{Replacement:"█",IgnoreCase:!1,CacheSize:1e3}),super(r,s),this._acAutomaton=new n(s.IgnoreCase),this._sensitiveWords=new Set,this._acAutomaton.AddInterferenceWords(" \t\r\n".split("")),s.EnableCache){if(!Number.isInteger(s.CacheSize)||s.CacheSize<=0)throw new Error(`AuditorPlugin CacheSize 须为正整数 >>> ${s.CacheSize}`);this._testCache=new e(s.CacheSize),this._findCache=new e(s.CacheSize),this._replaceCache=new e(s.CacheSize)}else this._testCache=null,this._findCache=null,this._replaceCache=null;this.buildAutomaton()}Test(t){if(!t||0===t.length)return!1;if(this._testCache){const e=this._testCache.Get(t);if(null!==e)return e}const e=this._acAutomaton.Test(t);return this._testCache&&this._testCache.Set(t,e),e}Find(t){if(!t||0===t.length)return{Matched:!1,Words:[],Matches:[]};if(this._findCache){const e=this._findCache.Get(t);if(null!==e)return{Matched:e.Matched,Words:[...e.Words],Matches:e.Matches.map(t=>Object.assign({},t))}}const e=this._acAutomaton.Match(t),r=new Set;for(const t of e)r.add(t.Word);const n={Matched:e.length>0,Words:Array.from(r),Matches:e};return this._findCache&&this._findCache.Set(t,{Matched:n.Matched,Words:[...n.Words],Matches:n.Matches.map(t=>Object.assign({},t))}),n}Replace(t,e){var r;if(!t||0===t.length)return t;const n=JSON.stringify([t,null!=e?e:this.Cfg.Replacement]);if(this._replaceCache){const t=this._replaceCache.Get(n);if(null!==t)return t}const s=this.Find(t);if(!s.Matched)return null===(r=this._replaceCache)||void 0===r||r.Set(n,t),t;const i=Array.from(t),o=[...s.Matches].sort((t,e)=>t.Start-e.Start),h=[];for(const t of o){const e=h[h.length-1];e&&t.Start<e.end?e.end=Math.max(e.end,t.End):h.push({start:t.Start,end:t.End})}const a=null!=e?e:this.Cfg.Replacement;for(let t=h.length-1;t>=0;t--){const{start:e,end:r}=h[t];i.splice(e,r-e,a)}const c=i.join("");return this._replaceCache&&this._replaceCache.Set(n,c),c}InjectSensitiveWords(t){for(const e of t)e&&e.length>0&&this._sensitiveWords.add(e);this.buildAutomaton(),this.clearCache()}InjectInterferenceWords(t){this._acAutomaton.AddInterferenceWords(t),this.clearCache()}GetSensitiveWordCount(){return this._sensitiveWords.size}GetInterferenceWordCount(){return this._acAutomaton.GetInterferenceWordCount()}ClearSensitiveWords(){this._sensitiveWords.clear(),this.buildAutomaton(),this.clearCache()}ClearInterferenceWords(){this._acAutomaton.ClearInterferenceWords(),this.clearCache()}buildAutomaton(){this._acAutomaton.Clear();const t=this._sensitiveWords;for(const e of t)this._acAutomaton.AddWord(e);this._acAutomaton.Build()}clearCache(){var t,e,r;null===(t=this._testCache)||void 0===t||t.Clear(),null===(e=this._findCache)||void 0===e||e.Clear(),null===(r=this._replaceCache)||void 0===r||r.Clear()}}export{s as AuditorPlugin};

package/dist/auditor.mjs

@@ -0,0 +1,403 @@
+import { Override } from '@nebulaaa/dict';
+import { LRU } from '@nebulaaa/lru';
+import { Plugin } from '@nebulaaa/plugin';
+
+/** AC 自动机 */
+class ACAutomaton {
+    constructor(ignoreCase = false) {
+        this._root = {
+            Children: new Map(),
+            Fail: null,
+            Words: [],
+            Output: [],
+        };
+        this._built = false;
+        this._interferenceWords = new Set();
+        this._ignoreCase = ignoreCase;
+    }
+    /**
+     * 大小写归一（仅 ASCII 字母，逐码点等长替换，保证匹配位置与原始文本索引一致）
+     */
+    normalize(text) {
+        if (!this._ignoreCase) {
+            return text;
+        }
+        let out = '';
+        for (const ch of text) {
+            const code = ch.codePointAt(0);
+            out += code >= 65 && code <= 90 ? String.fromCharCode(code + 32) : ch;
+        }
+        return out;
+    }
+    /**
+     * 添加敏感词
+     * @param word 敏感词
+     */
+    AddWord(word) {
+        if (!word || word.length === 0) {
+            return;
+        }
+        let current = this._root;
+        const chars = Array.from(this.normalize(word)); // 归一后分词(IgnoreCase 关闭时原样返回)
+        for (const char of chars) {
+            let child = current.Children.get(char);
+            if (!child) {
+                child = {
+                    Children: new Map(),
+                    Fail: null,
+                    Words: [],
+                    Output: [],
+                };
+                current.Children.set(char, child);
+            }
+            current = child;
+        }
+        if (!current.Words.includes(word)) {
+            // 同词重复添加幂等：自身词独立存放，output 由 build 重新生成
+            current.Words.push(word);
+        }
+        this._built = false; // 标记需要重新构建 fail 指针
+    }
+    /**
+     * 构建 fail 指针（使用 BFS）
+     */
+    Build() {
+        if (this._built) {
+            return;
+        }
+        const queue = [];
+        // 第一层节点的 fail 指针指向 root
+        for (const child of this._root.Children.values()) {
+            child.Fail = this._root;
+            child.Output = [...child.Words]; // 由自身词重新生成（fail 为 root，无合并项）
+            queue.push(child);
+        }
+        // BFS 构建 fail 指针（头指针索引出队：array.shift 为 O(n)，万级节点的大词库构建退化为 O(n²)）
+        let head = 0;
+        while (head < queue.length) {
+            const current = queue[head++];
+            for (const [char, child] of current.Children) {
+                queue.push(child);
+                // 查找 fail 指针
+                let fail = current.Fail;
+                while (fail && !fail.Children.has(char)) {
+                    fail = fail.Fail;
+                }
+                child.Fail = fail ? fail.Children.get(char) || this._root : this._root;
+                // 合并 output：由自身词重新生成（幂等，重复构建不再累积；fail 节点层级更浅、已先构建完成）
+                child.Output = [...child.Words, ...child.Fail.Output];
+            }
+        }
+        this._built = true;
+    }
+    /**
+     * 匹配文本，返回所有匹配结果
+     * @param text 待匹配的文本
+     * @returns 匹配结果列表
+     */
+    Match(text) {
+        if (!this._built) {
+            this.Build();
+        }
+        const results = [];
+        let current = this._root;
+        const chars = Array.from(this.normalize(text)); // 归一后分词(逐码点等长,位置索引不变)
+        // 记录匹配时的原始位置
+        for (let i = 0; i < chars.length; i++) {
+            const char = chars[i];
+            // 如果是干扰字符，跳过
+            if (this._interferenceWords.has(char)) {
+                continue;
+            }
+            // 沿着 fail 指针查找匹配的子节点
+            while (current !== this._root && !current.Children.has(char)) {
+                current = current.Fail;
+            }
+            if (current.Children.has(char)) {
+                current = current.Children.get(char);
+                // 输出所有匹配的敏感词
+                for (const word of current.Output) {
+                    // 计算在原始文本中的起始位置（跳过干扰字符）
+                    let j = i;
+                    // 从当前位置向前查找匹配的起始位置
+                    const wordChars = Array.from(this.normalize(word));
+                    let wordIndex = wordChars.length - 1;
+                    // 从后向前匹配，找到原始文本中的位置
+                    while (j >= 0 && wordIndex >= 0) {
+                        if (this._interferenceWords.has(chars[j])) {
+                            j--;
+                            continue;
+                        }
+                        if (chars[j] === wordChars[wordIndex]) {
+                            wordIndex--;
+                        }
+                        j--;
+                    }
+                    results.push({
+                        Word: word,
+                        Start: j + 1,
+                        End: i + 1,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * 检测文本是否包含敏感词
+     * @param text 待检测的文本
+     * @returns 是否包含敏感词
+     */
+    Test(text) {
+        if (!this._built) {
+            this.Build();
+        }
+        let current = this._root;
+        const chars = Array.from(this.normalize(text));
+        for (let i = 0; i < chars.length; i++) {
+            const char = chars[i];
+            // 如果是干扰字符，跳过
+            if (this._interferenceWords.has(char)) {
+                continue;
+            }
+            while (current !== this._root && !current.Children.has(char)) {
+                current = current.Fail;
+            }
+            if (current.Children.has(char)) {
+                current = current.Children.get(char);
+                if (current.Output.length > 0) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * 清空所有节点
+     */
+    Clear() {
+        this._root = {
+            Children: new Map(),
+            Fail: null,
+            Words: [],
+            Output: [],
+        };
+        this._built = false;
+    }
+    /**
+     * 注入干扰词（仅单字符生效：匹配按单字符查表）
+     * @param words 干扰词列表
+     */
+    AddInterferenceWords(words) {
+        for (const word of words) {
+            if (!word || word.length === 0) {
+                continue;
+            }
+            const chars = Array.from(this.normalize(word));
+            if (chars.length !== 1) {
+                // 多字符干扰词在按字符匹配的查表中永不命中——显式告警而非静默失效
+                console.warn(`addInterferenceWords: 干扰词须为单个字符，已忽略 "${word}"`);
+                continue;
+            }
+            this._interferenceWords.add(chars[0]);
+        }
+    }
+    /**
+     * 清空干扰词
+     */
+    ClearInterferenceWords() {
+        this._interferenceWords.clear();
+    }
+    /**
+     * 获取干扰词数量
+     */
+    GetInterferenceWordCount() {
+        return this._interferenceWords.size;
+    }
+}
+/**
+ * 敏感词审计员插件
+ */
+class AuditorPlugin extends Plugin {
+    constructor(deps, cfg) {
+        // 默认值填充必须在 super 之前：基类构造会冻结 cfg，冻结后 defineProperty 会抛错
+        Override(cfg, {
+            Replacement: '█',
+            IgnoreCase: false,
+            CacheSize: 1000,
+        });
+        super(deps, cfg);
+        this._acAutomaton = new ACAutomaton(cfg.IgnoreCase);
+        this._sensitiveWords = new Set();
+        this._acAutomaton.AddInterferenceWords(' \t\r\n'.split(''));
+        if (cfg.EnableCache) {
+            // 缓存容量须为正整数：非法配置构造期显式失败，错误信息带插件上下文便于定位
+            if (!Number.isInteger(cfg.CacheSize) || cfg.CacheSize <= 0) {
+                throw new Error(`AuditorPlugin CacheSize 须为正整数 >>> ${cfg.CacheSize}`);
+            }
+            this._testCache = new LRU(cfg.CacheSize);
+            this._findCache = new LRU(cfg.CacheSize);
+            this._replaceCache = new LRU(cfg.CacheSize);
+        }
+        else {
+            this._testCache = null;
+            this._findCache = null;
+            this._replaceCache = null;
+        }
+        // 构建敏感词自动机
+        this.buildAutomaton();
+    }
+    Test(text) {
+        if (!text || text.length === 0) {
+            return false;
+        }
+        // 检查缓存
+        if (this._testCache) {
+            const cached = this._testCache.Get(text);
+            if (cached !== null) {
+                return cached;
+            }
+        }
+        const result = this._acAutomaton.Test(text);
+        // 更新缓存
+        if (this._testCache) {
+            this._testCache.Set(text, result);
+        }
+        return result;
+    }
+    Find(text) {
+        if (!text || text.length === 0) {
+            return { Matched: false, Words: [], Matches: [] };
+        }
+        // 检查缓存
+        if (this._findCache) {
+            const cached = this._findCache.Get(text);
+            if (cached !== null) {
+                // 返回浅拷贝，防止外部修改影响缓存
+                return {
+                    Matched: cached.Matched,
+                    Words: [...cached.Words],
+                    Matches: cached.Matches.map((m) => (Object.assign({}, m))),
+                };
+            }
+        }
+        // 匹配文本，自动跳过干扰词
+        const matches = this._acAutomaton.Match(text);
+        // 去重敏感词
+        const wordSet = new Set();
+        for (const match of matches) {
+            wordSet.add(match.Word);
+        }
+        const result = {
+            Matched: matches.length > 0,
+            Words: Array.from(wordSet),
+            Matches: matches,
+        };
+        // 更新缓存（存储副本，防止后续修改影响缓存）
+        if (this._findCache) {
+            this._findCache.Set(text, {
+                Matched: result.Matched,
+                Words: [...result.Words],
+                Matches: result.Matches.map((m) => (Object.assign({}, m))),
+            });
+        }
+        return result;
+    }
+    Replace(text, replacement) {
+        var _a;
+        if (!text || text.length === 0) {
+            return text;
+        }
+        // 检查缓存（JSON 编码组合键：字符串拼接的 "_" 分隔符可出现在 text/replacement 中造成碰撞）
+        const cacheKey = JSON.stringify([text, replacement !== null && replacement !== void 0 ? replacement : this.Cfg.Replacement]);
+        if (this._replaceCache) {
+            const cached = this._replaceCache.Get(cacheKey);
+            if (cached !== null) {
+                return cached;
+            }
+        }
+        const result = this.Find(text);
+        if (!result.Matched) {
+            // 干净文本是最高频流量，同样入缓存（组合键已防碰撞），避免反复全量匹配
+            (_a = this._replaceCache) === null || _a === void 0 ? void 0 : _a.Set(cacheKey, text);
+            return text;
+        }
+        // 在码点数组上操作：matches 的位置基于 Array.from 分词（码点索引），
+        // 直接对原字符串 slice 会因代理对（emoji 等）长度不一致而切错位置
+        const chars = Array.from(text);
+        // 合并重叠区间：重叠匹配若逐个替换，从后向前切片会互相错位（吞字或残留敏感片段）
+        const sorted = [...result.Matches].sort((a, b) => a.Start - b.Start);
+        const ranges = [];
+        for (const match of sorted) {
+            const last = ranges[ranges.length - 1];
+            if (last && match.Start < last.end) {
+                last.end = Math.max(last.end, match.End); // 重叠：并入上一区间
+            }
+            else {
+                ranges.push({ start: match.Start, end: match.End });
+            }
+        }
+        // 每个合并区间整体替换为一个 replacement 串（非逐字符屏蔽）；空串为合法替换值（删除敏感词）
+        const replaceChar = replacement !== null && replacement !== void 0 ? replacement : this.Cfg.Replacement;
+        for (let i = ranges.length - 1; i >= 0; i--) {
+            const { start, end } = ranges[i];
+            chars.splice(start, end - start, replaceChar); // 从后向前，前面的索引不受影响
+        }
+        const replacedText = chars.join('');
+        // 更新缓存
+        if (this._replaceCache) {
+            this._replaceCache.Set(cacheKey, replacedText);
+        }
+        return replacedText;
+    }
+    InjectSensitiveWords(words) {
+        for (const word of words) {
+            if (word && word.length > 0) {
+                this._sensitiveWords.add(word);
+            }
+        }
+        this.buildAutomaton();
+        this.clearCache();
+    }
+    InjectInterferenceWords(words) {
+        this._acAutomaton.AddInterferenceWords(words);
+        this.clearCache();
+    }
+    GetSensitiveWordCount() {
+        return this._sensitiveWords.size;
+    }
+    GetInterferenceWordCount() {
+        return this._acAutomaton.GetInterferenceWordCount();
+    }
+    ClearSensitiveWords() {
+        this._sensitiveWords.clear();
+        this.buildAutomaton();
+        this.clearCache();
+    }
+    ClearInterferenceWords() {
+        this._acAutomaton.ClearInterferenceWords();
+        this.clearCache();
+    }
+    /**
+     * 构建 AC 自动机
+     */
+    buildAutomaton() {
+        this._acAutomaton.Clear();
+        const words = this._sensitiveWords;
+        for (const word of words) {
+            this._acAutomaton.AddWord(word);
+        }
+        this._acAutomaton.Build();
+    }
+    /**
+     * 清空缓存
+     */
+    clearCache() {
+        var _a, _b, _c;
+        (_a = this._testCache) === null || _a === void 0 ? void 0 : _a.Clear();
+        (_b = this._findCache) === null || _b === void 0 ? void 0 : _b.Clear();
+        (_c = this._replaceCache) === null || _c === void 0 ? void 0 : _c.Clear();
+    }
+}
+
+export { AuditorPlugin };

package/dist/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nebulaaa/auditor",
+  "version": "1.0.0",
+  "description": "敏感词审计员插件",
+  "author": "doooreyn",
+  "license": "MIT",
+  "keywords": [
+    "auditor",
+    "nebulaaa"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "main": "./auditor.cjs",
+  "module": "./auditor.mjs",
+  "types": "./auditor.d.ts",
+  "exports": {
+    ".": {
+      "types": "./auditor.d.ts",
+      "require": "./auditor.cjs",
+      "import": "./auditor.mjs",
+      "default": "./auditor.cjs"
+    },
+    "./min": {
+      "require": "./auditor.min.cjs",
+      "import": "./auditor.min.mjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/package.json

@@ -1,6 +1,70 @@
-{
-  "name": "@nebulaaa/auditor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@nebulaaa/auditor",
+  "version": "1.0.0",
+  "description": "敏感词审计员插件",
+  "main": "./dist/auditor.cjs",
+  "module": "./dist/auditor.mjs",
+  "types": "./dist/auditor.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/auditor.cjs",
+      "import": "./dist/auditor.mjs",
+      "types": "./dist/auditor.d.ts",
+      "default": "./dist/auditor.cjs"
+    },
+    "./min": {
+      "require": "./dist/auditor.min.cjs",
+      "import": "./dist/auditor.min.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && rollup -c rollup.config.mjs && node ../scripts/write-dist-package.mjs auditor",
+    "test": "jest"
+  },
+  "keywords": [
+    "auditor",
+    "nebulaaa"
+  ],
+  "author": "doooreyn",
+  "license": "MIT",
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10.0.0",
+      "onFail": "warn"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "allowScripts": {
+    "unrs-resolver@1.12.2": true,
+    "@parcel/watcher@2.6.0": true
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.2",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.5.2",
+    "rollup": "^4.28.1",
+    "rollup-plugin-dts": "^6.1.1",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.7.3"
+  },
+  "dependencies": {
+    "@nebulaaa/dict": "^1.1.0",
+    "@nebulaaa/lru": "^1.1.0",
+    "@nebulaaa/plugin": "^1.0.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.