docs(canvas): explain import parsers, identities and integrity gates

This commit is contained in:
2026-11-12 00:31:08 +08:00
parent 68e655b52c
commit 72e84a6cc1
10 changed files with 150 additions and 0 deletions
+11
View File
@@ -1,13 +1,20 @@
/**
* 依赖等待记录的批选择。以迭代Kosaraju找强连通分量(SCC),让完全收到的循环引用组原子加入,
* 单独按拓扑排序丢掉所有环会误拒合法对象图;组外依赖须已提交或在本批前面选中。
*/
import type { ImportLocator } from './imports.ts';
import { fault } from '../canvas-core/values.ts';
/** Ready SCCs are indivisible. Ordinary records retain source-order FIFO selection. */
/** pending按源顺序输入;返回有序原子组,不实际提交,缺依赖的组继续等待而非直接丢失。 */
export function selectImportGroups(pending: readonly ImportLocator[], committed: ReadonlySet<string>, limits: {units: number; bytes: number; changes: number}): readonly (readonly ImportLocator[])[] {
// 正向边仅含当前pending内依赖,反向表用于第二次DFS;原index保留稳定源顺序。
const byKey = new Map(pending.map((row, index) => [row.key, {row, index}])), edges = new Map<string, string[]>(), reverse = new Map<string, string[]>();
for (const row of pending) {
const dependencies = row.dependencies.filter(key => byKey.has(key)); edges.set(row.key, dependencies);
for (const key of dependencies) { const list = reverse.get(key) ?? []; list.push(row.key); reverse.set(key, list); }
}
// 第一遍显式DFS保存完成序,frame.index支持逐邻居推进,避免深链递归调用栈溢出。
const seen = new Set<string>(), finish: string[] = [];
for (const row of pending) {
if (seen.has(row.key)) continue;
@@ -18,6 +25,7 @@ export function selectImportGroups(pending: readonly ImportLocator[], committed:
const key = neighbors[frame.index++]; if (!seen.has(key)) { seen.add(key); stack.push({key, index: 0}); }
}
}
// 第二遍按反向完成序走反向边收集SCC,组内/组间再按最早源index排序。
seen.clear(); const components: ImportLocator[][] = [];
for (let i = finish.length - 1; i >= 0; i--) {
const first = finish[i]; if (seen.has(first)) continue;
@@ -26,13 +34,16 @@ export function selectImportGroups(pending: readonly ImportLocator[], committed:
group.sort((a, b) => byKey.get(a.key)!.index - byKey.get(b.key)!.index); components.push(group);
}
components.sort((a, b) => byKey.get(a[0].key)!.index - byKey.get(b[0].key)!.index);
// committed与本轮已选择组构成可用依赖;一组不能满足自己之外尚未到齐的引用。
const available = new Set(committed), chosen: ImportLocator[][] = []; let units = 0, bytes = 0, changes = 0;
for (const group of components) {
const internal = new Set(group.map(row => row.key));
if (!group.every(row => row.dependencies.every(key => available.has(key) || internal.has(key)))) continue;
// SCC不可拆:单组字节/changes超安全上限必须报错,不能分批提交半个循环引用。
const size = group.reduce((sum, row) => sum + row.byteLength, 0), count = group.reduce((sum, row) => sum + row.changeCount, 0);
if (size > limits.bytes || count > limits.changes) throw fault('import_dependency_group_capacity');
// The frame's adaptive unit budget is soft for one SCC, byte/change safety limits are hard.
// 第一组可超过units软预算以闭合环;后续组和字节/changes总预算仍保守限制。
if (units && units + group.length > limits.units || bytes + size > limits.bytes || changes + count > limits.changes) continue;
chosen.push(group); units += group.length; bytes += size; changes += count; for (const row of group) available.add(row.key);
}