@c9up/atlas 0.1.13 → 0.1.15

package/src/schema/SchemaCheck.ts

@@ -0,0 +1,273 @@
+/**
+ * Schema verification — reconciles each model's `@Column` metadata against the
+ * LIVE database schema (via {@link introspectTable}) and reports drift BEFORE
+ * it bites at runtime. This is what pure-JS ORMs (Lucid) structurally cannot
+ * do; atlas can because its driver introspects the real database.
+ *
+ * Four drift categories:
+ *   - `missing-table`    — the model's table does not exist.
+ *   - `missing-in-db`    — a model column maps to a non-existent DB column
+ *                          (typo → `did you mean`).
+ *   - `type-mismatch`    — a declared `@Column({ type })` clashes with the DB
+ *                          column's type (conservative: only clear num↔text).
+ *   - `missing-in-model` — a NOT NULL DB column with no default that no model
+ *                          property maps to → inserts will fail.
+ *
+ * The check is dialect-agnostic; only {@link introspectTable} is dialect-aware.
+ * Kept free of any `@c9up/ream` import — atlas stays framework-agnostic.
+ */
+
+import { getColumnMetadata, getEntityMetadata } from "../decorators/entity.js";
+import { getNamingStrategy } from "../naming/NamingStrategy.js";
+import type { AtlasDialect } from "../query/native.js";
+import {
+	type IntrospectedColumn,
+	introspectTable,
+	type SchemaIntrospectable,
+} from "./introspect.js";
+
+type Constructor = new (...args: unknown[]) => unknown;
+
+export type SchemaFindingKind =
+	| "missing-table"
+	| "missing-in-db"
+	| "type-mismatch"
+	| "missing-in-model";
+
+export interface SchemaFinding {
+	entity: string;
+	table: string;
+	kind: SchemaFindingKind;
+	column: string;
+	detail: string;
+	/** A close DB column name, for typo diagnostics (`did you mean`). */
+	suggestion?: string;
+}
+
+// ─── Type compatibility (conservative) ───────────────────────────────
+
+/**
+ * Coarse group of a type string. We only ever flag a mismatch between the two
+ * UNAMBIGUOUS groups (`num` vs `text`); everything storage-dependent
+ * (date/time, binary, blob — SQLite stores these as TEXT/NUMERIC) is `other`
+ * and never flagged, so the check has NO false positives.
+ */
+function typeGroup(raw: string): "num" | "text" | "other" {
+	const t = raw.toLowerCase();
+	if (/(^|[^a-z])(int|serial|decimal|numeric|real|float|double|bool)/.test(t)) {
+		return "num";
+	}
+	if (/char|text|clob|string|uuid|json/.test(t)) return "text";
+	return "other";
+}
+
+/** Compatible unless the model and DB types are in clearly-different groups. */
+export function typesCompatible(modelType: string, dbType: string): boolean {
+	const m = typeGroup(modelType);
+	const d = typeGroup(dbType);
+	if (m === "other" || d === "other") return true;
+	return m === d;
+}
+
+// ─── `did you mean` (atlas-local; no @c9up/ream import) ───────────────
+
+function levenshtein(a: string, b: string): number {
+	const dp = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		let prev = dp[0];
+		dp[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const tmp = dp[j];
+			dp[j] = Math.min(
+				dp[j] + 1,
+				dp[j - 1] + 1,
+				prev + (a[i - 1] === b[j - 1] ? 0 : 1),
+			);
+			prev = tmp;
+		}
+	}
+	return dp[b.length];
+}
+
+/** Closest candidate within edit distance 2 (typo suggestion), else undefined. */
+export function suggestColumn(
+	name: string,
+	candidates: string[],
+): string | undefined {
+	let best: string | undefined;
+	let bestD = Number.POSITIVE_INFINITY;
+	for (const c of candidates) {
+		const d = levenshtein(name, c);
+		if (d < bestD) {
+			bestD = d;
+			best = c;
+		}
+	}
+	return bestD <= 2 ? best : undefined;
+}
+
+// ─── Reconciler ──────────────────────────────────────────────────────
+
+function reconcile(
+	entityName: string,
+	table: string,
+	cols: ReturnType<typeof getColumnMetadata>,
+	columnNameOf: (property: string) => string,
+	dbCols: IntrospectedColumn[],
+): SchemaFinding[] {
+	const findings: SchemaFinding[] = [];
+	const dbByName = new Map(dbCols.map((c) => [c.name, c]));
+	const dbNames = dbCols.map((c) => c.name);
+	const mappedDbColumns = new Set<string>();
+
+	for (const col of cols) {
+		const dbName = columnNameOf(col.propertyKey);
+		mappedDbColumns.add(dbName);
+		const dbCol = dbByName.get(dbName);
+		if (!dbCol) {
+			findings.push({
+				entity: entityName,
+				table,
+				kind: "missing-in-db",
+				column: dbName,
+				detail: `model property \`${col.propertyKey}\` maps to column \`${dbName}\`, which does not exist`,
+				suggestion: suggestColumn(dbName, dbNames),
+			});
+			continue;
+		}
+		if (col.type && !typesCompatible(col.type, dbCol.type)) {
+			findings.push({
+				entity: entityName,
+				table,
+				kind: "type-mismatch",
+				column: dbName,
+				detail: `declared \`${col.type}\` but column is \`${dbCol.type}\``,
+			});
+		}
+	}
+
+	// Reverse drift — a NOT NULL column with no default that no model property
+	// writes: every insert omitting it fails. The dangerous, easy-to-miss case
+	// (e.g. a migration added a column the model never caught up to). PKs are
+	// excluded (DB-generated).
+	for (const dbCol of dbCols) {
+		if (dbCol.primaryKey) continue;
+		if (!dbCol.nullable && !dbCol.hasDefault && !mappedDbColumns.has(dbCol.name)) {
+			findings.push({
+				entity: entityName,
+				table,
+				kind: "missing-in-model",
+				column: dbCol.name,
+				detail: `column \`${dbCol.name}\` is NOT NULL with no default but no model property maps to it — inserts will fail`,
+			});
+		}
+	}
+	return findings;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Reconcile every given entity against the live database. Pass the app's model
+ * classes (atlas has no global entity registry by design — mirror Lucid, where
+ * `ace` is pointed at your models). Returns a flat list of findings (empty when
+ * the schema and models agree).
+ */
+export async function checkSchema(
+	entities: readonly Constructor[],
+	db: SchemaIntrospectable,
+	dialect: AtlasDialect,
+): Promise<SchemaFinding[]> {
+	const findings: SchemaFinding[] = [];
+	for (const entity of entities) {
+		const meta = getEntityMetadata(entity);
+		if (!meta?.tableName) continue; // not an @Entity — skip silently
+		const table = meta.tableName;
+		const entityName = entity.name;
+
+		const dbCols = await introspectTable(db, dialect, table);
+		if (dbCols === null) {
+			findings.push({
+				entity: entityName,
+				table,
+				kind: "missing-table",
+				column: table,
+				detail: `table \`${table}\` does not exist in the database — run your migrations`,
+			});
+			continue;
+		}
+
+		const strategy = getNamingStrategy(entity);
+		findings.push(
+			...reconcile(
+				entityName,
+				table,
+				getColumnMetadata(entity),
+				(p) => strategy.columnName(p),
+				dbCols,
+			),
+		);
+	}
+	return findings;
+}
+
+/** Render findings as a didactic, Adonis-style diff (grouped per table). */
+export function formatSchemaFindings(findings: SchemaFinding[]): string {
+	if (findings.length === 0) return "[atlas:check] schema OK — models match the database.";
+	const byTable = new Map<string, SchemaFinding[]>();
+	for (const f of findings) {
+		const key = `${f.table} (${f.entity})`;
+		const list = byTable.get(key) ?? [];
+		list.push(f);
+		byTable.set(key, list);
+	}
+	const lines: string[] = [
+		`[atlas:check] ${findings.length} schema issue(s) found:`,
+	];
+	for (const [key, list] of byTable) {
+		lines.push(`\n  ${key}`);
+		for (const f of list) {
+			const hint = f.suggestion ? ` — did you mean \`${f.suggestion}\`?` : "";
+			lines.push(`    ✗ ${f.column}: ${f.detail}${hint}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Boot-time guard: run {@link checkSchema} and either throw (fail-fast, for CI /
+ * dev startup) or warn (non-blocking). Returns the findings. `mode` defaults to
+ * `"throw"` — a schema mismatch is a misconfiguration that should stop the boot
+ * before requests serve stale assumptions.
+ */
+export async function verifySchema(
+	entities: readonly Constructor[],
+	db: SchemaIntrospectable,
+	dialect: AtlasDialect,
+	opts: { mode?: "throw" | "warn" } = {},
+): Promise<SchemaFinding[]> {
+	const findings = await checkSchema(entities, db, dialect);
+	if (findings.length > 0) {
+		const report = formatSchemaFindings(findings);
+		if ((opts.mode ?? "throw") === "throw") {
+			throw new Error(report);
+		}
+		console.warn(report);
+	}
+	return findings;
+}
+
+/**
+ * CLI body: run the check, print the report (diff or the OK line), and return
+ * the process exit code (`0` = schema matches, `1` = drift). Used by the
+ * `atlas:check` console command; safe to call from any script.
+ */
+export async function runSchemaCheck(
+	entities: readonly Constructor[],
+	db: SchemaIntrospectable,
+	dialect: AtlasDialect,
+): Promise<number> {
+	const findings = await checkSchema(entities, db, dialect);
+	console.log(formatSchemaFindings(findings));
+	return findings.length > 0 ? 1 : 0;
+}

package/src/schema/TableBuilder.ts

@@ -12,6 +12,8 @@ import {
 	compileStatementNative,
 	getAtlasDialect,
 } from "../query/native.js";
+import { RawSql } from "../query/QueryBuilder.js";
+import { type DefaultValue, renderDefaultValue } from "./raw.js";
 import {
 	type ColumnDefinition,
 	type ColumnType,
@@ -128,7 +130,7 @@ export class TableBuilder {
 	 * the helper dialect-aware.
 	 */
 	id(): this {
-		return this.uuid("id").primary().defaultTo("gen_random_uuid()");
+		return this.uuid("id").primary().defaultTo(new RawSql("gen_random_uuid()"));
 	}
 
 	/**
@@ -155,8 +157,8 @@ export class TableBuilder {
 	 * the helper dialect-aware.
 	 */
 	timestamps(): this {
-		this.timestamp("created_at").notNullable().defaultTo("NOW()");
-		this.timestamp("updated_at").notNullable().defaultTo("NOW()");
+		this.timestamp("created_at").notNullable().defaultTo(new RawSql("NOW()"));
+		this.timestamp("updated_at").notNullable().defaultTo(new RawSql("NOW()"));
 		return this;
 	}
 
@@ -182,8 +184,15 @@ export class TableBuilder {
 		return this;
 	}
 
-	defaultTo(value: string): this {
-		if (this.#currentColumn) this.#currentColumn.defaultValue = value;
+	/**
+	 * Set a column default. JS literals are quoted/escaped (`'x'`, `123`,
+	 * `true` — Lucid/Knex semantics); wrap SQL expressions in {@link raw} (or
+	 * use `Migration.now()`) to emit them verbatim.
+	 */
+	defaultTo(value: DefaultValue): this {
+		if (this.#currentColumn) {
+			this.#currentColumn.defaultValue = renderDefaultValue(value);
+		}
 		return this;
 	}
 

package/src/schema/introspect.ts

@@ -0,0 +1,133 @@
+/**
+ * Live schema introspection — reads the ACTUAL table/column shape from the
+ * connected database, per dialect. The reconciler in `SchemaCheck.ts` diffs
+ * this against each model's `@Column` metadata.
+ *
+ * SQLite uses `pragma_table_info`; Postgres and MySQL use `information_schema`.
+ * Table names come from `@Entity(...)` (developer-defined, trusted) — they are
+ * validated against a strict identifier pattern before interpolation, since
+ * `pragma_table_info(...)` cannot bind its argument.
+ */
+
+import type { AtlasDialect } from "../query/native.js";
+
+/**
+ * Minimal connection surface the check needs: a row-returning `query`. Both the
+ * real `AsyncDatabaseConnection` and the test `Database` satisfy it, so the
+ * checker doesn't depend on the full driver interface.
+ */
+export interface SchemaIntrospectable {
+	query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+}
+
+/** One column as it actually exists in the database. */
+export interface IntrospectedColumn {
+	name: string;
+	/** Raw dialect type string (e.g. `INTEGER`, `character varying`, `varchar`). */
+	type: string;
+	nullable: boolean;
+	hasDefault: boolean;
+	primaryKey: boolean;
+}
+
+/** A safe SQL identifier (table name from `@Entity`). */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertIdent(name: string): void {
+	if (!IDENT.test(name)) {
+		throw new Error(
+			`[atlas:check] refusing to introspect unsafe table identifier: ${JSON.stringify(name)}`,
+		);
+	}
+}
+
+/**
+ * Introspect one table. Returns its columns, or `null` when the table does not
+ * exist in the database (a distinct, reportable drift — not an error).
+ */
+export async function introspectTable(
+	db: SchemaIntrospectable,
+	dialect: AtlasDialect,
+	table: string,
+): Promise<IntrospectedColumn[] | null> {
+	assertIdent(table);
+	switch (dialect) {
+		case "sqlite":
+			return introspectSqlite(db, table);
+		case "postgres":
+			return introspectPostgres(db, table);
+		case "mysql":
+			return introspectMysql(db, table);
+	}
+}
+
+async function introspectSqlite(
+	db: SchemaIntrospectable,
+	table: string,
+): Promise<IntrospectedColumn[] | null> {
+	const rows = await db.query(
+		`SELECT * FROM pragma_table_info('${table}')`,
+	);
+	if (rows.length === 0) return null; // unknown table → no columns
+	return rows.map((r) => ({
+		name: String(r.name),
+		type: String(r.type ?? ""),
+		nullable: Number(r.notnull) === 0,
+		hasDefault: r.dflt_value !== null && r.dflt_value !== undefined,
+		primaryKey: Number(r.pk) > 0,
+	}));
+}
+
+async function introspectPostgres(
+	db: SchemaIntrospectable,
+	table: string,
+): Promise<IntrospectedColumn[] | null> {
+	const cols = await db.query(
+		`SELECT column_name, data_type, is_nullable, column_default
+		 FROM information_schema.columns
+		 WHERE table_schema = current_schema() AND table_name = $1
+		 ORDER BY ordinal_position`,
+		[table],
+	);
+	if (cols.length === 0) return null;
+	const pkRows = await db.query(
+		`SELECT kcu.column_name
+		 FROM information_schema.table_constraints tc
+		 JOIN information_schema.key_column_usage kcu
+		   ON kcu.constraint_name = tc.constraint_name
+		  AND kcu.table_schema = tc.table_schema
+		 WHERE tc.table_name = $1 AND tc.constraint_type = 'PRIMARY KEY'`,
+		[table],
+	);
+	const pks = new Set(pkRows.map((r) => String(r.column_name)));
+	return cols.map((r) => ({
+		name: String(r.column_name),
+		type: String(r.data_type ?? ""),
+		nullable: String(r.is_nullable).toUpperCase() === "YES",
+		hasDefault: r.column_default !== null && r.column_default !== undefined,
+		primaryKey: pks.has(String(r.column_name)),
+	}));
+}
+
+async function introspectMysql(
+	db: SchemaIntrospectable,
+	table: string,
+): Promise<IntrospectedColumn[] | null> {
+	const rows = await db.query(
+		`SELECT column_name, data_type, is_nullable, column_default, column_key
+		 FROM information_schema.columns
+		 WHERE table_schema = DATABASE() AND table_name = ?
+		 ORDER BY ordinal_position`,
+		[table],
+	);
+	if (rows.length === 0) return null;
+	return rows.map((r) => ({
+		name: String(r.column_name ?? r.COLUMN_NAME),
+		type: String(r.data_type ?? r.DATA_TYPE ?? ""),
+		nullable: String(r.is_nullable ?? r.IS_NULLABLE).toUpperCase() === "YES",
+		hasDefault:
+			(r.column_default ?? r.COLUMN_DEFAULT) !== null &&
+			(r.column_default ?? r.COLUMN_DEFAULT) !== undefined,
+		primaryKey: String(r.column_key ?? r.COLUMN_KEY ?? "").toUpperCase() === "PRI",
+	}));
+}

package/src/schema/raw.ts

@@ -0,0 +1,34 @@
+/**
+ * Default-value rendering for the schema builder — Lucid/Knex semantics.
+ *
+ * `defaultTo` quotes JS literals and emits raw SQL only when given a `RawSql`
+ * (the single raw-expression type atlas uses everywhere, incl. queries),
+ * produced in a migration by `this.now()` / `this.raw(...)`:
+ *
+ *   t.text('status').defaultTo('new')             // → DEFAULT 'new'   (quoted literal)
+ *   t.boolean('active').defaultTo(false)          // → DEFAULT false
+ *   t.integer('count').defaultTo(0)               // → DEFAULT 0
+ *   t.uuid('id').defaultTo(this.raw('gen_random_uuid()'))  // → DEFAULT gen_random_uuid()
+ *   t.timestamp('created_at').defaultTo(this.now())        // → DEFAULT NOW()/CURRENT_TIMESTAMP
+ *
+ * Before this, `defaultTo` wrote its argument verbatim, so a bare
+ * `defaultTo('new')` produced the invalid `DEFAULT new` and string defaults had
+ * to be hand-quoted (`defaultTo("'new'")`) — a footgun Lucid/Knex avoid.
+ */
+
+import { RawSql } from "../query/QueryBuilder.js";
+
+/** Accepted `defaultTo` argument: a JS literal or a raw SQL expression. */
+export type DefaultValue = string | number | boolean | RawSql;
+
+/**
+ * Render a `defaultTo` argument to the SQL fragment stored as the column
+ * default. Literals are quoted/escaped; a {@link RawSql} passes through verbatim.
+ */
+export function renderDefaultValue(value: DefaultValue): string {
+	if (value instanceof RawSql) return value.sql;
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "true" : "false";
+	// String literal — single-quote and escape embedded quotes (SQL standard).
+	return `'${value.replace(/'/g, "''")}'`;
+}

package/src/services/db.ts

@@ -14,6 +14,18 @@
  */
 
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import { RawSql } from "../query/QueryBuilder.js";
+
+/** The `db` singleton surface: the bound connection plus the AdonisJS-style `db.raw()` builder. */
+export interface DbService extends AsyncDatabaseConnection {
+	/**
+	 * Build a raw SQL expression — AdonisJS `db.raw()` / `Database.raw()`. Use it
+	 * for query fragments and for column defaults that are SQL expressions:
+	 *
+	 *   t.uuid('id').defaultTo(db.raw('gen_random_uuid()'))
+	 */
+	raw(sql: string, params?: unknown[]): RawSql;
+}
 
 let instance: AsyncDatabaseConnection | undefined;
 
@@ -37,8 +49,12 @@ export function getDb(): AsyncDatabaseConnection | undefined {
 	return instance;
 }
 
-const db: AsyncDatabaseConnection = new Proxy({} as AsyncDatabaseConnection, {
+const db: DbService = new Proxy({} as DbService, {
 	get(_target, prop) {
+		// `raw` is a pure builder (no connection needed) — available pre-boot too.
+		if (prop === "raw") {
+			return (sql: string, params: unknown[] = []) => new RawSql(sql, params);
+		}
 		if (!instance) {
 			throw new Error(
 				"[atlas] db singleton accessed before AtlasProvider.boot() ran. " +