@hodela/site 0.3.1 → 0.4.0

package/dist/migration-rules.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Luật cho từng câu lệnh trong migration. MỘT bản duy nhất: nền tảng (kiểm tra khi upload và khi build) và công cụ của developer
+ * (`hodela-dev check`) dùng chung gói này (subpath `migration-rules`), nên "máy dev báo qua" nghĩa là nền tảng cũng cho qua. Migration chỉ được tạo thêm, không phá dữ liệu.
+ * Đây là rào chắn chống tai nạn (agent lỡ DROP/DELETE), không phải ranh giới bảo mật:
+ * mỗi website chạy trên database riêng của nó.
+ */
+import { type SqlDialect, type SqlStatement } from "./sql-split.js";
+export type IssueCode = "bad_file_name" | "duplicate_number" | "file_too_large" | "syntax" | "statement_not_allowed" | "update_without_where" | "reserved_name" | "dialect_syntax" | "empty_file";
+export type Issue = {
+    code: string;
+    message: string;
+    file?: string | undefined;
+    line?: number | undefined;
+};
+export declare const MIGRATION_NAME_RE: RegExp;
+export declare const MAX_MIGRATION_BYTES: number;
+export declare const MAX_MIGRATION_FILES = 200;
+/** Kiểm tra một câu lệnh. Trả về null nếu hợp lệ. */
+export declare function classifyStatement(file: string, stmt: SqlStatement, dialect: SqlDialect): Issue | null;
+export type ParsedMigration = {
+    name: string;
+    number: string;
+    sql: string;
+    statements: SqlStatement[];
+};
+/** Tên file, kích thước, cú pháp, từng câu lệnh. Không chạm vào database. */
+export declare function analyzeMigrations(files: Array<{
+    name: string;
+    sql: string;
+}>, dialect: SqlDialect): {
+    migrations: ParsedMigration[];
+    issues: Issue[];
+};

package/dist/migration-rules.js

@@ -0,0 +1,148 @@
+/**
+ * Luật cho từng câu lệnh trong migration. MỘT bản duy nhất: nền tảng (kiểm tra khi upload và khi build) và công cụ của developer
+ * (`hodela-dev check`) dùng chung gói này (subpath `migration-rules`), nên "máy dev báo qua" nghĩa là nền tảng cũng cho qua. Migration chỉ được tạo thêm, không phá dữ liệu.
+ * Đây là rào chắn chống tai nạn (agent lỡ DROP/DELETE), không phải ranh giới bảo mật:
+ * mỗi website chạy trên database riêng của nó.
+ */
+import { splitSqlStatements, SqlSyntaxError } from "./sql-split.js";
+export const MIGRATION_NAME_RE = /^(\d{4})_[a-z0-9_]+\.sql$/;
+export const MAX_MIGRATION_BYTES = 256 * 1024;
+export const MAX_MIGRATION_FILES = 200;
+const RESERVED_NAME_RE = /^(_hodela_|sqlite_|_cf_|d1_)/i;
+const HINT_DESTRUCTIVE = "Migration chỉ được thêm, không xóa dữ liệu hay cấu trúc. Muốn bỏ một cột hoặc bảng: ngừng dùng nó trong code và để nguyên trong database.";
+function words(stmt) {
+    return stmt.tokens.filter((t) => t.kind === "word").map((t) => t.text);
+}
+function fail(file, stmt, code, message) {
+    return { code, message, file, line: stmt.line };
+}
+/** Kiểm tra một câu lệnh. Trả về null nếu hợp lệ. */
+export function classifyStatement(file, stmt, dialect) {
+    const w = words(stmt);
+    const first = w[0] ?? "";
+    for (const t of stmt.tokens) {
+        if ((t.kind === "word" || t.kind === "ident") && RESERVED_NAME_RE.test(t.text)) {
+            return fail(file, stmt, "reserved_name", `Tên "${t.text}" do hệ thống giữ riêng, đừng tạo hay đụng tới.`);
+        }
+    }
+    switch (first) {
+        case "CREATE": {
+            let i = 1;
+            if (w[i] === "UNIQUE")
+                i += 1;
+            const what = w[i];
+            if (what === "TEMP" || what === "TEMPORARY") {
+                return fail(file, stmt, "statement_not_allowed", "Không dùng bảng tạm (TEMP) trong migration.");
+            }
+            if (what === "TABLE") {
+                if (dialect === "mysql" && /\bTEXT\b[^,)]*\b(PRIMARY|UNIQUE)\b/i.test(stmt.sql)) {
+                    return fail(file, stmt, "dialect_syntax", "MySQL không cho TEXT làm khóa chính hoặc UNIQUE. Dùng VARCHAR(255).");
+                }
+                return null;
+            }
+            if (what === "INDEX") {
+                if (dialect === "mysql" && w[i + 1] === "IF") {
+                    return fail(file, stmt, "dialect_syntax", "MySQL không hỗ trợ CREATE INDEX IF NOT EXISTS. Khai báo index trong CREATE TABLE.");
+                }
+                return null;
+            }
+            return fail(file, stmt, "statement_not_allowed", `CREATE ${what ?? ""} không được phép. Chỉ CREATE TABLE và CREATE INDEX (không VIEW, TRIGGER, TYPE, EXTENSION...). Dùng TEXT/VARCHAR thay cho ENUM.`);
+        }
+        case "ALTER": {
+            const tableIdx = w.indexOf("TABLE");
+            if (w[1] !== "TABLE" || tableIdx < 0) {
+                return fail(file, stmt, "statement_not_allowed", "Chỉ ALTER TABLE được phép.");
+            }
+            const action = w.find((x, idx) => idx > tableIdx && (x === "ADD" || x === "RENAME" || x === "DROP" || x === "ALTER" || x === "MODIFY" || x === "CHANGE"));
+            if (action === "ADD" || action === "RENAME")
+                return null;
+            if (action === "DROP")
+                return fail(file, stmt, "statement_not_allowed", `DROP không được phép. ${HINT_DESTRUCTIVE}`);
+            return fail(file, stmt, "statement_not_allowed", "Chỉ ALTER TABLE ... ADD (thêm cột) hoặc RENAME được phép. Muốn đổi kiểu cột: thêm cột mới, chép dữ liệu sang, rồi dùng cột mới.");
+        }
+        case "INSERT":
+            return null;
+        case "UPDATE":
+            if (!w.includes("WHERE")) {
+                return fail(file, stmt, "update_without_where", "UPDATE phải có WHERE để không sửa nhầm cả bảng.");
+            }
+            return null;
+        case "DROP":
+        case "DELETE":
+        case "TRUNCATE":
+            return fail(file, stmt, "statement_not_allowed", `${first} không được phép. ${HINT_DESTRUCTIVE}`);
+        default:
+            return fail(file, stmt, "statement_not_allowed", `${first || "(trống)"} không được phép trong migration. Chỉ CREATE TABLE/INDEX, ALTER TABLE ADD/RENAME, INSERT, UPDATE ... WHERE.`);
+    }
+}
+/** Mẫu lỗi cú pháp riêng của từng dialect mà không có DB thật để thử (MySQL). */
+function dialectLint(file, stmt, dialect) {
+    if (dialect === "mysql") {
+        if (/\bAUTOINCREMENT\b/i.test(stmt.sql)) {
+            return fail(file, stmt, "dialect_syntax", "MySQL dùng AUTO_INCREMENT, không phải AUTOINCREMENT.");
+        }
+        if (stmt.tokens.some((t) => t.kind === "ident" && stmt.sql.includes(`"${t.text}"`))) {
+            return fail(file, stmt, "dialect_syntax", 'MySQL không dùng "tên" có nháy kép. Dùng `tên` hoặc không bọc.');
+        }
+    }
+    return null;
+}
+/** Tên file, kích thước, cú pháp, từng câu lệnh. Không chạm vào database. */
+export function analyzeMigrations(files, dialect) {
+    const issues = [];
+    const migrations = [];
+    if (files.length > MAX_MIGRATION_FILES) {
+        issues.push({ code: "file_too_large", message: `Quá ${MAX_MIGRATION_FILES} file migration.` });
+    }
+    const seenNumbers = new Map();
+    for (const f of [...files].sort((a, b) => a.name.localeCompare(b.name))) {
+        const m = MIGRATION_NAME_RE.exec(f.name);
+        if (!m) {
+            issues.push({
+                code: "bad_file_name",
+                file: f.name,
+                message: `Tên "${f.name}" sai định dạng NNNN_ten.sql (4 chữ số, chữ thường, số, gạch dưới). Ví dụ: 0002_add_phone.sql.`,
+            });
+            continue;
+        }
+        const number = m[1];
+        const dup = seenNumbers.get(number);
+        if (dup) {
+            issues.push({
+                code: "duplicate_number",
+                file: f.name,
+                message: `Số ${number} bị trùng với ${dup}. Mỗi migration cần số riêng, tăng dần.`,
+            });
+            continue;
+        }
+        seenNumbers.set(number, f.name);
+        if (new TextEncoder().encode(f.sql).byteLength > MAX_MIGRATION_BYTES) {
+            issues.push({ code: "file_too_large", file: f.name, message: `Migration ${f.name} quá lớn.` });
+            continue;
+        }
+        let statements;
+        try {
+            statements = splitSqlStatements(f.sql, dialect);
+        }
+        catch (e) {
+            issues.push({
+                code: "syntax",
+                file: f.name,
+                line: e instanceof SqlSyntaxError ? e.line : undefined,
+                message: `${f.name}: ${e instanceof Error ? e.message : "lỗi cú pháp"}`,
+            });
+            continue;
+        }
+        if (statements.length === 0) {
+            issues.push({ code: "empty_file", file: f.name, message: `Migration ${f.name} không có câu lệnh nào.` });
+            continue;
+        }
+        for (const stmt of statements) {
+            const bad = classifyStatement(f.name, stmt, dialect) ?? dialectLint(f.name, stmt, dialect);
+            if (bad)
+                issues.push({ ...bad, message: `${f.name} dòng ${stmt.line}: ${bad.message}` });
+        }
+        migrations.push({ name: f.name, number, sql: f.sql, statements });
+    }
+    return { migrations, issues };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hodela/site",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "files": [
     "dist",
@@ -19,6 +19,10 @@
       "types": "./dist/sql-split.d.ts",
       "import": "./dist/sql-split.js"
     },
+    "./migration-rules": {
+      "types": "./dist/migration-rules.d.ts",
+      "import": "./dist/migration-rules.js"
+    },
     "./admin-token": {
       "types": "./dist/admin-token.d.ts",
       "import": "./dist/admin-token.js"