把讲义与源码装进网站

/* Public view: redacted lines; not a complete executable copy. */ // Explicit publishing boundary: only listed docs/source, never the whole repository.
import fs from 'node:fs';
import path from 'node:path';
import { symbolsFor } from './symbols.mjs';
import { readings, readingSources } from './readings.mjs'; import { goPatternDocs, goPatternSources } from './go-patterns.mjs'; import { deepDocs, deepSources } from './deep.mjs';
import { expandExcerpts, verifyCoverage } from './excerpts.mjs';
const root = path.resolve('..');

const docs = [
  ['foundations', '前置课程：从刚入门开始', 'docs/foundations/index.md', '只默认基本编程，先建立理解实现所需的知识地图。', 'basics'],
  ['basics-tools', '工程工具与数据', 'docs/foundations/engineering-basics.md', '终端、文件、依赖、JSON 与测试分别在做什么。', 'basics'],
  ['basics-go', 'Go 语言入门', 'docs/foundations/go-language.md', '从函数和变量读到 struct、方法与接口。', 'basics'],
  ['basics-values', 'Go 的值与内存', 'docs/foundations/go-values.md', '指针、slice、map、拷贝与生命周期。', 'basics'],
  ['basics-execution', '程序怎样运行', 'docs/foundations/execution-stack.md', '编译、解释、CPython、Wasm 与 Host/Guest。', 'basics'],
  ['basics-memory', '内存与跨语言 ABI', 'docs/foundations/memory-abi.md', '从 bit/byte 到指针、buffer 与引用计数。', 'basics'],
  ['basics-concurrency', '并发、等待与取消', 'docs/foundations/concurrency.md', 'goroutine、channel、可见性和任务收尾。', 'basics'],
  ['basics-plm', 'PLM 的思考基础', 'docs/foundations/plm-reasoning.md', '依赖、AST、只读快照与交付时机。', 'basics'],
  ['basics-linux', 'Ubuntu 构建与离线演示', 'docs/foundations/linux-build-and-offline.md', 'WSL、交叉编译、构建缓存与 network namespace。', 'basics'],
  ['basics-web', 'Web 与发布（可选）', 'docs/foundations/web-basics.md', '浏览器、HTTP、Pages，以及 noindex 的边界。', 'basics'],

  ['research-positioning', 'Pysolate 定位：云端 Agent 执行', 'docs/research/cloud-agent-execution.md', '轻重执行分工、驻留成本与固定资源下的任务容量。', 'research'],
  ['research-reuse', '研究探索：生成代码复用', 'docs/research/reusable-code-exploration.md', '从问题定义、方法方向到实验数据与后续设想。', 'research'],
  ['research-memory', '内存优化历程：每个新增 Guest 的成本', 'docs/research/memory-optimization.md', '从引擎冗余、COW 写放大到分配器布局，记录配对数据与失败方案。', 'research'],
  ['guide', '学习顺序与完整路径', 'docs/learning-guide.md', '从两行 Python 到 Host 边界，逐步读懂实现。'],
  ['flow', '调用与状态图', 'docs/execution-flow.md', '区分 Guest 控制流、Host 任务与 Future。'],
  ['plm', 'Whole-program PLM', 'docs/whole-program-plm.md', '依赖、控制流与原调用处的结果交付。'],
  ['prefix', '流式 Prefix', 'docs/prefix.md', '接收完整语句，复用同一个 Guest 与 Future。'],
  ['prepared-copy', '可选：Prepared full-copy', 'docs/prepared-copy.md', '先理解干净基线与全量私有副本。'],
  ['cow', 'Linux COW：共享与隔离', 'docs/cow.md', '虚拟内存、memfd、同地址映射与私有写入。'],
  ['examples', '五个边界例子', 'docs/walkthrough-examples.md', '独立、依赖、分支、错误和正常回退。'],
  ['python-provider', 'Python 工具实现', 'docs/python-provider.md', 'Guest 经固定 Go 桥调用 native Python worker。'],
  ['python-editor', 'Python IDE 类型提示', 'docs/python-editor.md', '保留原始源码，用静态声明识别注入工具。'],
  ['core-demos', '四个核心 Demo', 'docs/core-demos.md', '普通调用、PLM、prefix、隔离与 prepared 复用。'],
  ['demo-walkthrough', '扩展：报告与通知', 'docs/demo-walkthrough.md', '一个 Python 程序，三个 Host 结果，沿调用链理解执行与状态信息。'],
  ['interview', '演示与协作练习', 'docs/interview-playbook.md', '运行入口、讲解顺序和未解答的小需求。'],
  ['questions', '六张追问卡', 'docs/question-cards.md', '带源码入口的问题，不替你写标准答案。'],
  ['build', '构建与来源', 'docs/build-and-provenance.md', '实际 Wasm 的打包边界与使用条件。'], ['meal-curriculum', '饭点课分课路线', 'docs/meal-curriculum.md', '流程课与知识小点怎样对应代码带读。'],
  ['repository', '仓库说明', 'README.md', '命令、实现范围与文件导航。'],

];
const sourceFiles = [
  'cmd/python-provider/main.go', 'cmd/python-provider/main_test.go', 'examples/python_provider.py',
  'providers/report.py', 'examples/typings/__builtins__.pyi', 'pyrightconfig.json',
  'cmd/walkthrough/main.go', 'cmd/walkthrough/main_test.go', 'examples/notification.py', 'demos/walkthrough.sh', 'demos/core.sh',
  'runner.go', 'bridge.go', 'future.go', 'prefix.go', 'prepared.go',
  'cow.go', 'cow_linux.go', 'cow_other.go', 'cow_test.go', 'cow_linux_test.go',
  'guest/bootstrap.py', 'guest/plm.py', 'guest/prefix.py', 'guest/runtime.c',
  'cmd/demo/main.go', 'runner_test.go', 'plm_test.go', 'prefix_test.go', 'prepared_test.go',
  'cmd/demo/main_test.go', 'guest/test_plm.py', 'guest/test_prefix.py',
  'examples/lookup.py', 'examples/order.py', 'examples/dependency.py', 'examples/branch.py',
  'examples/error_delivery.py', 'examples/fallback.py', 'build-guest.sh', 'Makefile',
  'tools/setup-build-inputs.py', 'tools/build-inputs.lock.json',
  'go.mod', 'go.sum', 'LICENSE', '.gitignore', 'tools/offline-check.sh', 'tools/read-local.sh', 'site/public/_headers',
];
docs.unshift(...readings.map(([slug,title,file,description])=>[slug,title,`docs/code-reading/${file}.md`,description,'reading'])); docs.unshift(['order-tour','先跟完一次 order.py','docs/order-function-tour.md','按函数职责和调用目的读正常执行路径。','reading']);
sourceFiles.push(...readingSources.filter(name=>!sourceFiles.includes(name))); docs.push(...goPatternDocs, ...deepDocs); sourceFiles.push(...goPatternSources(root), ...deepSources); docs.push(['trading-demo','模拟交易：控制流与工具许可','docs/trading-demo.md','带时间戳观察安全读取、分支和本地下单。']); sourceFiles.push('examples/trading.py','cmd/trade-demo/main.go','cmd/trade-demo/market.go','cmd/trade-demo/main_test.go','cmd/trade-demo/market_test.go'); sourceFiles.push(...['run.sh','trade.sh','01-price-skip.sh','02-cash-skip.sh','03-host-denied.sh','04-approved.sh','05-prefix.sh','06-plm-source.sh'].map(name=>'demos/'+name));
const id = name => name.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
const routes = new Map(docs.map(([slug,,file]) => [file, `/${slug}/`]));
for (const file of sourceFiles) routes.set(file, `/code/${id(file)}/`);
routes.set('site/public/plm-flow.svg', '/plm-flow.svg'); routes.set('site/public/deep-memory-domains.svg', '/deep-memory-domains.svg');
routes.set('site/public/robots.txt', '/robots.txt');

routes.set('tools/rebuild-guest.py', '/build/'); // Private machine defaults stay local.
/* [REDACTED: private operational rule] */
function check(text, name) {
  for (const pattern of forbidden) if (pattern.test(text)) throw new Error(`Private operational detail in ${name}: ${pattern}`);
}
// Only the privacy-rule implementations have a visibly redacted public view.
// Other source files still fail closed if private operational details appear.
const ruleFiles = new Set(['site/scripts/prepare.mjs', 'site/scripts/verify.mjs']);
const sources = [...new Set(sourceFiles)].map(name => {
  let code = fs.readFileSync(path.join(root,name),'utf8'), redacted = false;
  if (ruleFiles.has(name)) {
    code = code.split('\n').map(line=>{
      try { check(line,name); return line; }
      catch { redacted = true; return '/* [REDACTED: private operational rule] */'; }
    }).join('\n');
    if (redacted) code = '/* Public view: redacted lines; not a complete executable copy. */ '+code;
  }
  check(code,name);
  const ext = path.extname(name);
  const lang = ({'.go':'go','.py':'python','.c':'c','.sh':'bash','.mjs':'js','.ts':'ts','.astro':'astro','.css':'css','.json':'json'})[ext] || 'text';
  return {id:id(name),name,code,lang,redacted,symbols:symbolsFor(name,code)};
});
const sourceMap = new Map(sources.map(s=>[s.name,s]));

const usedLines = new Map();
fs.rmSync('.generated', { recursive: true, force: true });
fs.mkdirSync('.generated/docs', { recursive: true });
for (const [order, [slug,title,file,description,section = 'implementation']] of docs.entries()) {
  let body = fs.readFileSync(path.join(root,file), 'utf8');
  body = body.replace(/\]\(([^)]+)\)/g, (whole, target) => {
    if (/^(https?:|#|mailto:)/.test(target)) return whole;
    const [name,fragment] = target.split('#');
    const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file),name));
    const route = routes.get(resolved);
    if (!route) throw new Error(`Unlisted publication link: ${file} -> ${target}`);
    return `](${route}${fragment ? '#'+fragment : ''})`;
  });
  body = expandExcerpts(body,sourceMap,usedLines);
  check(body,file);
  body = body.replace(/^# [^\n]*\n/, '');
  fs.writeFileSync(`.generated/docs/${slug}.md`, `---\ntitle: ${JSON.stringify(title)}\norder: ${order}\nsection: ${JSON.stringify(section)}\ndescription: ${JSON.stringify(description)}\n---\n${body}`);

}
const coverage = verifyCoverage(sourceMap,readingSources,usedLines);
fs.writeFileSync('.generated/reading-coverage.json', JSON.stringify(coverage));
console.log(`Reading excerpts cover ${coverage.length} source files, ${coverage.reduce((n,f)=>n+f.covered,0)} nonblank lines.`);
fs.writeFileSync('.generated/sources.json', JSON.stringify(sources));
fs.writeFileSync('.generated/navigation.json', JSON.stringify(docs.map(([slug,title,,description,section = 'implementation'])=>({slug,title,description,section}))));
console.log(`Publishing ${docs.length} documents and ${sources.length} source views; no runtime artifacts.`);

// Ordered chapters: one execution path first, advanced mechanisms afterwards.
export const readings = [
  ['read', '代码带读：沿执行路径理解', 'index', '先理解职责与状态，再读完整源码块。'],
  ['read-entry', '入口：参数、工具与模式', 'entry', 'cmd/demo/main.go'],
  ['read-runner', 'Runner：创建与运行', 'runner', 'runner.go'],
  ['read-guest-c', '跨入 C 与 CPython', 'guest-c', 'guest/runtime.c'],
  ['read-guest-python', 'Python 执行约定', 'guest-python', 'guest/bootstrap.py'],
  ['read-bridge', 'Host 工具边界', 'bridge', 'bridge.go'],
  ['read-runtime-tests', '用测试核对普通执行', 'runtime-tests', 'runner_test.go'],
  ['read-example-tests', 'CLI 示例的测试', 'example-tests', 'cmd/demo/main_test.go'],
  ['read-examples', '六个用户程序', 'examples', 'examples/*.py'],
  ['read-trading', '交易演示：从读取到条件下单', 'trading', '交易程序、Host 状态与对应测试'],
  ['read-demo-scripts', '快捷脚本：组织可重复的演示', 'demo-scripts', 'demos/*.sh'],
  ['read-futures', 'Future：本轮任务登记与交付', 'futures', 'future.go'],
  ['read-plm-pass', 'PLM：沿 AST 找安全提前点', 'plm-pass', 'guest/plm.py'],
  ['read-plm-tests', 'PLM 的真实执行测试', 'plm-tests', 'plm_test.go'],
  ['read-plm-python-tests', 'AST 改写的单元测试', 'plm-python-tests', 'guest/test_plm.py'],
  ['read-prefix-host', 'Host 怎样接收源码片段', 'prefix-host', 'prefix.go'],
  ['read-prefix-guest', 'Guest 怎样解析和领取', 'prefix-guest', 'guest/prefix.py'],
  ['read-prefix-tests', 'Prefix 的真实执行测试', 'prefix-tests', 'prefix_test.go'],

  ['read-prefix-python-tests', 'Prefix 的解析测试', 'prefix-python-tests', 'guest/test_prefix.py'],
  ['read-prepared', '初始化与内存恢复的分岔', 'prepared', 'prepared.go'],
  ['read-prepared-tests', 'Full-copy 的行为测试', 'prepared-tests', 'prepared_test.go'],
  ['read-cow-interface', 'COW 的小接口', 'cow-interface', 'cow.go'],
  ['read-cow-linux', 'Linux COW：逐步跟进系统调用', 'cow-linux', 'cow_linux.go'],
  ['read-cow-platform', '不支持的平台怎样报错', 'cow-platform', 'cow_other.go'],
  ['read-cow-kernel-tests', '验证映射与释放', 'cow-kernel-tests', 'cow_linux_test.go'],
  ['read-cow-guest-tests', 'COW 上的真实 Python', 'cow-guest-tests', 'cow_test.go'],
  ['read-go-module', 'Go 依赖与校验记录', 'go-module', 'go.mod / go.sum'],
  ['read-build-entry', 'Makefile：选择构建任务', 'build-entry', 'Makefile'],
  ['read-build-inputs', '准备本地编译工具链', 'build-inputs', 'tools/setup-build-inputs.py / lock'],
  ['read-guest-build', '链接并打包真实 Guest', 'guest-build', 'build-guest.sh'],
  ['read-offline', '隔离子进程网络', 'offline', 'tools/offline-check.sh'],
  ['read-local-reader', '启动静态阅读服务', 'local-reader', 'tools/read-local.sh'],
  ['read-site-content', 'Astro 内容与页面路由', 'site-content', '内容集合与普通页面'],
  ['read-site-source-view', '源码页的行号与函数导航', 'site-source-view', '源码页面与符号提取'],
  ['read-site-styles', 'CSS：布局与手机阅读', 'site-styles', 'site/src/styles/global.css'],
  ['read-site-validation', '检查页面与发布边界', 'site-validation', 'site/scripts/verify.mjs'],
  ['read-site-config', '站点依赖与搜索索引规则', 'site-config', 'package.json / headers / robots'],
  ['read-site-pipeline', '把讲义与源码装进网站', 'site-pipeline', 'prepare.mjs / readings.mjs'],
  ['read-site-layout', '代码优先的页面外壳', 'site-layout', 'Docs.astro / 首页 / 阅读样式'],
  ['read-site-excerpts', '源码片段提取与覆盖检查', 'site-excerpts', 'excerpts.mjs / 对应测试'],
];

// Complete source coverage accompanies responsibility-level explanations.
export const readingSources = [
  'cmd/demo/main.go', 'runner.go', 'bridge.go', 'guest/runtime.c', 'guest/bootstrap.py',
  'runner_test.go', 'cmd/demo/main_test.go',
  'examples/lookup.py', 'examples/order.py', 'examples/dependency.py',
  'examples/branch.py', 'examples/error_delivery.py', 'examples/fallback.py',
  'future.go', 'guest/plm.py', 'plm_test.go', 'guest/test_plm.py',
  'prefix.go', 'guest/prefix.py', 'prefix_test.go', 'guest/test_prefix.py',
  'prepared.go', 'prepared_test.go', 'cow.go', 'cow_linux.go', 'cow_other.go',
  'cow_linux_test.go', 'cow_test.go', 'go.mod', 'go.sum', 'Makefile',
  'tools/setup-build-inputs.py', 'tools/build-inputs.lock.json', 'build-guest.sh',
  'tools/offline-check.sh', 'tools/read-local.sh',
  'site/src/content.config.ts', 'site/src/pages/[slug].astro',
  'site/src/pages/code/[id].astro', 'site/src/pages/code/index.astro',
  'site/src/pages/404.astro', 'site/src/styles/global.css',
  'site/scripts/symbols.mjs', 'site/scripts/verify.mjs', 'site/package.json',
  'site/public/_headers', 'site/public/robots.txt',
  'site/scripts/prepare.mjs', 'site/scripts/readings.mjs',
  'site/src/layouts/Docs.astro', 'site/src/pages/index.astro',
  'site/src/styles/code-reading.css', 'site/scripts/excerpts.mjs', 'site/scripts/excerpts.test.mjs',
  'examples/trading.py', 'cmd/trade-demo/main.go', 'cmd/trade-demo/market.go',
  'cmd/trade-demo/main_test.go', 'cmd/trade-demo/market_test.go',
  'demos/run.sh', 'demos/trade.sh', 'demos/01-price-skip.sh', 'demos/02-cash-skip.sh',
  'demos/03-host-denied.sh', 'demos/04-approved.sh', 'demos/05-prefix.sh', 'demos/06-plm-source.sh',
];