源码片段提取与覆盖检查

// Extract once, after ordinary Markdown links are rewritten. Never re-parse
// a marker that happens to occur inside the source code being displayed.
const marker = /<!-- source: ([^\n]+):(\d+)-(\d+) -->/g;
const linesOf = code => code.replace(/\n$/, '').split('\n');

export function expandExcerpts(body, sources, used) {
  if (/<!--\s*source:/.test(body.replace(marker, ''))) throw new Error('Malformed source marker');
  return body.replace(marker, (_whole, name, first, last) => {
    const source = sources.get(name);
    if (!source) throw new Error(`Unlisted teaching source: ${name}`);
    const lines = linesOf(source.code), start = Number(first), end = Number(last);
    if (start < 1 || end < start || end > lines.length) throw new Error(`Invalid source range: ${name}:${start}-${end} (file has ${lines.length})`);
    const seen = used.get(name) || new Set();
    for (let n = start; n <= end; n++) seen.add(n);
    used.set(name, seen);

    const code = lines.slice(start - 1, end).join('\n');
    const longest = Math.max(2, ...(code.match(/`+/g) || []).map(s=>s.length));
    const fence = '`'.repeat(longest + 1);
    const notice = source.redacted && (start === 1 || code.includes('[REDACTED:')) ? '\n> 此文件的私有运行环境规则已在公开展示中隐藏；行号保持对应本机源码。\n' : '';
    return `\n**\`${name}\` · L${start}–L${end}** · [打开完整源码](/code/${source.id}/#L${start})\n${notice}\n<div class="code-excerpt" style="--line-start:${start-1}">\n\n${fence}${source.lang}\n${code}\n${fence}\n\n</div>\n`;
  });
}

// This checks displayed source coverage, not the semantic quality of prose.
export function verifyCoverage(sources, expected, used) {
  return [...new Set(expected)].map(name => {
    const source = sources.get(name);
    if (!source) throw new Error(`Unlisted coverage target: ${name}`);
    const lines = linesOf(source.code), seen = used.get(name) || new Set();
    const meaningful = lines.map((text,i)=>text.trim() ? i+1 : 0).filter(Boolean);
    const missing = meaningful.filter(n=>!seen.has(n));
    if (missing.length) throw new Error(`Uncovered source lines: ${name}: ${missing.join(', ')}`);
    return {name, lines:lines.length, covered:meaningful.length};
  });
}

import assert from 'node:assert/strict';
import { expandExcerpts, verifyCoverage } from './excerpts.mjs';
const sources = new Map([['x.go', {code:'package x\n\nvar a = 1\n',lang:'go',id:'x-go'}]]);
const used = new Map();
const rendered = expandExcerpts('解释\n<!-- source: x.go:1-3 -->\n逐行说明', sources, used);
assert.match(rendered, /package x/);
assert.match(rendered, /--line-start:0/);
assert.match(rendered, /\/code\/x-go\/#L1/);
assert.match(rendered, /逐行说明/);
assert.equal(verifyCoverage(sources, ['x.go'], used)[0].covered, 2);

assert.throws(()=>expandExcerpts('<!-- source: secret.env:1-2 -->',sources,new Map()),/Unlisted/);
assert.throws(()=>expandExcerpts('<!-- source: x.go:1-8 -->',sources,new Map()),/range/);
assert.throws(()=>expandExcerpts('<!-- source: x.go:L1-L2 -->',sources,new Map()),/Malformed/);
assert.throws(()=>verifyCoverage(sources,['x.go'],new Map()),/Uncovered/);
const self = new Map([['a.js',{code:'const marker = "<!-- source: not-a-file:1-2 -->";\n',lang:'js',id:'a-js'}]]);
assert.match(expandExcerpts('<!-- source: a.js:1-1 -->',self,new Map()),/not-a-file/);
console.log('Excerpt extraction, line offsets, coverage and publication boundaries passed.');