dsh-thesis 1.0.0

package/lib/dedup/normalize.js

@@ -0,0 +1,329 @@
+/**
+ * 降重模块的文本归一化与切分（确定性，无第三方依赖）。
+ *
+ * 两件事：
+ * 1. **归一化**：全角/半角统一（NFKC 的常用子集）、去 Markdown 标记与空白标点、
+ *    中文按字切分、拉丁按词切分（统一小写）。归一化后每个字符都带一条
+ *    「原文偏移」记录，使任何命中都能回到原始行号与原文片段。
+ * 2. **段落切分**：按空行与 Markdown 结构切段，标题行/代码块/公式行/
+ *    参考文献条目/表格行/引用块不算正文重复；短于 `minChars` 的段落跳过。
+ *
+ * 归一化与偏移必须一一对应：{@link NormalizedText.chars} 的第 i 个字符来自
+ * {@link NormalizedText.tokens} 中某个 token 的第 j 个字符，而该 token 记录了
+ * 它在**原文**中的起止偏移（`[start, end)`）。
+ *
+ * @module dsh-thesis/dedup
+ */
+// ---------------------------------------------------------------------------
+// 全角 / 半角
+// ---------------------------------------------------------------------------
+/** 常见中文标点 → ASCII 等价物；归一化后会被当作可忽略标点。 */
+const PUNCT_MAP = {
+    '，': ',', '。': '.', '、': ',', '；': ';', '：': ':', '？': '?', '！': '!',
+    '（': '(', '）': ')', '【': '[', '】': ']', '《': '<', '》': '>',
+    '“': '"', '”': '"', '‘': "'", '’': "'", '—': '-', '–': '-', '…': '.',
+    '～': '~', '·': '.', '　': ' ',
+};
+/**
+ * 全角 → 半角、常见中文标点 → ASCII、统一大小写与换行符。
+ * 除 BOM（丢弃）与 CRLF（合并为一个 `\n`）外逐字符等长替换，
+ * 因此行号与原文字符偏移都保持可对应。
+ */
+export function toHalfWidth(input) {
+    let out = '';
+    let pendingCr = false;
+    for (const ch of input) {
+        if (ch === '\uFEFF')
+            continue;
+        if (ch === '\r') {
+            out += '\n';
+            pendingCr = true;
+            continue;
+        }
+        if (ch === '\n') {
+            // CRLF 只算一次换行（保证行号与原始文件一致）。
+            if (!pendingCr)
+                out += '\n';
+            pendingCr = false;
+            continue;
+        }
+        pendingCr = false;
+        if (ch === '\t') {
+            out += ch;
+            continue;
+        }
+        const mapped = PUNCT_MAP[ch];
+        if (mapped !== undefined) {
+            out += mapped;
+            continue;
+        }
+        const code = ch.codePointAt(0) ?? 0;
+        if (code >= 0xFF01 && code <= 0xFF5E) {
+            out += String.fromCharCode(code - 0xFEE0);
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// 行级屏蔽（结构行不算正文）
+// ---------------------------------------------------------------------------
+/** 标题行：`# 标题`。 */
+export function isHeadingLine(line) {
+    return /^\s{0,3}#{1,6}\s/.test(line);
+}
+/** 围栏代码块：``` 或 ~~~（≥3 个）。 */
+export function isCodeFence(line) {
+    return /^\s{0,3}(`{3,}|~{3,})/.test(line);
+}
+/** 缩进代码块（4 空格 / 1 个制表符开头）。 */
+export function isIndentedCode(line) {
+    return /^( {4,}|\t)\S/.test(line);
+}
+/** 独立公式行：`$$...$$`、`\begin{...}` 环境，或整行基本由数学符号构成。 */
+export function isFormulaLine(line) {
+    const t = line.trim();
+    if (t === '')
+        return false;
+    if (/^\$\$/.test(t) || /^\\[a-zA-Z]*\{?(equation|align|array)/.test(t))
+        return true;
+    const compact = t.replace(/\s/g, '');
+    if (!/[$\\=]/.test(t) || compact.length === 0)
+        return false;
+    const math = compact.replace(/[^$\\=+\-*/^_{}()[\]]/g, '').length;
+    return math >= compact.length * 0.5;
+}
+/** 图片行、水平分割线、HTML 注释行。 */
+export function isStructuralLine(line) {
+    const t = line.trim();
+    return /^!\[/.test(t) || /^(-{3,}|\*{3,}|_{3,})$/.test(t) || /^<!--/.test(t) || /-->$/.test(t);
+}
+/** 表格行。 */
+export function isTableLine(line) {
+    return /^\s{0,3}\|/.test(line);
+}
+/** 引用块行（以 `>` 开头的说明性文字）。 */
+export function isQuoteLine(line) {
+    return /^\s{0,3}>/.test(line);
+}
+/** 列表项行（提纲/清单，不是连续论述）。 */
+export function isListItemLine(line) {
+    return /^\s{0,3}([-*+]|\d+[.)])\s/.test(line);
+}
+/** 参考文献标题（`## 参考文献` / `# References` 等）。 */
+export function isReferenceHeading(line) {
+    const t = line.trim().replace(/^#{1,6}\s*/, '');
+    return /^(参考文献|引用文献|references?|bibliography)$/i.test(t);
+}
+/** 参考文献条目行：`[1] 作者. 题名. 期刊, 年.` */
+export function isReferenceEntry(line) {
+    return /^\s{0,3}\[\d{1,3}\]\s*\S/.test(line);
+}
+/** 模板脚手架提示行（`（写作要求：...）`、`（待补）` 等）。 */
+export function isPlaceholderLine(line) {
+    const t = line.trim();
+    return /^[（(]\s*(写作要求|待补|待写|待演练|待填写)/.test(t) || /^(TODO|TBD|FIXME)\b/.test(t);
+}
+/** 该行是否属于「不构成正文重复」的结构行（不含空行判断）。 */
+export function isSkippedLine(line) {
+    return isHeadingLine(line)
+        || isCodeFence(line)
+        || isIndentedCode(line)
+        || isFormulaLine(line)
+        || isStructuralLine(line)
+        || isTableLine(line)
+        || isQuoteLine(line)
+        || isListItemLine(line)
+        || isReferenceHeading(line)
+        || isReferenceEntry(line)
+        || isPlaceholderLine(line);
+}
+// ---------------------------------------------------------------------------
+// 归一化 + 偏移映射
+// ---------------------------------------------------------------------------
+function isCjk(ch) {
+    const code = ch.codePointAt(0) ?? 0;
+    return (code >= 0x4E00 && code <= 0x9FFF)
+        || (code >= 0x3400 && code <= 0x4DBF)
+        || (code >= 0xF900 && code <= 0xFAFF);
+}
+function isLatinStart(ch) {
+    return /[A-Za-z\u00C0-\u024F]/.test(ch);
+}
+function isLatinBody(ch) {
+    return /[A-Za-z0-9_\u00C0-\u024F]/.test(ch);
+}
+/** 拉丁词内部保留数字与下划线：`http_server`、`apiv2` 仍是可区分的标识符。 */
+function isKeptLatin(ch) {
+    return /[A-Za-z0-9_\u00C0-\u024F]/.test(ch);
+}
+/** 数字（含小数）：数字是降重的"硬要素"，必须参与比对（改了数字就是改数据）。 */
+function isDigitStart(ch) {
+    return ch >= '0' && ch <= '9';
+}
+function isDigitBody(ch) {
+    return (ch >= '0' && ch <= '9') || ch === '.';
+}
+/**
+ * 归一化一段文本，并记录每个归一化字符的原文偏移。
+ *
+ * 保留中文、拉丁词（含数字与下划线）与独立数字；标点、空白、Markdown 标记
+ * 全部丢弃 —— 字符级过滤不会破坏偏移映射（字符是逐个追加的）。
+ */
+export function normalizeText(text) {
+    const half = toHalfWidth(text);
+    const tokens = [];
+    const chars = [];
+    let normalized = '';
+    const pushChar = (ch, offset) => {
+        tokens.push({ text: ch, start: offset, end: offset + 1 });
+        chars.push({ ch, offset, tokenStart: true, breakBefore: true });
+        normalized += ch;
+    };
+    const pushWord = (from, to, word) => {
+        if (word === '')
+            return;
+        tokens.push({ text: word, start: from, end: to });
+        let first = true;
+        for (let k = 0; k < to - from; k += 1) {
+            const c = word[k];
+            if (c === undefined)
+                continue;
+            chars.push({ ch: c, offset: from + k, tokenStart: first, breakBefore: first });
+            first = false;
+        }
+        normalized += word;
+    };
+    let i = 0;
+    while (i < half.length) {
+        const ch = half[i];
+        if (isCjk(ch)) {
+            pushChar(ch, i);
+            i += 1;
+            continue;
+        }
+        if (isLatinStart(ch)) {
+            let j = i + 1;
+            while (j < half.length && isLatinBody(half[j]))
+                j += 1;
+            pushWord(i, j, half.slice(i, j).toLowerCase());
+            i = j;
+            continue;
+        }
+        if (isDigitStart(ch)) {
+            let j = i + 1;
+            while (j < half.length && isDigitBody(half[j]))
+                j += 1;
+            pushWord(i, j, half.slice(i, j));
+            i = j;
+            continue;
+        }
+        i += 1;
+    }
+    return { text: normalized, tokens, chars };
+}
+/**
+ * 把归一化字符区间 `[from, to)` 映射回**原文**的字符区间。
+ * 返回闭开区间 `{ start, end }`；空区间返回 `null`。
+ */
+export function offsetsFor(doc, from, to) {
+    const lo = Math.max(0, from);
+    const hi = Math.min(doc.chars.length, to);
+    if (hi <= lo)
+        return null;
+    const first = doc.chars[lo];
+    const last = doc.chars[hi - 1];
+    return { start: first.offset, end: last.offset + 1 };
+}
+/** 原文区间 `[start, end)` 的文本（越界自动截断）。 */
+export function sliceRaw(raw, start, end) {
+    const lo = Math.max(0, Math.min(raw.length, start));
+    const hi = Math.max(lo, Math.min(raw.length, end));
+    return raw.slice(lo, hi);
+}
+/** 原始文本中某个字符偏移对应的 1 基行号。 */
+export function lineAt(raw, offset) {
+    const clamped = Math.max(0, Math.min(raw.length, offset));
+    let line = 1;
+    for (let i = 0; i < clamped; i += 1) {
+        if (raw[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+// ---------------------------------------------------------------------------
+// 段落切分
+// ---------------------------------------------------------------------------
+/**
+ * 按空行与 Markdown 结构切段。
+ *
+ * 规则（全部确定性）：
+ * - 围栏代码块（``` 之间）、标题行、公式行、表格行、引用块、列表项行、
+ *   参考文献条目/文献区、模板占位行，一律**不参与**比对；
+ * - 连续的非跳过行合并为一个段落，段落边界在空行或跳过行处断开；
+ * - 归一化后不足 `minChars` 个字符的段落跳过（返回 `skipped` 便于解释原因）。
+ */
+export function segmentsFromText(text, options) {
+    // 归一化输入的形态：全角→半角（逐字符等长，BOM 除外）与 CRLF→LF，
+    // 因此行号、段内字符偏移都与原文一致。
+    const halfText = toHalfWidth(text);
+    const halfLines = halfText.split('\n');
+    const segments = [];
+    const chapter = options.chapter ?? options.file;
+    let skippedShort = 0;
+    let inCode = false;
+    let inReferences = false;
+    let bufferStart = -1;
+    let bufferEnd = -1;
+    const flush = () => {
+        if (bufferStart < 0)
+            return;
+        const start = bufferStart;
+        const end = bufferEnd;
+        bufferStart = -1;
+        bufferEnd = -1;
+        const raw = halfLines.slice(start - 1, end).join('\n');
+        const doc = normalizeText(raw);
+        if (doc.chars.length < options.minChars) {
+            skippedShort += 1;
+            return;
+        }
+        segments.push({
+            file: options.file,
+            chapter,
+            lineStart: start,
+            lineEnd: end,
+            raw,
+            text: raw,
+            doc,
+        });
+    };
+    for (let index = 0; index < halfLines.length; index += 1) {
+        const line = halfLines[index];
+        const lineNo = index + 1;
+        if (isCodeFence(line)) {
+            flush();
+            inCode = !inCode;
+            continue;
+        }
+        if (inCode)
+            continue;
+        if (isReferenceHeading(line)) {
+            flush();
+            inReferences = true;
+            continue;
+        }
+        if (inReferences)
+            continue;
+        if (line.trim() === '' || isSkippedLine(line)) {
+            flush();
+            continue;
+        }
+        if (bufferStart < 0)
+            bufferStart = lineNo;
+        bufferEnd = lineNo;
+    }
+    flush();
+    return { segments, skippedShort };
+}

package/lib/dedup/report.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 降重报告的渲染：分级、行号、命中来源、原文片段、处方、全文加权重复率估算，
+ * 以及可回填的「学校检测结果」区块。
+ *
+ * 报告口径（必须与文字一起出现，不得省去）：
+ * - 本地相似度是**字符串重合度估算**，算法为 shingle 指纹 + 包含率，
+ *   只在用户给定的参考语料内比较，**不等于**知网/维普等系统的重复率；
+ * - 本插件不接入任何收费查重系统（无账号、也不应接入）；学校结果是权威口径，
+ *   用户自行送检后可把重复率回填进本报告，用于对齐两套口径的差距。
+ *
+ * @module dsh-thesis/dedup
+ */
+import type { ScanResult } from './similarity.ts';
+import { type RewritePlan } from './rewrite.ts';
+/** 风险分级：high（≥ threshold）| medium（≥ 0.6×threshold）| low（其余）。 */
+export type RiskLevel = 'high' | 'medium' | 'low';
+export interface ReportRiskItem {
+    readonly level: RiskLevel;
+    readonly chapter: string;
+    readonly file: string;
+    readonly lineStart: number;
+    readonly lineEnd: number;
+    readonly score: number;
+    readonly source: string;
+    /** 原文片段（截断到 120 字）或命中片段（原文坐标）。 */
+    readonly excerpt: string;
+    /** 命中片段（原文坐标，含行号）。 */
+    readonly matches: readonly {
+        readonly lineStart: number;
+        readonly lineEnd: number;
+        readonly text: string;
+    }[];
+    /** 结构化改写处方。 */
+    readonly plan: RewritePlan;
+    /** 该段原始文本（未截断，供结构化消费方使用）。 */
+    readonly text: string;
+}
+export interface ReportSummary {
+    readonly paragraphCount: number;
+    readonly matchedCount: number;
+    readonly high: number;
+    readonly medium: number;
+    readonly low: number;
+    /** 唯一命中来源数。 */
+    readonly sourceCount: number;
+    /** 全文加权重复率估计（见 {@link ReportOptions.algorithm}）。 */
+    readonly weightedRate: number;
+}
+export interface DetectedResult {
+    /** 用户自行送检得到的重复率（0..1，或 0..100 的百分数，>1 视为百分数）。 */
+    readonly rate: number;
+    /** 检测系统名称（如"知网 PMLC"），可缺省。 */
+    readonly system?: string;
+    /** 送检/出报告日期（任意字符串，原样保留）。 */
+    readonly date?: string;
+}
+export interface ReportOptions {
+    /** 判定高风险的包含率阈值。 */
+    readonly threshold: number;
+    readonly shingle: number;
+    readonly minChars: number;
+    /** 用户自行送检的结果（可选，回填进报告）。 */
+    readonly detected?: DetectedResult;
+    /** 查询时间（默认 `new Date()`；测试注入固定时间以保证可复现）。 */
+    readonly now?: Date;
+    /** 本次扫描的参考语料说明（文件/目录，展示用）。 */
+    readonly corpusLabels?: readonly string[];
+}
+export interface DedupReport {
+    readonly summary: ReportSummary;
+    readonly risks: readonly ReportRiskItem[];
+    readonly algorithm: string;
+    readonly generatedAt: string;
+    readonly detected?: DetectedResult;
+    readonly boundaries: readonly string[];
+}
+/** 估算口径说明（单一来源，Markdown 与结构化对象共用）。 */
+export declare const ALGORITHM_NOTE: string;
+/** 边界说明（写入报告，避免误用）。 */
+export declare const BOUNDARY_NOTES: readonly string[];
+/**
+ * 全文加权重复率估计（口径明确、可复现）：
+ * `Σ(命中段落归一化字符数 × 该段最佳命中得分) / 全文参与比对的字符总数`。
+ * 分母包含**未命中段落**（按 0 计入），因此该值是保守估计（不会低报）。
+ */
+export declare function weightedRateOf(scanResult: ScanResult): number;
+/** 结构化报告对象即「报告的结构化形态」。 */
+export declare function buildReport(scanResult: ScanResult, options: ReportOptions): DedupReport;
+export declare function levelLabel(level: RiskLevel): string;
+/** 渲染 Markdown 报告。 */
+export declare function renderReport(report: DedupReport, options: ReportOptions): string;
+export interface BaselineSnapshot {
+    readonly paragraphCount: number;
+    readonly matchedCount: number;
+    readonly high: number;
+    readonly medium: number;
+    readonly weightedRate: number;
+}
+/** 从 baseline 报告（Markdown）解析出汇总指标；解析失败返回 null。 */
+export declare function parseBaseline(markdown: string): BaselineSnapshot | null;
+export interface VerifyDelta {
+    readonly baseline: BaselineSnapshot;
+    readonly current: BaselineSnapshot;
+    /** 加权重复率降幅（百分点，正数表示下降）。 */
+    readonly rateDrop: number;
+    readonly rateDropRatio: number;
+    readonly highDrop: number;
+    readonly mediumDrop: number;
+    readonly verdict: string;
+}
+/** 计算复测降幅（正数 = 下降）。 */
+export declare function verifyDelta(baseline: BaselineSnapshot, current: BaselineSnapshot): VerifyDelta;
+/** 渲染复测报告（降重报告-复测.md）。 */
+export declare function renderVerifyReport(delta: VerifyDelta, options: ReportOptions, riskSource: DedupReport): string;