validate-ddl: fail-closed 名副其实——非追加式 ALTER 硬拒 + 统一抹除底稿

- mergeAlterStatements 对 MODIFY/CHANGE/RENAME/ALTER/DROP（除 DROP FOREIGN KEY，外键维度已移除故对称放行）登记 unsupportedAlters；CLI 非空即 exit 1 并列出子句。此前静默跳过导致「migration 改了列但 docs/03 未同步」绿灯假阳性——恰是闸门最该抓的场景。未 CREATE 的表同样登记（检测先于 if(!t) 跳过）。parseDDL(text, opts) 不传收集器时行为不变（向后兼容）。 - parseDDL 三遍扫描统一单一抹除底稿（剥注释+抹字面量一次完成，REGEX-3 全覆盖； blankStringLiterals 长度不变故偏移可复用）；顺带修掉第一遍在未抹除底稿上扫描、字面量内 "CREATE TABLE ghost(...)" 产出幽灵表的缺口。 - 测试 52→58：全部拒绝臂参数化覆盖（RENAME/ALTER COLUMN/DROP INDEX/DROP PRIMARY KEY）、混合 ADD+MODIFY（ADD 仍并入且登记）、CLI exit-1 冒烟（spawnSync）、幽灵表回归、DROP FOREIGN KEY 容忍。 - add-req SKILL.md 闸门说明同步硬拒语义，消掉悬空的「见 P2」引用。

validate-ddl: fail-closed 名副其实——非追加式 ALTER 硬拒 + 统一抹除底稿
- mergeAlterStatements 对 MODIFY/CHANGE/RENAME/ALTER/DROP（除 DROP FOREIGN KEY，外键维度已移除故对称放行）登记 unsupportedAlters；CLI 非空即 exit 1 并列出子句。此前静默跳过导致「migration 改了列但 docs/03 未同步」绿灯假阳性——恰是闸门最该抓的场景。未 CREATE 的表同样登记（检测先于 if(!t) 跳过）。parseDDL(text, opts) 不传收集器时行为不变（向后兼容）。 - parseDDL 三遍扫描统一单一抹除底稿（剥注释+抹字面量一次完成，REGEX-3 全覆盖； blankStringLiterals 长度不变故偏移可复用）；顺带修掉第一遍在未抹除底稿上扫描、字面量内 "CREATE TABLE ghost(...)" 产出幽灵表的缺口。 - 测试 52→58：全部拒绝臂参数化覆盖（RENAME/ALTER COLUMN/DROP INDEX/DROP PRIMARY KEY）、混合 ADD+MODIFY（ADD 仍并入且登记）、CLI exit-1 冒烟（spawnSync）、幽灵表回归、DROP FOREIGN KEY 容忍。 - add-req SKILL.md 闸门说明同步硬拒语义，消掉悬空的「见 P2」引用。
zichun
1 parent 94816863
Showing 3 changed files with 116 additions and 17 deletions
lib/validate-ddl.mjs
lib/validate-ddl.test.mjs
skills/plan/add-req/SKILL.md
@@ -140,35 +140,32 @@ const INLINE_KEY_RE = new RegExp(
 // 提取每个 CREATE TABLE 的：列名→类型、索引名集合。
 // 第二遍并入 db-init A.1 强制的独立语句形态（CREATE INDEX，C1）。
-export function parseDDL(text) {
+export function parseDDL(text, opts = {}) {
   const tables = new Map()
-  // 先剥离 SQL 注释，避免被注释掉的 CREATE TABLE 被当成真实表（幽灵表假阳性）。
-  const src = stripSqlComments(String(text))
+  // 剥注释 + 抹字符串字面量，得到单一无害化底稿（REGEX-3 全覆盖）；
+  // blankStringLiterals 保证长度不变 → 偏移可直接用于平衡括号提取。
+  const scanSrc = blankStringLiterals(stripSqlComments(String(text)))
   // 抓取 CREATE TABLE <name> ( <body> ) ；name 反引号可含中文（H3）；body 到匹配的右括号。
   // 支持可选 schema 限定名 `db`.`t` / db.t（取末段为表名，与 docs/03 一致）。
   const createRe = new RegExp(
     'CREATE\\s+(?:(?:GLOBAL|LOCAL)\\s+)?(?:TEMPORARY\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?' +
     '(?:' + IDENT + '\\s*\\.\\s*)?(' + IDENT + ')\\s*\\(', 'gi')
   let m
-  while ((m = createRe.exec(src)) !== null) {
+  while ((m = createRe.exec(scanSrc)) !== null) {
     const tableName = stripTicks(m[1])
     const bodyStart = createRe.lastIndex - 1 // 指向 '('
-    const body = extractBalancedParens(src, bodyStart)
+    const body = extractBalancedParens(scanSrc, bodyStart)
     if (body == null) continue
-    // 抹掉列体内字符串字面量再解析：避免 DEFAULT / COMMENT 里出现 "KEY …" 文本被
-    // 内联检测误当真实约束（REGEX-3）；反引号标识符整段保留，列名/类型解析不读字面量内容，故不受影响。
-    tables.set(tableName, parseTableBody(blankStringLiterals(body)))
+    tables.set(tableName, parseTableBody(body))
     // 继续从 body 之后扫描
     createRe.lastIndex = bodyStart + body.length + 2
   }
   // 第二遍：db-init A.1/A.2 强制 DDL 形态为 CREATE TABLE → CREATE INDEX，
   // 索引写在表体之外。把这些独立语句并回对应表，否则含索引的 schema 首轮校验必报假阳性（C1）。
-  // 扫描前先抹掉字符串字面量内部，避免 DEFAULT / COMMENT 里的 "CREATE INDEX …" 文本被误当语句（REGEX-3）。
-  const scanSrc = blankStringLiterals(src)
   mergeStandaloneIndexes(scanSrc, tables)
   // 第三遍：增量 migration（V2+）的 ALTER TABLE ADD COLUMN / ADD [UNIQUE] INDEX|KEY 并入对应表。
-  mergeAlterStatements(scanSrc, tables)
+  mergeAlterStatements(scanSrc, tables, opts.unsupportedAlters)
   return tables
 }
@@ -178,7 +175,7 @@ export function parseDDL(text) {
 // docs/03 是累积 SSoT，列/索引最终集合 = V1 CREATE + 各 V_n ADD 的并集，与文件顺序无关，
 // 故对 `validate-ddl docs/03 sql/migrations/V*.sql`（glob 按字典序展开）的并集校验成立。
 // 表未在所提供 DDL 中 CREATE → 跳过（表集合维度另报缺，不凭空造表，与 mergeStandaloneIndexes 一致）。
-function mergeAlterStatements(src, tables) {
+function mergeAlterStatements(src, tables, unsupported) {
   const re = new RegExp('ALTER\\s+TABLE\\s+(?:' + IDENT + '\\s*\\.\\s*)?(' + IDENT + ')\\s+', 'gi')
   let m
   while ((m = re.exec(src)) !== null) {
@@ -191,11 +188,21 @@ function mergeAlterStatements(src, tables) {
     const nextStmt = src.slice(bodyStart).search(/\b(?:ALTER|CREATE|DROP)\s+TABLE\b/i)
     if (nextStmt !== -1) cand.push(bodyStart + nextStmt)
     const end = cand.length ? Math.min(...cand) : src.length
-    const t = tables.get(tbl)
-    if (!t) continue
     for (const clauseRaw of splitTopLevelCommas(src.slice(bodyStart, end))) {
       const clause = clauseRaw.trim()
       if (!clause) continue
+      // 非追加式子句 → 登记给调用方 fail-closed 硬拒。静默放行会让「migration 改了列但
+      // docs/03 未同步」假阳性通过——这恰是闸门最该抓的场景。DROP FOREIGN KEY 例外：
+      // 外键维度已移除，与下方 ADD CONSTRAINT/FOREIGN 的跳过对称。
+      // ALTER（COLUMN ... SET/DROP DEFAULT 等）虽不动 4 维，仍硬拒：解析器无法廉价证明
+      // 某条 ALTER 子句是 4 维中性的，故对整个 ALTER 动词 fail-closed，逃生口见 CLI 第三行文案。
+      if (/^(?:MODIFY|CHANGE|RENAME|ALTER)\b/i.test(clause) ||
+          (/^DROP\b/i.test(clause) && !/^DROP\s+FOREIGN\s+KEY\b/i.test(clause))) {
+        if (unsupported) unsupported.push({ table: tbl, clause: clause.length > 80 ? clause.slice(0, 77) + '…' : clause })
+        continue
+      }
+      const t = tables.get(tbl)
+      if (!t) continue // 表未 CREATE：表集合维度另行报缺，不凭空造表
       const idxM = clause.match(new RegExp('^ADD\\s+(UNIQUE\\s+)?(?:INDEX|KEY)\\s+(' + IDENT + ')\\s*\\(', 'i'))
       if (idxM) {
         const kind = idxM[1] ? 'UNIQUE' : 'INDEX'
@@ -212,7 +219,7 @@ function mergeAlterStatements(src, tables) {
         if (colM[1] !== '`' && /^(?:KEY|INDEX|UNIQUE|FULLTEXT|SPATIAL|PRIMARY|CONSTRAINT|CHECK|FOREIGN|COLUMN)$/i.test(name)) continue
         t.columns.set(name, extractType(colM[3]))
       }
-      // 其它（MODIFY/CHANGE/DROP/RENAME/ALTER COLUMN）→ 追加式校验不处理，跳过。
+      // 其它子句（不可识别的 ADD 变体等）→ 静默跳过。
     }
   }
 }
@@ -550,7 +557,14 @@ if (isCliEntry) {
   // 多个 migration（V1 + V_n...）拼成单一多语句文本：parseDDL 三遍扫描天然按 CREATE→ALTER
   // 累积出最终 schema；追加式 ALTER 与文件顺序无关，故 glob 字典序展开（V1,V10,V2...）也正确。
   const ddlText = ddlPaths.map(p => readFileSync(p, 'utf8')).join('\n;\n')
-  const ddlTables = parseDDL(ddlText)
+  const unsupportedAlters = []
+  const ddlTables = parseDDL(ddlText, { unsupportedAlters })
+  if (unsupportedAlters.length) {
+    console.error('validate-ddl: ✗ 仅支持追加式 migration（ALTER TABLE ... ADD COLUMN/INDEX/PRIMARY KEY），发现不支持的子句：')
+    for (const u of unsupportedAlters) console.error(`  - ${u.table}: ${u.clause}`)
+    console.error('  改类型/重命名/删列请人工写 V_n 并人工核对 docs/03 一致性后，不经本校验直接评审。')
+    process.exit(1)
+  }
   const diff = diffSchema(docsTables, ddlTables)
   if (diff.hasDiff) {
@@ -592,3 +592,88 @@ test(&#39;parseDDL: DEFAULT å—é¢é‡é‡Œçš„ &quot;ALTER TABLE ...&quot; æ–‡æœ¬ä¸è¢«è¯¯å½“çœŸå
   const t = parseDDL(ddl).get('t_z')
   assert.deepEqual([...t.columns.keys()], ['iId', 'sNote']) // æ—  hacked åˆ—
 })
+
+// â”€â”€ éžè¿½åŠ å¼ ALTER ç¡¬æ‹’ï¼ˆfail-closedï¼‰â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
+test('å¢žé‡æ ¡éªŒï¼šALTER MODIFY è¢«ç™»è®°ä¸ºä¸æ”¯æŒï¼ˆä¸é™é»˜æ”¾è¡Œï¼‰', () => {
+  const un = []
+  parseDDL('CREATE TABLE `t`(`c` int);\nALTER TABLE `t` MODIFY `c` bigint;', { unsupportedAlters: un })
+  assert.equal(un.length, 1)
+  assert.equal(un[0].table, 't')
+  assert.match(un[0].clause, /^MODIFY/i)
+})
+
+test('å¢žé‡æ ¡éªŒï¼šCHANGE / DROP COLUMN ç™»è®°ï¼›DROP FOREIGN KEY å®¹å¿è·³è¿‡', () => {
+  const un = []
+  parseDDL([
+    'CREATE TABLE `t`(`c` int);',
+    'ALTER TABLE `t` CHANGE `c` `c2` int;',
+    'ALTER TABLE `t` DROP COLUMN `c`;',
+    'ALTER TABLE `t` DROP FOREIGN KEY `fk_x`;',
+  ].join('\n'), { unsupportedAlters: un })
+  assert.equal(un.length, 2)
+})
+
+test('å¢žé‡æ ¡éªŒï¼šæœªä¼ æ”¶é›†å™¨æ—¶è¡Œä¸ºä¸å˜ï¼ˆå‘åŽå…¼å®¹ï¼‰', () => {
+  const tables = parseDDL('CREATE TABLE `t`(`c` int);\nALTER TABLE `t` MODIFY `c` bigint;')
+  assert.equal(tables.get('t').columns.get('c'), 'int')
+})
+
+test('å¢žé‡æ ¡éªŒï¼šRENAME/ALTER COLUMN/DROP INDEX/DROP PRIMARY KEY å„è‡‚å‡ç™»è®°ï¼›æ··åˆ ADD+MODIFY æ—¶ ADD ä»å¹¶å…¥', () => {
+  for (const clause of [
+    'RENAME COLUMN `c` TO `c2`',
+    'RENAME TO `t2`',
+    'ALTER COLUMN `c` SET DEFAULT 1',
+    'DROP INDEX `idx_x`',
+    'DROP PRIMARY KEY',
+  ]) {
+    const un = []
+    parseDDL('CREATE TABLE `t`(`c` int);\nALTER TABLE `t` ' + clause + ';', { unsupportedAlters: un })
+    assert.equal(un.length, 1, clause)
+  }
+  const un = []
+  const tables = parseDDL('CREATE TABLE `t`(`c` int);\nALTER TABLE `t` ADD COLUMN `d` int, MODIFY `c` bigint;', { unsupportedAlters: un })
+  assert.equal(un.length, 1)
+  assert.ok(tables.get('t').columns.has('d'))
+})
+
+test('REGEX-3ï¼šè¡¨ä½“ä¹‹å¤–å—ç¬¦ä¸²å—é¢é‡ä¸çš„ CREATE TABLE ä¸äº§å‡ºå¹½çµè¡¨', () => {
+  const tables = parseDDL("CREATE TABLE `real`(`a` int);\nINSERT INTO log VALUES ('CREATE TABLE ghost (a int)');")
+  assert.ok(tables.has('real'))
+  assert.ok(!tables.has('ghost'))
+})
+
+test('CLI exit-1ï¼šmigration å« MODIFY æ—¶é€€å‡ºç ä¸º 1 ä¸” stderr å«ã€Œä¸æ”¯æŒçš„åå¥ã€', async () => {
+  const { spawnSync } = await import('node:child_process')
+  const { mkdtempSync, writeFileSync, mkdirSync } = await import('node:fs')
+  const { join } = await import('node:path')
+  const { tmpdir } = await import('node:os')
+
+  const dir = mkdtempSync(join(tmpdir(), 'validate-ddl-cli-'))
+  // docs/03 æ ¼å¼ï¼šä¸€å¼ è¡¨ä¸¤åˆ—
+  const docsContent = [
+    '## `t_order` â€” è®¢å•ä¸»è¡¨',
+    '',
+    '### å—æ®µ',
+    '',
+    '| å—æ®µ | ç±»åž‹ | Nullable | é»˜è®¤ | ä¸šåŠ¡å«ä¹‰ |',
+    '|---|---|---|---|---|',
+    '| `iId` | bigint | å¦ | è‡ªå¢ž | ä¸»é”® |',
+    '| `sCode` | varchar(50) | å¦ | â€” | ç¼–ç  |',
+    '',
+  ].join('\n')
+  const docsPath = join(dir, 'docs-03.md')
+  writeFileSync(docsPath, docsContent)
+
+  // V1ï¼šåˆ›å»ºè¡¨
+  const v1Path = join(dir, 'V1.sql')
+  writeFileSync(v1Path, 'CREATE TABLE `t_order` (`iId` bigint PRIMARY KEY, `sCode` varchar(50));\n')
+
+  // V2ï¼šå« MODIFYï¼ˆéžè¿½åŠ å¼ï¼‰â†’ è§¦å‘ exit-1
+  const v2Path = join(dir, 'V2.sql')
+  writeFileSync(v2Path, 'ALTER TABLE `t_order` MODIFY `sCode` varchar(100);\n')
+
+  const cliPath = new URL('./validate-ddl.mjs', import.meta.url).pathname
+  const result = spawnSync(process.execPath, [cliPath, docsPath, v1Path, v2Path], { encoding: 'utf8' })
+  assert.equal(result.status, 1, 'exit code should be 1 â€” stderr: ' + result.stderr)
+  assert.ok(result.stderr.includes('ä¸æ”¯æŒçš„åå¥'), 'stderr should mention ä¸æ”¯æŒçš„åå¥ â€” got: ' + result.stderr)
+})
@@ -81,7 +81,7 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs scan &lt;root&gt;
    （validate-ddl 已支持多文件：CREATE TABLE + 各 V_n 的 `ALTER ... ADD` 并集 ↔ docs/03 累积 SSoT 做 4 维比对。）
    - 退出码 `0` → 一致，继续。
    - 退出码 `1` → docs/03 与 migration 并集分叉（stderr 有 diff 明细）：**就地修正**——通常是 docs/03 表小节/列与 V_n 不一致，或 V_n 漏写某列的 ALTER。修正后重跑校验，直到 `0`。**绝不带分叉进入步骤 4**（schema 不一致会让下游 docs/05/编码全线偏）。
-   - 仅 ADD 追加式（改类型/重命名/删列暂不在 add-req 覆盖范围，见 P2）。
+   - 仅 ADD 追加式——校验器对 `MODIFY/CHANGE/DROP/RENAME` 子句**硬拒（exit 1）**，不静默放行。改类型/重命名/删列不在 add-req 覆盖范围：需人工写 V_n 并人工核对 docs/03 一致性。
 > **不在此 apply 到数据库**：新 schema 由 Coding 阶段冷起栈时 Flyway 自动 apply 全部 `V*.sql`；本步只做静态 DDL↔docs/03 一致性校验，运行时 apply 与 Seed 真跑由 Coding 阶段兜底。