@noormdev/sdk 1.5.1 → 1.6.0

package/dist/index.d.ts

@@ -1957,7 +1957,9 @@ declare class ChangeManager {
 	 * List all changes with status.
 	 *
 	 * Merges changes from disk with status from database.
-	 * Includes orphaned changes (in DB but not on disk).
+	 * Includes orphaned changes (in DB but not on disk), and folders on disk
+	 * that cannot be parsed: `failed` with the parse error when they never
+	 * ran, otherwise their recorded status.
 	 *
 	 * @returns Array of changes with merged status
 	 */
@@ -2585,7 +2587,7 @@ export declare class RunNamespace {
 	 *
 	 * @example
 	 * ```typescript
-	 * const files = await ctx.noorm.run.discover('sql/')
+	 * const files = await ctx.noorm.run.discover('db/sql/')
 	 * ```
 	 */
 	discover(dirpath?: string): Promise<string[]>;
@@ -2594,7 +2596,7 @@ export declare class RunNamespace {
 	 *
 	 * @example
 	 * ```typescript
-	 * const results = await ctx.noorm.run.preview(['sql/001.sql', 'sql/002.sql'])
+	 * const results = await ctx.noorm.run.preview(['db/sql/001.sql', 'db/sql/002.sql'])
 	 * ```
 	 */
 	preview(filepaths: string[], output?: string | null): Promise<FileResult[]>;

package/dist/index.js

@@ -13,7 +13,7 @@ import { __commonJS, __toESM } from './chunk-D2XW2UOP.js';
 import { existsSync, accessSync, constants, readFileSync, mkdirSync, chmodSync, createWriteStream, writeFileSync, openSync, writeSync, closeSync, unlinkSync, statSync, copyFileSync, fsyncSync, renameSync } from 'fs';
 import path, { join, dirname, resolve, relative, sep } from 'path';
 import { homedir, availableParallelism, userInfo } from 'os';
-import { stat, mkdir, writeFile, unlink, rename, rm, readdir, readFile, access } from 'fs/promises';
+import { stat, mkdir, writeFile, unlink, rename, rm, readFile, readdir, access } from 'fs/promises';
 import { createHash, createPrivateKey, createPublicKey, createDecipheriv, randomBytes, createCipheriv, randomUUID, hkdfSync } from 'crypto';
 import { execSync } from 'child_process';
 import { sql } from 'kysely';
@@ -1731,9 +1731,12 @@ var DEFAULT_BUILD_CONFIG = {
   include: [],
   exclude: []
 };
+var DEFAULT_DB_DIR = "db";
+var DEFAULT_SQL_PATH = `./${DEFAULT_DB_DIR}/sql`;
+var DEFAULT_CHANGES_PATH = `./${DEFAULT_DB_DIR}/changes`;
 var DEFAULT_PATH_CONFIG = {
-  sql: "./sql",
-  changes: "./changes"
+  sql: DEFAULT_SQL_PATH,
+  changes: DEFAULT_CHANGES_PATH
 };
 var DEFAULT_STRICT_CONFIG = {
   enabled: false,
@@ -2108,6 +2111,10 @@ var SettingsManager = class {
   /**
    * Initialize a new settings file with defaults.
    *
+   * An overwrite keeps the `paths` already in the file: they say where the
+   * project's files are, not a preference, and resetting them would point a
+   * project laid out elsewhere at directories that do not exist.
+   *
    * @param force - Overwrite existing file if true
    * @throws Error if file exists and force is false
    */
@@ -2116,7 +2123,10 @@ var SettingsManager = class {
     if (fileExists2 && !force) {
       throw new Error("Settings file already exists. Use force=true to overwrite.");
     }
+    const [previous] = fileExists2 ? await attempt(() => this.load()) : [void 0];
+    const keptPaths = previous ? this.#document?.paths : void 0;
     this.#document = createDefaultSettings();
+    if (keptPaths) this.#document.paths = clone(keptPaths);
     this.#refreshResolved();
     this.#loaded = true;
     await this.save();
@@ -4254,7 +4264,7 @@ function buildMssqlTvfWithTvp(rawName, params) {
 
 // src/core/change/types.ts
 function isPendingChange(item) {
-  return !item.orphaned && (item.status === "pending" || item.status === "reverted" || item.status === "stale");
+  return !item.orphaned && (item.status === "pending" || item.status === "reverted" || item.status === "stale" || item.status === "failed" && item.isNew);
 }
 var ChangeValidationError = class extends Error {
   constructor(changeName, issue) {
@@ -4340,10 +4350,31 @@ async function parseChange(folderPath, sqlDir) {
     hasChangelog
   };
 }
+function failureListItem(failure, status) {
+  const { date, description } = parseName(failure.name);
+  return {
+    name: failure.name,
+    path: failure.path,
+    date,
+    description,
+    status: status?.status ?? "failed",
+    appliedAt: status?.appliedAt ?? null,
+    appliedBy: status?.appliedBy ?? null,
+    revertedAt: status?.revertedAt ?? null,
+    errorMessage: status ? status.errorMessage : failure.message,
+    appliedHistoryId: status?.appliedHistoryId ?? null,
+    isNew: !status,
+    orphaned: false
+  };
+}
 async function discoverChanges(changesDir, sqlDir) {
+  const { changes } = await scanChanges(changesDir, sqlDir);
+  return changes;
+}
+async function scanChanges(changesDir, sqlDir) {
   const [exists] = await attempt(() => stat(changesDir));
   if (!exists) {
-    return [];
+    return { changes: [], failures: [] };
   }
   const [entries, readErr] = await attempt(() => readdir(changesDir, { withFileTypes: true }));
   if (readErr) {
@@ -4352,12 +4383,14 @@ async function discoverChanges(changesDir, sqlDir) {
       error: readErr,
       context: { changesDir, operation: "discover" }
     });
-    return [];
+    return { changes: [], failures: [] };
   }
   const folders = entries.filter((e) => e.isDirectory());
   const changes = [];
+  const failures = [];
   for (const folder of folders) {
     const folderPath = path.join(changesDir, folder.name);
+    if (!await looksLikeChange(folderPath)) continue;
     const [change, parseErr] = await attempt(() => parseChange(folderPath, sqlDir));
     if (parseErr) {
       observer.emit("error", {
@@ -4365,11 +4398,15 @@ async function discoverChanges(changesDir, sqlDir) {
         error: parseErr,
         context: { folder: folder.name, operation: "parse" }
       });
+      failures.push({ name: folder.name, path: folderPath, message: parseErr.message });
       continue;
     }
     changes.push(change);
   }
-  return changes.sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    changes: changes.sort((a, b) => a.name.localeCompare(b.name)),
+    failures
+  };
 }
 async function resolveManifest(manifestPath, sqlDir) {
   const [content, readErr] = await attempt(() => readFile(manifestPath, "utf-8"));
@@ -4428,6 +4465,13 @@ function parseName(name) {
   }
   return { date: null, description: name };
 }
+async function looksLikeChange(folderPath) {
+  for (const subfolder of ["change", "revert"]) {
+    const [entry] = await attempt(() => stat(path.join(folderPath, subfolder)));
+    if (entry?.isDirectory()) return true;
+  }
+  return false;
+}
 async function scanFolder(folderPath, sqlDir) {
   const [entries, err] = await attempt(() => readdir(folderPath, { withFileTypes: true }));
   if (err) {
@@ -6319,6 +6363,165 @@ var StatementWatcher = class {
   }
 };
 
+// src/core/runner/sqlite-statements.ts
+var QUOTE_PAIRS = {
+  "'": "'",
+  '"': '"',
+  "`": "`",
+  "[": "]"
+};
+function keywordAt(content, index, keyword) {
+  const end = index + keyword.length;
+  if (content.slice(index, end).toUpperCase() !== keyword) return false;
+  const before = index > 0 ? content[index - 1] : " ";
+  const after = end < content.length ? content[end] : " ";
+  return !/[A-Za-z0-9_$]/.test(before) && !/[A-Za-z0-9_$]/.test(after);
+}
+function splitSqliteStatements(content) {
+  const statements = [];
+  let current = "";
+  let closingQuote = null;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let inTrigger = false;
+  let blockDepth = 0;
+  let i = 0;
+  const flush = () => {
+    const trimmed = current.trim();
+    if (trimmed.length > 0 && !isCommentOnly(trimmed)) {
+      statements.push(trimmed);
+    }
+    current = "";
+  };
+  while (i < content.length) {
+    const char = content[i];
+    if (inLineComment) {
+      current += char;
+      if (char === "\n") inLineComment = false;
+      i++;
+      continue;
+    }
+    if (inBlockComment) {
+      current += char;
+      if (char === "*" && content[i + 1] === "/") {
+        current += "/";
+        inBlockComment = false;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (closingQuote !== null) {
+      current += char;
+      if (char === closingQuote) {
+        if (closingQuote !== "]" && content[i + 1] === closingQuote) {
+          current += closingQuote;
+          i += 2;
+          continue;
+        }
+        closingQuote = null;
+      }
+      i++;
+      continue;
+    }
+    if (char === "-" && content[i + 1] === "-") {
+      inLineComment = true;
+      current += "--";
+      i += 2;
+      continue;
+    }
+    if (char === "/" && content[i + 1] === "*") {
+      inBlockComment = true;
+      current += "/*";
+      i += 2;
+      continue;
+    }
+    if (QUOTE_PAIRS[char]) {
+      closingQuote = QUOTE_PAIRS[char];
+      current += char;
+      i++;
+      continue;
+    }
+    if (!inTrigger && keywordAt(content, i, "TRIGGER")) {
+      inTrigger = true;
+      current += content.slice(i, i + 7);
+      i += 7;
+      continue;
+    }
+    if (inTrigger && (keywordAt(content, i, "BEGIN") || keywordAt(content, i, "CASE"))) {
+      const length = keywordAt(content, i, "BEGIN") ? 5 : 4;
+      blockDepth++;
+      current += content.slice(i, i + length);
+      i += length;
+      continue;
+    }
+    if (inTrigger && blockDepth > 0 && keywordAt(content, i, "END")) {
+      blockDepth--;
+      if (blockDepth === 0) inTrigger = false;
+      current += content.slice(i, i + 3);
+      i += 3;
+      continue;
+    }
+    if (char === ";" && blockDepth === 0) {
+      current += char;
+      inTrigger = false;
+      flush();
+      i++;
+      continue;
+    }
+    current += char;
+    i++;
+  }
+  flush();
+  return statements;
+}
+function isCommentOnly(fragment) {
+  const withoutBlockComments = fragment.replace(/\/\*[\s\S]*?\*\//g, "");
+  return withoutBlockComments.split("\n").every((line) => {
+    const trimmed = line.trim();
+    return trimmed.length === 0 || trimmed.startsWith("--");
+  });
+}
+
+// src/core/runner/mssql-batches.ts
+function splitMssqlBatches(content) {
+  const batches = content.split(/^\s*GO\s*$/mi);
+  return batches.map((b) => b.trim()).filter((b) => b.length > 0 && !isCommentOnly2(b));
+}
+function isCommentOnly2(batch) {
+  for (const line of batch.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0 && !trimmed.startsWith("--")) {
+      return false;
+    }
+  }
+  return true;
+}
+async function executeSqlBody(context, sqlContent) {
+  if (context.dialect === "mssql") {
+    return executeFragments(context, splitMssqlBatches(sqlContent), "batch");
+  }
+  if (context.dialect === "sqlite") {
+    return executeFragments(context, splitSqliteStatements(sqlContent), "statement");
+  }
+  const [, execErr] = await attempt(() => sql.raw(sqlContent).execute(context.db));
+  if (execErr) {
+    return getSqlErrorMessage(execErr);
+  }
+  return null;
+}
+async function executeFragments(context, fragments, label) {
+  for (let i = 0; i < fragments.length; i++) {
+    const [, execErr] = await attempt(() => sql.raw(fragments[i]).execute(context.db));
+    if (execErr) {
+      const message = getSqlErrorMessage(execErr);
+      return fragments.length === 1 ? message : `[${label} ${i + 1} of ${fragments.length}] ${message}`;
+    }
+  }
+  return null;
+}
+
 // src/core/lock/types.ts
 var DEFAULT_LOCK_OPTIONS = {
   dialect: "postgres",
@@ -7066,12 +7269,12 @@ async function runFileBatch(context, change, expandedFiles, direction, checksum,
         }
         break;
       }
-      const [, execErr] = await attempt(
-        () => watcher.run(file.path, executor, (conn) => sql.raw(sqlContent).execute(conn))
+      const [execMessage, execErr] = await attempt(
+        () => watcher.run(file.path, executor, (conn) => executeSqlBody({ db: conn, dialect: context.dialect }, sqlContent))
       );
       const durationMs = performance.now() - fileStart;
-      if (execErr) {
-        const errorMessage2 = getSqlErrorMessage(execErr);
+      const errorMessage2 = execErr ? getSqlErrorMessage(execErr) : execMessage;
+      if (errorMessage2) {
         failed = true;
         failedFile = file.path;
         failureError = errorMessage2;
@@ -7409,17 +7612,31 @@ var ChangeManager = class {
    * List all changes with status.
    *
    * Merges changes from disk with status from database.
-   * Includes orphaned changes (in DB but not on disk).
+   * Includes orphaned changes (in DB but not on disk), and folders on disk
+   * that cannot be parsed: `failed` with the parse error when they never
+   * ran, otherwise their recorded status.
    *
    * @returns Array of changes with merged status
    */
   async list() {
-    const diskChanges = await discoverChanges(
+    const { items } = await this.#scan();
+    return items;
+  }
+  /**
+   * Merge disk and database state, and report the folders that cannot be read.
+   *
+   * An unreadable folder that a batch would run (never run, or `reverted` or
+   * `stale`) is pending work: the batch fails at its position rather than
+   * skipping it and running later changes out of order. `unreadable` holds the
+   * applied ones; they keep their status and only warrant a warning.
+   */
+  async #scan() {
+    const { changes: diskChanges, failures } = await scanChanges(
       this.#context.changesDir,
       this.#context.sqlDir
     );
     const statuses = await this.#history.getAllStatuses();
-    const diskNames = new Set(diskChanges.map((cs) => cs.name));
+    const diskNames = new Set([...diskChanges, ...failures].map((cs) => cs.name));
     const orphanedNames = await this.#history.getOrphaned(diskNames);
     const result = [];
     for (const cs of diskChanges) {
@@ -7437,6 +7654,15 @@ var ChangeManager = class {
         orphaned: false
       });
     }
+    const unreadable = [];
+    for (const failure of failures) {
+      const status = statuses.get(failure.name);
+      const item = failureListItem(failure, status);
+      if (!isPendingChange(item)) {
+        unreadable.push(failure);
+      }
+      result.push(item);
+    }
     for (const name of orphanedNames) {
       const status = statuses.get(name);
       result.push({
@@ -7458,7 +7684,10 @@ var ChangeManager = class {
         hasChangelog: void 0
       });
     }
-    return result.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+      items: result.sort((a, b) => a.name.localeCompare(b.name)),
+      unreadable
+    };
   }
   // ─────────────────────────────────────────────────────────
   // Run Single Change
@@ -7513,9 +7742,13 @@ var ChangeManager = class {
   async next(count = 1, options = {}) {
     const opts = { ...DEFAULT_BATCH, ...options };
     const start = performance.now();
-    const warnings = await this.#collectWarnings();
-    const list = await this.list();
-    const pending = list.filter(isPendingChange).slice(0, count);
+    const { items, unreadable } = await this.#scan();
+    const messages = [
+      ...await this.#collectWarnings() ?? [],
+      ...unreadable.map((f) => `Change '${f.name}' is applied but its files can no longer be read: ${f.message}`)
+    ];
+    const warnings = messages.length > 0 ? messages : void 0;
+    const pending = items.filter(isPendingChange).slice(0, count);
     if (pending.length === 0) {
       return {
         status: "success",
@@ -7583,9 +7816,7 @@ var ChangeManager = class {
    * @returns Batch result
    */
   async ff(options = {}) {
-    const list = await this.list();
-    const pendingCount = list.filter(isPendingChange).length;
-    return this.next(pendingCount, options);
+    return this.next(Number.POSITIVE_INFINITY, options);
   }
   /**
    * Rewind: revert changes in reverse order.
@@ -7754,6 +7985,8 @@ var ChangeManager = class {
       () => parseChange(changePath, this.#context.sqlDir)
     );
     if (err) {
+      const [onDisk] = await attempt(() => stat(changePath));
+      if (onDisk) throw err;
       const status = await this.#history.getStatus(name);
       if (status) {
         throw new ChangeOrphanedError(name);
@@ -8379,13 +8612,13 @@ var ChangesNamespace = class {
   get #changesDir() {
     return path.join(
       this.#state.projectRoot,
-      this.#state.settings.paths?.changes ?? "changes"
+      this.#state.settings.paths?.changes ?? DEFAULT_CHANGES_PATH
     );
   }
   get #sqlDir() {
     return path.join(
       this.#state.projectRoot,
-      this.#state.settings.paths?.sql ?? "sql"
+      this.#state.settings.paths?.sql ?? DEFAULT_SQL_PATH
     );
   }
   get #kysely() {
@@ -8418,167 +8651,6 @@ var ChangesNamespace = class {
     return this.#manager;
   }
 };
-
-// src/core/runner/sqlite-statements.ts
-var QUOTE_PAIRS = {
-  "'": "'",
-  '"': '"',
-  "`": "`",
-  "[": "]"
-};
-function keywordAt(content, index, keyword) {
-  const end = index + keyword.length;
-  if (content.slice(index, end).toUpperCase() !== keyword) return false;
-  const before = index > 0 ? content[index - 1] : " ";
-  const after = end < content.length ? content[end] : " ";
-  return !/[A-Za-z0-9_$]/.test(before) && !/[A-Za-z0-9_$]/.test(after);
-}
-function splitSqliteStatements(content) {
-  const statements = [];
-  let current = "";
-  let closingQuote = null;
-  let inLineComment = false;
-  let inBlockComment = false;
-  let inTrigger = false;
-  let blockDepth = 0;
-  let i = 0;
-  const flush = () => {
-    const trimmed = current.trim();
-    if (trimmed.length > 0 && !isCommentOnly(trimmed)) {
-      statements.push(trimmed);
-    }
-    current = "";
-  };
-  while (i < content.length) {
-    const char = content[i];
-    if (inLineComment) {
-      current += char;
-      if (char === "\n") inLineComment = false;
-      i++;
-      continue;
-    }
-    if (inBlockComment) {
-      current += char;
-      if (char === "*" && content[i + 1] === "/") {
-        current += "/";
-        inBlockComment = false;
-        i += 2;
-        continue;
-      }
-      i++;
-      continue;
-    }
-    if (closingQuote !== null) {
-      current += char;
-      if (char === closingQuote) {
-        if (closingQuote !== "]" && content[i + 1] === closingQuote) {
-          current += closingQuote;
-          i += 2;
-          continue;
-        }
-        closingQuote = null;
-      }
-      i++;
-      continue;
-    }
-    if (char === "-" && content[i + 1] === "-") {
-      inLineComment = true;
-      current += "--";
-      i += 2;
-      continue;
-    }
-    if (char === "/" && content[i + 1] === "*") {
-      inBlockComment = true;
-      current += "/*";
-      i += 2;
-      continue;
-    }
-    if (QUOTE_PAIRS[char]) {
-      closingQuote = QUOTE_PAIRS[char];
-      current += char;
-      i++;
-      continue;
-    }
-    if (!inTrigger && keywordAt(content, i, "TRIGGER")) {
-      inTrigger = true;
-      current += content.slice(i, i + 7);
-      i += 7;
-      continue;
-    }
-    if (inTrigger && (keywordAt(content, i, "BEGIN") || keywordAt(content, i, "CASE"))) {
-      const length = keywordAt(content, i, "BEGIN") ? 5 : 4;
-      blockDepth++;
-      current += content.slice(i, i + length);
-      i += length;
-      continue;
-    }
-    if (inTrigger && blockDepth > 0 && keywordAt(content, i, "END")) {
-      blockDepth--;
-      if (blockDepth === 0) inTrigger = false;
-      current += content.slice(i, i + 3);
-      i += 3;
-      continue;
-    }
-    if (char === ";" && blockDepth === 0) {
-      current += char;
-      inTrigger = false;
-      flush();
-      i++;
-      continue;
-    }
-    current += char;
-    i++;
-  }
-  flush();
-  return statements;
-}
-function isCommentOnly(fragment) {
-  const withoutBlockComments = fragment.replace(/\/\*[\s\S]*?\*\//g, "");
-  return withoutBlockComments.split("\n").every((line) => {
-    const trimmed = line.trim();
-    return trimmed.length === 0 || trimmed.startsWith("--");
-  });
-}
-
-// src/core/runner/mssql-batches.ts
-function splitMssqlBatches(content) {
-  const batches = content.split(/^\s*GO\s*$/mi);
-  return batches.map((b) => b.trim()).filter((b) => b.length > 0 && !isCommentOnly2(b));
-}
-function isCommentOnly2(batch) {
-  for (const line of batch.split("\n")) {
-    const trimmed = line.trim();
-    if (trimmed.length > 0 && !trimmed.startsWith("--")) {
-      return false;
-    }
-  }
-  return true;
-}
-async function executeSqlBody(context, sqlContent) {
-  if (context.dialect === "mssql") {
-    return executeFragments(context, splitMssqlBatches(sqlContent), "batch");
-  }
-  if (context.dialect === "sqlite") {
-    return executeFragments(context, splitSqliteStatements(sqlContent), "statement");
-  }
-  const [, execErr] = await attempt(() => sql.raw(sqlContent).execute(context.db));
-  if (execErr) {
-    return getSqlErrorMessage(execErr);
-  }
-  return null;
-}
-async function executeFragments(context, fragments, label) {
-  for (let i = 0; i < fragments.length; i++) {
-    const [, execErr] = await attempt(() => sql.raw(fragments[i]).execute(context.db));
-    if (execErr) {
-      const message = getSqlErrorMessage(execErr);
-      return fragments.length === 1 ? message : `[${label} ${i + 1} of ${fragments.length}] ${message}`;
-    }
-  }
-  return null;
-}
-
-// src/core/runner/runner.ts
 var SQL_EXTENSIONS2 = [".sql", ".sql.tmpl"];
 var FILE_HEADER_TEMPLATE = `-- ============================================================
 -- File: %FILE%
@@ -8918,8 +8990,8 @@ async function prepareFiles(context, files) {
   for (const file of files) {
     const relFilepath = path.relative(context.projectRoot, file.path);
     const [loaded, loadError] = await attempt(async () => {
-      const sql28 = await loadAndRenderFile2(context, file.path);
-      return { sql: sql28, checksum: computeChecksumFromContent(sql28) };
+      const sql27 = await loadAndRenderFile2(context, file.path);
+      return { sql: sql27, checksum: computeChecksumFromContent(sql27) };
     });
     if (loadError) {
       prepared.push({ file, relFilepath, checksum: "", sql: "", loadError });
@@ -9205,12 +9277,12 @@ var RunNamespace = class {
    *
    * @example
    * ```typescript
-   * const files = await ctx.noorm.run.discover('sql/')
+   * const files = await ctx.noorm.run.discover('db/sql/')
    * ```
    */
   async discover(dirpath) {
     const absolutePath = this.#resolvePath(
-      dirpath ?? this.#state.settings.paths?.sql ?? "sql"
+      dirpath ?? this.#state.settings.paths?.sql ?? DEFAULT_SQL_PATH
     );
     return discoverFiles(absolutePath);
   }
@@ -9222,7 +9294,7 @@ var RunNamespace = class {
    *
    * @example
    * ```typescript
-   * const results = await ctx.noorm.run.preview(['sql/001.sql', 'sql/002.sql'])
+   * const results = await ctx.noorm.run.preview(['db/sql/001.sql', 'db/sql/002.sql'])
    * ```
    */
   async preview(filepaths, output) {
@@ -9299,7 +9371,7 @@ var RunNamespace = class {
     const context = await this.#createRunContext();
     const sqlPath = path.join(
       this.#state.projectRoot,
-      this.#state.settings.paths?.sql ?? "sql"
+      this.#state.settings.paths?.sql ?? DEFAULT_SQL_PATH
     );
     const configForMatch = {
       name: this.#state.config.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noormdev/sdk",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Database schema & changeset manager SDK",
   "type": "module",
   "main": "./dist/index.js",