FlowScope 仓库的辅助脚本集合。所有脚本必须从仓库根目录调用（./scripts/xxx），脚本内部已固定 cd "$(dirname "$0")/.." 或假设 cwd 为 repo root。

每个脚本都有"自动入口"和"手动入口"两种用法。自动入口是 just <target> / pre-commit / CI；手动入口是 ./scripts/xxx。新代码请优先用自动入口，自动入口出问题再降级手动调试。

编译 Rust workspace（release）+ WASM 模块，并把 WASM 产物同步到 3 个位置：

• packages/core/wasm/（npm 发布目录，提交进 git）
• packages/core/src/wasm（指向上面目录的 symlink，给 TS import 用）
• app/public/wasm/（Vite dev server 直接对外服务）

⚠️ 依赖 wasm-pack，没装先跑 just install-rust-tools。

从 Rust 的 flowscope-core::schema_guard 测试里抽出 AnalyzeRequest/AnalyzeResult 等 schema JSON，写入 docs/api_schema.json。前后端用它做契约一致性校验。

pre-commit 钩子：跑 update_api_schema.cjs 后用 git diff 检查 docs/api_schema.json 是否被改动；如果改动了说明 Rust 改了 schema 但没同步 docs，直接 fail commit。

线上 Neo4j 服务器侧使用，一键"停旧 → nohup 启新 → 健康检查 → 报告退出码"。健壮性要点：

• pid 文件 + 端口占用进程双重 kill（兜底 lsof / ss / fuser）
• SIGTERM 10s 超时后强制 SIGKILL（可调 SHUTDOWN_TIMEOUT_SEC）
• 启动后 30s 内每秒重试 /api/health（可调 HEALTH_TIMEOUT_SEC）
• 新进程刚启就崩 → tail -30 日志 + 退出码 2
• 日志自动归档为 *.log.YYYYMMDD-HHMMSS.bak，不会无限增长

环境变量（全部可覆盖）：

退出码：

./scripts/serve-restart.sh                     # 用默认参数重启
PORT=8080 ./scripts/serve-restart.sh           # 覆盖端口
AUDIT_LOG=/data/audit.db ./scripts/serve-restart.sh

线上停服。pid 文件 + 端口占用 双重 kill，幂等（已停止时返回 0）。

./scripts/serve-stop.sh         # 默认 PORT=7681
PORT=8080 ./scripts/serve-stop.sh

把任意文件上传到 https://upload.zhenguanyu.com/upfile，返回 CDN URL，并下载远端副本对比 sha256（不一致直接 exit 1）。

• 原本只给 H5 前端 zip 用，现已扩展到任意文件（CLI 二进制、tar、原始 binary 都行）。
• 默认上限 200MB（覆盖当前 ~72MB 的 flowscope binary），需要更大用 UPLOAD_MAX_MB=500。
• 不带参数时自动选 repo 根目录最新的 flowscope-h5-*.zip。

完整发布流程参考 docs/release-workflow.md 和 .cursor/commands/build-and-upload.md。

跑 release CLI 把 test-sql/ 下每个 SQL 跑一遍，验证：

• CLI 返回 0 + 输出合法 JSON
• issues 无 error（warning 容忍但会报告）
• statements 至少 1 个（防止 SET/USE 等被全部过滤后留空）
• 若 test-sql/.regression-expect.json 钉了字段（sqlType/insertType/targetTable/sourceTables/statementTypes/errorCount），做严格 match

新 fixture 拖进 test-sql/ 即自动入套件（无 expect 时只跑软检查）。

读 SQLFluff 源码里的 test/fixtures/rules/std_rule_cases/*.yml，对每个 case：

• pass_str → 验证 FlowScope 不报该规则
• fail_str → 验证 FlowScope 报该规则
• fix_str → 对比 FlowScope --fix 输出与期望

依赖 SQLFluff 源码 checkout 的 .venv/bin/python（含 PyYAML）。

在真实 SQL 语料上同时跑 FlowScope 和 SQLFluff，输出：

• 总违规数 before/after 对比
• 每条规则 before/after 增量
• 各规则的 parity gap（SQLFluff 修了多少 vs FlowScope 修了多少）
• FlowScope 的 fix 遥测（applied / skipped / blocked 候选分布）
• SQLFluff 的 fixability 摘要

LT02 缩进规则专项对比 workbench（sql-corpus-parity-report.py 的窄版）：

• LT02 only 模式跑两侧
• 报告 LT02 修复前后计数 / parity gap / fix 遥测
• 列出 FlowScope 修复后残留的 LT02 issue 分组
• 输出 per-file / per-line 与 SQLFluff 的分歧

在 SQL 语料上 benchmark FlowScope 的 fix 性能。默认 batch 模式（一次性 CLI 调用覆盖整个目录，避免 per-file 进程开销，匹配真实使用场景）。

1. 文件名：日常 = kebab-case，Python 偶有 snake_case 历史遗留可保留
2. shebang：bash → #!/usr/bin/env bash + set -euo pipefail；Python → #!/usr/bin/env python3
3. 可执行权限：chmod +x 之后再 git add
4. cwd：脚本顶部 cd "$(dirname "$0")/.." 确保从仓库根目录运行
5. 自动入口：除非真的一次性，否则在 justfile 加一行 wrapper
6. README：在本文件对应章节加一段（用途 / 入口 / 关键参数 / 退出码）
7. CI 引用：如果被 .github/workflows/ci.yml 引用，README 标明"CI 跑"