lib: drop duplicated headers, JSDoc restatements, CLI-entry comments; reuse advanceLiteral helper

zichun
1 parent d61c07b1
Showing 4 changed files with 20 additions and 78 deletions
lib/apply-ddl.mjs
lib/merge-gitignore.mjs
lib/render.mjs
lib/validate-ddl.mjs
-// lib/apply-ddl.mjs
-//
-// Replaces the inline `set -a; . .env.local; mysql < V1.sql` bash from db-init.
-//
-// parseEnv(): dotenv-style line parser. Pure parsing, NO variable expansion and
-// NO shell execution — `$VAR`, backticks, `$(...)` and other shell constructs are
-// kept verbatim as literal characters, which eliminates the shell-injection vector
-// of `source`-ing an untrusted .env file.
-//
-// applyDDL(): connects with mysql2/promise (multipleStatements) to run a DDL file.
-
 /**
  * Parse dotenv-style text into a plain object.
  *
@@ -60,14 +49,6 @@ export function parseEnv(text) {
 /**
  * Apply a DDL file to a MySQL database using mysql2/promise.
  *
- * Reads connection settings from the parsed env file. Recognised keys (with
- * common aliases) — DB_HOST/MYSQL_HOST, DB_PORT/MYSQL_PORT, DB_USER/MYSQL_USER,
- * DB_PASS/DB_PASSWORD/MYSQL_PASSWORD, DB_SCHEMA/DB_NAME/MYSQL_DATABASE.
- * DB_SCHEMA is the plugin's canonical schema key (see .env.local template); the
- * target database MUST resolve to a non-empty value or applyDDL fails closed —
- * V1 DDL contains no `USE`/`CREATE DATABASE`, so a missing schema would only
- * surface as an opaque `ER_NO_DB_ERROR` on the first CREATE TABLE.
- *
  * @param {{envPath: string, ddlPath: string}} opts
  * @returns {Promise<void>}
  */
@@ -104,9 +85,7 @@ export async function applyDDL({ envPath, ddlPath }) {
  * Resolve mysql2 connection settings from a parsed env object. Pure (no I/O),
  * so it is unit-testable without mysql2 installed.
  *
- * fail-closed on missing schema: DB_SCHEMA is the plugin's canonical key; V1 DDL
- * has no `USE`/`CREATE DATABASE`, so a missing database would otherwise surface
- * only as an opaque ER_NO_DB_ERROR on the first CREATE TABLE.
+ * Throws if no schema resolves — V1 has no USE/CREATE DATABASE.
  *
  * @param {Record<string,string>} env
  * @param {string} [envPath] only used to make the error message actionable
@@ -132,9 +111,7 @@ export class MysqlUnavailableError extends Error {
   }
 }
-// CLI entry: node lib/apply-ddl.mjs <envPath> <ddlPath>
-// Use pathToFileURL so the guard matches even when the path contains spaces or
-// other characters that get percent-encoded in import.meta.url.
+// CLI entry guard (see render.mjs for pathToFileURL rationale)
 const { pathToFileURL } = await import('node:url')
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const [envPath, ddlPath] = process.argv.slice(2)
 // lib/merge-gitignore.mjs
 // 合并两份 .gitignore，对**规则行**逐行判重并集合并；注释行透传（相邻去重），空行丢弃（节由注释头承担）。
-// 之所以不对注释去重：两段分组各自的同名注释头（如多次出现的 `# generated`）是分节标题，
-// 全局去重会把第二段的标题吞掉，让 add 文件的规则被并入第一段的注释下、破坏分节语义。
 export function mergeGitignore(baseText, addText) {
   const seenRules = new Set()
   const out = []
@@ -25,10 +23,7 @@ export function mergeGitignore(baseText, addText) {
   return text
 }
-// CLI entry: node lib/merge-gitignore.mjs <basePath> <addPath>
-// Use pathToFileURL so the guard matches even when the path contains spaces or
-// non-ASCII chars (import.meta.url is percent-encoded; process.argv[1] is raw).
-const { pathToFileURL } = await import('node:url')
+const { pathToFileURL } = await import('node:url') // CLI entry guard (see render.mjs)
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const [basePath, addPath] = process.argv.slice(2)
   const { readFileSync, writeFileSync } = await import('node:fs')
 // lib/render.mjs — literal-safe template render (replaces scope-lock/render.sh)
 //
-// 用法（CLI）：node lib/render.mjs <tplPath> <varsJsonPath> <outPath>
-// 程序内：import { render } from './render.mjs'
-//
 // 核心要求：{{key}} 占位替换；值中含 $、{、}、}} 不被二次解释（字面插入）；
 // 先剥离 HTML 注释（模板引导文本）；缺少变量则 throw（不静默留空）。
 export function render(template, vars) {
 // lib/validate-ddl.mjs — docs/03 表格 ↔ DDL（V1.sql）一致性 5 维校验
 // 替换 db-init/scripts/validate.sh（跨平台、纯 Node、零外部依赖）。
-// 语法基线偏向 MySQL 8（int/varchar/json 等 ANSI + MySQL 类型；KEY/UNIQUE KEY 索引语法）。
-// 厂商扩展（Postgres `bytea`、Oracle `nvarchar2` 等）未列入 SQL_TYPE_RE，下游解析可能退化为
-// 跳过整项（fix #2 起 KEY/INDEX 项遇未知类型保留字会跳过而非误判为列）。
 //
 // 用法（CLI）：node lib/validate-ddl.mjs <docs03Path> <ddlPath>
 //   退出码 0 = 一致；1 = 存在差异（diff 明细打印到 stderr）；2 = 用法/路径错误。
 // 程序内：import { parseDocsTables, parseDDL, diffSchema } from './validate-ddl.mjs'
 //
-// 5 维 diff：
-//   1) 表集合（missingTables / extraTables）
-//   2) 列名（columnMismatches，side: 'docs'|'ddl'）
-//   3) 列类型（typeMismatches）
-//   4) 索引（indexMismatches，side: 'docs'|'ddl'）
-//   5) 外键（foreignKeyMismatches，side: 'docs'|'ddl'）
-//
 // 数据结构（解析结果）：Map<tableName, {
 //   columns: Map<colName, type>, indexes: Set<string>, foreignKeys: Set<string> }>
@@ -102,10 +92,6 @@ function parseIndexBullet(line, indexes) {
 // 解析外键 bullet：  - `name`: from_col → to_table.to_col (on_delete)
 // 归一化为 parseDDL 同形的 `${fromCols}->${toTable}(${toCols})`（注意 docs 用 unicode → / DDL 用 ->）。
-// 复合外键的两种合法 docs 写法都支持，避免与 DDL 侧的 `(idA, idB)` 形态不对称：
-//   - `fk`: colA, colB → other.idA, idB                   ← 平铺，到列也是逗号分隔
-//   - `fk`: colA, colB → other.(idA, idB)                 ← 目标列括起
-//   - `fk`: colA, colB → other.`idA`,`idB`                ← 各列各带反引号
 function parseForeignKeyBullet(line, foreignKeys) {
   // 1) 先把头部 `- `name`: ... → table` 抠出来，保留"目标表后剩余的尾段"用于解析目标列（可能是
   //    `.idA`、`.idA, idB`、`.(idA, idB)` 或 `.`idA`,`idB``）。
@@ -209,8 +195,6 @@ function parseTableBody(body) {
         indexes.add(`${nameMatch[1]}:${kind}:${cols}`)
         continue
       }
-      // 命名是类型关键字 / 无法定位 → 回退到列定义解析；
-      // 列正则下游会拒绝以保留字开头的列名（fix #2）。
     }
     // CONSTRAINT <name> 但非外键（如 UNIQUE/CHECK 约束）→ 当索引/约束记
     if (/^CONSTRAINT\b/i.test(upper)) {
@@ -249,7 +233,6 @@ function extractType(rest) {
   return base + paren + mod
 }
-// ── 5 维 diff ────────────────────────────────────────────────────
 export function diffSchema(docsTables, ddlTables) {
   const diff = {
     missingTables: [],       // docs 有、DDL 无
@@ -264,8 +247,7 @@ export function diffSchema(docsTables, ddlTables) {
   const docNames = new Set(docsTables.keys())
   const ddlNames = new Set(ddlTables.keys())
-  for (const t of docNames) if (!ddlNames.has(t)) diff.missingTables.push(t)
-  for (const t of ddlNames) if (!docNames.has(t)) diff.extraTables.push(t)
+  symDiff(docNames, ddlNames, t => diff.missingTables.push(t), t => diff.extraTables.push(t))
   diff.missingTables.sort()
   diff.extraTables.sort()
@@ -293,14 +275,14 @@ export function diffSchema(docsTables, ddlTables) {
     // 表内体现 PK、不在 ### 索引 重列 → 从两侧索引集剔除 PRIMARY，避免假阳性；命名二级索引仍比对。
     const dIdx = new Set([...(d.indexes || [])].filter(ix => ix !== 'PRIMARY'))
     const sIdx = new Set([...(s.indexes || [])].filter(ix => ix !== 'PRIMARY'))
-    for (const ix of dIdx) if (!sIdx.has(ix)) diff.indexMismatches.push({ table: t, index: ix, side: 'docs' })
-    for (const ix of sIdx) if (!dIdx.has(ix)) diff.indexMismatches.push({ table: t, index: ix, side: 'ddl' })
+    symDiff(dIdx, sIdx,
+      ix => diff.indexMismatches.push({ table: t, index: ix, side: 'docs' }),
+      ix => diff.indexMismatches.push({ table: t, index: ix, side: 'ddl' }))
     // 维度 5：外键
-    const dFk = d.foreignKeys || new Set()
-    const sFk = s.foreignKeys || new Set()
-    for (const fk of dFk) if (!sFk.has(fk)) diff.foreignKeyMismatches.push({ table: t, foreignKey: fk, side: 'docs' })
-    for (const fk of sFk) if (!dFk.has(fk)) diff.foreignKeyMismatches.push({ table: t, foreignKey: fk, side: 'ddl' })
+    symDiff(d.foreignKeys || new Set(), s.foreignKeys || new Set(),
+      fk => diff.foreignKeyMismatches.push({ table: t, foreignKey: fk, side: 'docs' }),
+      fk => diff.foreignKeyMismatches.push({ table: t, foreignKey: fk, side: 'ddl' }))
   }
   diff.hasDiff = diff.missingTables.length > 0 || diff.extraTables.length > 0 ||
@@ -309,7 +291,6 @@ export function diffSchema(docsTables, ddlTables) {
   return diff
 }
-// ── 工具函数 ─────────────────────────────────────────────────────
 // 剥离 SQL 注释：-- 行注释（到行尾）、# 行注释（到行尾）、/* */ 块注释。
 // **字符串字面量感知**：单引号 / 双引号 / 反引号字面量内部的注释符按原文保留（DEFAULT 'a--b' /
 // DEFAULT '#tag' 之类不会被错剥成"列丢失"）。转义引号支持 SQL 标准的 '' 与反斜杠 \\'。
@@ -322,19 +303,9 @@ function stripSqlComments(sql) {
     const next = s[i + 1]
     // 进入字符串 / 反引号：原样吐出整个字面量
     if (ch === "'" || ch === '"' || ch === '`') {
-      const q = ch
-      out += ch
-      i++
-      while (i < s.length) {
-        const c = s[i]
-        // SQL 标准的双引号转义：'' 或 ""
-        if (c === q && s[i + 1] === q) { out += c + c; i += 2; continue }
-        // 反斜杠转义：\' / \" / \\ 等（MySQL 默认开启 NO_BACKSLASH_ESCAPES 才禁，保守按开启处理）
-        if (c === '\\' && i + 1 < s.length && q !== '`') { out += c + s[i + 1]; i += 2; continue }
-        out += c
-        i++
-        if (c === q) break
-      }
+      const end = advanceLiteral(s, i)
+      out += s.slice(i, end)
+      i = end
       continue
     }
     // /* ... */ 块注释（吞到下一个 */）
@@ -453,7 +424,12 @@ function typesEqual(a, b) {
   return norm(a) === norm(b)
 }
-// ── 报告（供 CLI 与外部复用）────────────────────────────────────
+// 集合对称差：对 left\right 调用 onlyLeft，对 right\left 调用 onlyRight。
+function symDiff(left, right, onlyLeft, onlyRight) {
+  for (const x of left) if (!right.has(x)) onlyLeft(x)
+  for (const x of right) if (!left.has(x)) onlyRight(x)
+}
+
 export function formatDiff(diff) {
   const out = []
   if (diff.missingTables.length) {
@@ -491,10 +467,7 @@ export function formatDiff(diff) {
   return out.join('\n')
 }
-// ── CLI 入口 ─────────────────────────────────────────────────────
-// 用 pathToFileURL 做比较：路径含空格/非 ASCII 时 import.meta.url 是百分号编码，
-// 而 process.argv[1] 是原始路径，直接 `file://${argv1}` 拼接永远不相等。
-const { pathToFileURL } = await import('node:url')
+const { pathToFileURL } = await import('node:url') // CLI entry guard (see render.mjs)
 const isCliEntry = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
 if (isCliEntry) {
   const { readFileSync, existsSync } = await import('node:fs')