Files
Genarrative/scripts/check-spacetime-schema-guard.mjs
T
kdletters e9c3dc1120 退役旧创作模板业务
保留 SpacetimeDB 历史表、迁移白名单与旧业务源码
切换前端 active 入口并解除旧创作页面和路由编译链
移除旧后端路由、worker 与纯业务 crate 依赖
收敛 SpacetimeDB 模块为历史数据壳
同步 Nginx、Pingora、验证门禁与架构文档
2026-07-17 22:07:52 +08:00

700 lines
19 KiB
JavaScript

import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync } from 'node:fs';
import { basename, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
const scriptDir = dirname(fileURLToPath(import.meta.url));
const repoRoot = join(scriptDir, '..');
const moduleSrcRoot = 'server-rs/crates/spacetime-module/src';
const moduleManifestPath = 'server-rs/crates/spacetime-module/Cargo.toml';
const migrationPath = `${moduleSrcRoot}/migration.rs`;
const tableCatalogPath = 'docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md';
const bindingsRoot = 'server-rs/crates/spacetime-client/src/module_bindings/';
const allowBreaking = process.env.SPACETIME_SCHEMA_GUARD_ALLOW_BREAKING === '1';
function normalizePath(path) {
return path.replace(/\\/gu, '/');
}
function runGit(args, options = {}) {
return execFileSync('git', args, {
cwd: repoRoot,
encoding: 'utf8',
stdio: options.quiet ? ['ignore', 'pipe', 'ignore'] : ['ignore', 'pipe', 'pipe'],
maxBuffer: 32 * 1024 * 1024,
}).trim();
}
function tryGit(args) {
try {
return runGit(args, { quiet: true });
} catch {
return null;
}
}
function resolveBaseRef() {
const explicitArgIndex = process.argv.indexOf('--base-ref');
if (explicitArgIndex >= 0 && process.argv[explicitArgIndex + 1]) {
return process.argv[explicitArgIndex + 1];
}
if (process.env.SPACETIME_SCHEMA_BASE_REF) {
return process.env.SPACETIME_SCHEMA_BASE_REF;
}
const mergeBase = tryGit(['merge-base', 'HEAD', 'origin/master']);
if (mergeBase) {
return mergeBase;
}
const originMaster = tryGit(['rev-parse', '--verify', 'origin/master']);
if (originMaster) {
return originMaster;
}
return 'HEAD';
}
function resolveCurrentCrateRoot() {
const manifest = readFileSync(join(repoRoot, moduleManifestPath), 'utf8');
const libSection = /\[lib\]\s*\n([\s\S]*?)(?=\n\[|$)/u.exec(manifest)?.[1] ?? '';
const configuredPath = /^\s*path\s*=\s*"([^"]+)"/mu.exec(libSection)?.[1];
return normalizePath(
configuredPath
? join(dirname(moduleManifestPath), configuredPath)
: join(moduleSrcRoot, 'lib.rs'),
);
}
function childModuleDirectory(sourcePath, isCrateRoot) {
if (isCrateRoot) {
return dirname(sourcePath);
}
const fileName = basename(sourcePath);
if (fileName === 'mod.rs') {
return dirname(sourcePath);
}
return join(dirname(sourcePath), fileName.slice(0, -'.rs'.length));
}
function listReachableCurrentRustFiles() {
const crateRoot = resolveCurrentCrateRoot();
const pending = [{ path: crateRoot, isCrateRoot: true }];
const visited = new Set();
const externalModulePattern = /((?:[ \t]*#\[[^\]\r\n]*\][ \t]*\r?\n)*)[ \t]*(?:pub(?:\([^)]*\))?[ \t]+)?mod[ \t]+([A-Za-z_][A-Za-z0-9_]*)[ \t]*;/gmu;
while (pending.length > 0) {
const current = pending.pop();
if (!current || visited.has(current.path)) {
continue;
}
const absolutePath = join(repoRoot, current.path);
if (!existsSync(absolutePath)) {
continue;
}
visited.add(current.path);
const source = readFileSync(absolutePath, 'utf8');
const defaultModuleDir = childModuleDirectory(current.path, current.isCrateRoot);
let match;
externalModulePattern.lastIndex = 0;
while ((match = externalModulePattern.exec(source)) !== null) {
const attributes = match[1] ?? '';
if (/cfg\s*\(\s*(?:any\s*\(\s*\)|test)\s*\)/u.test(attributes)) {
continue;
}
const moduleName = match[2];
const configuredPath = /#\[\s*path\s*=\s*"([^"]+)"\s*\]/u.exec(attributes)?.[1];
const candidates = configuredPath
? [join(dirname(current.path), configuredPath)]
: [
join(defaultModuleDir, `${moduleName}.rs`),
join(defaultModuleDir, moduleName, 'mod.rs'),
];
const modulePath = candidates
.map(normalizePath)
.find((candidate) => existsSync(join(repoRoot, candidate)));
if (modulePath && !visited.has(modulePath)) {
pending.push({ path: modulePath, isCrateRoot: false });
}
}
}
return [...visited].sort();
}
function listBaseRustFiles(baseRef) {
const output = tryGit(['ls-tree', '-r', '--name-only', baseRef, '--', moduleSrcRoot]);
if (!output) {
return [];
}
return output
.split(/\r?\n/u)
.map(normalizePath)
.filter((path) => path.endsWith('.rs'))
.sort();
}
function readCurrentFile(path) {
return readFileSync(join(repoRoot, path), 'utf8');
}
function readBaseFile(baseRef, path) {
const text = tryGit(['show', `${baseRef}:${path}`]);
return text ?? '';
}
function lineNumberAt(text, index) {
let line = 1;
for (let i = 0; i < index; i += 1) {
if (text[i] === '\n') {
line += 1;
}
}
return line;
}
function findClosingBracket(text, start) {
let depth = 0;
let quote = null;
let escaped = false;
let lineComment = false;
let blockCommentDepth = 0;
for (let i = start; i < text.length; i += 1) {
const char = text[i];
const next = text[i + 1];
if (lineComment) {
if (char === '\n') {
lineComment = false;
}
continue;
}
if (blockCommentDepth > 0) {
if (char === '/' && next === '*') {
blockCommentDepth += 1;
i += 1;
} else if (char === '*' && next === '/') {
blockCommentDepth -= 1;
i += 1;
}
continue;
}
if (quote) {
if (escaped) {
escaped = false;
} else if (char === '\\') {
escaped = true;
} else if (char === quote) {
quote = null;
}
continue;
}
if (char === '/' && next === '/') {
lineComment = true;
i += 1;
continue;
}
if (char === '/' && next === '*') {
blockCommentDepth = 1;
i += 1;
continue;
}
if (char === '"' || char === "'") {
quote = char;
continue;
}
if (char === '[') {
depth += 1;
} else if (char === ']') {
depth -= 1;
if (depth === 0) {
return i + 1;
}
}
}
return -1;
}
function findClosingBrace(text, start) {
let depth = 0;
let quote = null;
let escaped = false;
let lineComment = false;
let blockCommentDepth = 0;
for (let i = start; i < text.length; i += 1) {
const char = text[i];
const next = text[i + 1];
if (lineComment) {
if (char === '\n') {
lineComment = false;
}
continue;
}
if (blockCommentDepth > 0) {
if (char === '/' && next === '*') {
blockCommentDepth += 1;
i += 1;
} else if (char === '*' && next === '/') {
blockCommentDepth -= 1;
i += 1;
}
continue;
}
if (quote) {
if (escaped) {
escaped = false;
} else if (char === '\\') {
escaped = true;
} else if (char === quote) {
quote = null;
}
continue;
}
if (char === '/' && next === '/') {
lineComment = true;
i += 1;
continue;
}
if (char === '/' && next === '*') {
blockCommentDepth = 1;
i += 1;
continue;
}
if (char === '"' || char === "'") {
quote = char;
continue;
}
if (char === '{') {
depth += 1;
} else if (char === '}') {
depth -= 1;
if (depth === 0) {
return i;
}
}
}
return -1;
}
function splitTopLevelSegments(text) {
const segments = [];
let start = 0;
let parenDepth = 0;
let bracketDepth = 0;
let braceDepth = 0;
let angleDepth = 0;
let quote = null;
let escaped = false;
let lineComment = false;
let blockCommentDepth = 0;
for (let i = 0; i < text.length; i += 1) {
const char = text[i];
const next = text[i + 1];
if (lineComment) {
if (char === '\n') {
lineComment = false;
}
continue;
}
if (blockCommentDepth > 0) {
if (char === '/' && next === '*') {
blockCommentDepth += 1;
i += 1;
} else if (char === '*' && next === '/') {
blockCommentDepth -= 1;
i += 1;
}
continue;
}
if (quote) {
if (escaped) {
escaped = false;
} else if (char === '\\') {
escaped = true;
} else if (char === quote) {
quote = null;
}
continue;
}
if (char === '/' && next === '/') {
lineComment = true;
i += 1;
continue;
}
if (char === '/' && next === '*') {
blockCommentDepth = 1;
i += 1;
continue;
}
if (char === '"' || char === "'") {
quote = char;
continue;
}
if (char === '(') {
parenDepth += 1;
} else if (char === ')') {
parenDepth = Math.max(0, parenDepth - 1);
} else if (char === '[') {
bracketDepth += 1;
} else if (char === ']') {
bracketDepth = Math.max(0, bracketDepth - 1);
} else if (char === '{') {
braceDepth += 1;
} else if (char === '}') {
braceDepth = Math.max(0, braceDepth - 1);
} else if (char === '<') {
angleDepth += 1;
} else if (char === '>') {
angleDepth = Math.max(0, angleDepth - 1);
} else if (
char === ',' &&
parenDepth === 0 &&
bracketDepth === 0 &&
braceDepth === 0 &&
angleDepth === 0
) {
segments.push({ text: text.slice(start, i), start });
start = i + 1;
}
}
segments.push({ text: text.slice(start), start });
return segments;
}
function normalizeRustText(text) {
return text.replace(/\s+/gu, ' ').trim();
}
function parseField(segment, fileText, bodyStartIndex) {
const withoutLineComments = segment.text.replace(/\/\/.*$/gmu, '').trim();
if (!withoutLineComments) {
return null;
}
const attrs = [...withoutLineComments.matchAll(/#\[[\s\S]*?\]/gu)].map((match) =>
normalizeRustText(match[0]),
);
const fieldText = withoutLineComments.replace(/#\[[\s\S]*?\]\s*/gu, '').trim();
const fieldMatch =
/^(?:pub(?:\([^)]*\))?\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([\s\S]+)$/u.exec(
fieldText,
);
if (!fieldMatch) {
return null;
}
return {
name: fieldMatch[1],
type: normalizeRustText(fieldMatch[2]),
attrs,
hasDefault: attrs.some((attr) => /^#\[\s*default\b/u.test(attr)),
line: lineNumberAt(fileText, bodyStartIndex + segment.start),
};
}
function parseFields(body, fileText, bodyStartIndex) {
return splitTopLevelSegments(body)
.map((segment) => parseField(segment, fileText, bodyStartIndex))
.filter(Boolean);
}
function parseTablesFromFile(path, text) {
const tables = [];
const tableAttrPattern = /#\[\s*(?:spacetimedb::)?table\s*\(/gu;
let match;
while ((match = tableAttrPattern.exec(text)) !== null) {
const attrStart = match.index;
const attrEnd = findClosingBracket(text, attrStart);
if (attrEnd < 0) {
continue;
}
const attrText = text.slice(attrStart, attrEnd);
const accessorMatch = /accessor\s*=\s*(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))/u.exec(
attrText,
);
const accessor = accessorMatch?.[1] ?? accessorMatch?.[2];
if (!accessor) {
continue;
}
const afterAttr = text.slice(attrEnd, attrEnd + 4000);
const structMatch =
/(?:#\[[\s\S]*?\]\s*)*(?:pub(?:\([^)]*\))?\s+)?struct\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{/u.exec(
afterAttr,
);
if (!structMatch) {
continue;
}
const structStart = attrEnd + structMatch.index;
const structOpenBrace = structStart + structMatch[0].lastIndexOf('{');
const structCloseBrace = findClosingBrace(text, structOpenBrace);
if (structCloseBrace < 0) {
continue;
}
const bodyStartIndex = structOpenBrace + 1;
const body = text.slice(bodyStartIndex, structCloseBrace);
tables.push({
accessor,
structName: structMatch[1],
path,
line: lineNumberAt(text, structStart),
fields: parseFields(body, text, bodyStartIndex),
});
tableAttrPattern.lastIndex = structCloseBrace + 1;
}
return tables;
}
function collectTablesFromSources(sources) {
const tables = new Map();
const failures = [];
for (const source of sources) {
for (const table of parseTablesFromFile(source.path, source.text)) {
const previous = tables.get(table.accessor);
if (previous) {
failures.push(
`${table.path}:${table.line}: SpacetimeDB table accessor ${table.accessor} 重复定义,首次定义在 ${previous.path}:${previous.line}`,
);
continue;
}
tables.set(table.accessor, table);
}
}
return { tables, failures };
}
function loadCurrentSources() {
return listReachableCurrentRustFiles().map((path) => ({
path,
text: readCurrentFile(path),
}));
}
function loadBaseSources(baseRef) {
return listBaseRustFiles(baseRef).map((path) => ({
path,
text: readBaseFile(baseRef, path),
}));
}
function getChangedFiles(baseRef) {
const diffOutput = tryGit(['diff', '--name-only', '-z', baseRef, '--']) ?? '';
const untrackedModuleOutput =
tryGit(['ls-files', '--others', '--exclude-standard', '-z', moduleSrcRoot]) ?? '';
const untrackedBindingsOutput =
tryGit(['ls-files', '--others', '--exclude-standard', '-z', bindingsRoot]) ?? '';
return new Set(
[
...diffOutput.split(String.fromCharCode(0)),
...untrackedModuleOutput.split(String.fromCharCode(0)),
...untrackedBindingsOutput.split(String.fromCharCode(0)),
]
.map(normalizePath)
.filter(Boolean),
);
}
function sameFieldSchema(left, right) {
return (
left.name === right.name &&
left.type === right.type &&
left.attrs.join('\n') === right.attrs.join('\n')
);
}
function fieldDescription(field) {
return `${field.name}: ${field.type}`;
}
function compareTables(baseTables, currentTables) {
const failures = [];
let schemaChanged = false;
let breakingChanged = false;
for (const [accessor, baseTable] of baseTables) {
const currentTable = currentTables.get(accessor);
if (!currentTable) {
schemaChanged = true;
breakingChanged = true;
failures.push(
`${baseTable.path}:${baseTable.line}: SpacetimeDB 表 ${accessor} 被删除或改名。表删除/改名必须先询问用户并确认迁移计划。`,
);
continue;
}
const currentFieldNames = new Set(currentTable.fields.map((field) => field.name));
if (currentTable.fields.length < baseTable.fields.length) {
schemaChanged = true;
breakingChanged = true;
failures.push(
`${currentTable.path}:${currentTable.line}: SpacetimeDB 表 ${accessor} 字段数量减少。删除或改名字段必须先询问用户并确认迁移计划。`,
);
}
for (let index = 0; index < baseTable.fields.length; index += 1) {
const baseField = baseTable.fields[index];
const currentField = currentTable.fields[index];
if (!currentField) {
continue;
}
if (sameFieldSchema(baseField, currentField)) {
continue;
}
schemaChanged = true;
breakingChanged = true;
if (baseField.name !== currentField.name) {
const baseFieldStillExists = currentFieldNames.has(baseField.name);
const reason = baseFieldStillExists ? '字段顺序被调整' : '字段被删除或改名';
failures.push(
`${currentTable.path}:${currentField.line}: SpacetimeDB 表 ${accessor} 的第 ${
index + 1
} 个字段从 ${baseField.name} 变为 ${currentField.name},疑似${reason}。只能在结构体最后追加新字段;改名必须先询问用户并确认迁移计划。`,
);
continue;
}
failures.push(
`${currentTable.path}:${currentField.line}: SpacetimeDB 表 ${accessor}.${currentField.name} 的 schema 从 ${fieldDescription(
baseField,
)} 变为 ${fieldDescription(currentField)}。修改已有字段类型或属性必须先询问用户并确认迁移计划。`,
);
}
if (currentTable.fields.length > baseTable.fields.length) {
schemaChanged = true;
if (!breakingChanged) {
const addedFields = currentTable.fields.slice(baseTable.fields.length);
for (const field of addedFields) {
if (!field.hasDefault) {
failures.push(
`${currentTable.path}:${field.line}: SpacetimeDB 表 ${accessor} 新增字段 ${field.name} 必须放在结构体最后并添加 #[default(...)]。当前字段位于末尾但缺少默认值。`,
);
}
}
}
}
}
for (const accessor of currentTables.keys()) {
if (!baseTables.has(accessor)) {
schemaChanged = true;
}
}
return { failures, schemaChanged, breakingChanged };
}
function checkSchemaSidecars(changedFiles, schemaChanged) {
if (!schemaChanged) {
return [];
}
const failures = [];
if (!changedFiles.has(migrationPath)) {
failures.push(
`SpacetimeDB schema 已变化,但 ${migrationPath} 没有同步变更。row shape 或表变化必须同步迁移导入导出口径。`,
);
}
if (!changedFiles.has(tableCatalogPath)) {
failures.push(
`SpacetimeDB schema 已变化,但 ${tableCatalogPath} 没有同步变更。表结构目录必须跟源码一致。`,
);
}
const bindingsChanged = [...changedFiles].some((path) => path.startsWith(bindingsRoot));
if (!bindingsChanged) {
failures.push(
`SpacetimeDB schema 已变化,但 ${bindingsRoot} 下没有生成绑定变更。请重新生成并提交绑定。`,
);
}
return failures;
}
function main() {
const baseRef = resolveBaseRef();
const currentSources = loadCurrentSources();
const baseSources = loadBaseSources(baseRef);
const currentResult = collectTablesFromSources(currentSources);
const baseResult = collectTablesFromSources(baseSources);
const compareResult = compareTables(baseResult.tables, currentResult.tables);
const changedFiles = getChangedFiles(baseRef);
const sidecarFailures = checkSchemaSidecars(changedFiles, compareResult.schemaChanged);
const compareFailures =
compareResult.breakingChanged && allowBreaking ? [] : compareResult.failures;
const failures = [
...currentResult.failures,
...baseResult.failures,
...compareFailures,
...sidecarFailures,
];
if (compareResult.breakingChanged && !allowBreaking) {
failures.push(
'检测到 SpacetimeDB 字段删除、改名、重排、类型或属性修改。请先询问用户并确认迁移计划;确认后如确需继续,可在人工确认的迁移提交中设置 SPACETIME_SCHEMA_GUARD_ALLOW_BREAKING=1 运行本检查。',
);
}
if (failures.length > 0) {
console.error(`SpacetimeDB schema guard failed against ${baseRef}:`);
for (const failure of failures) {
console.error(`- ${failure}`);
}
process.exit(1);
}
console.log(
`SpacetimeDB schema guard passed for ${currentResult.tables.size} table(s) against ${baseRef}.`,
);
}
main();