@fabrika/platform-node 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform-node",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -37,6 +37,6 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/platform": "0.6.0"
+		"@fabrika/platform": "0.7.0"
 	}
 }

package/src/file-table-ddl.ts

@@ -1,6 +1,6 @@
-// The SQL of a file collection's table that three readers must agree on: `@fabrika/db`'s `fileTableSql` and
-// `fileScanSql` write it, the migration classifier admits exactly the scan migration, and `@fabrika/check` recognizes
-// a table that can hold the scan states. Pure: tokens in, answers out.
+// The SQL of a file collection's table, which an application on an older framework release (up to 0.5) created with
+// that release's `fileTableSql` and widened with its `fileScanSql`. The migration classifier admits exactly those
+// statements and an adoption migration's calls of the framework's copy and release functions. Pure: tokens in, answers out.
 
 import { type SqlToken, sqlTokens, topLevelStatements, upperWord } from './migration-sql'
 import { nameText } from './sql-names'
@@ -13,6 +13,18 @@ export const FILE_STATUSES = ['pending', 'live', 'quarantined', 'rejected'] as c
 
 export const FILE_TABLE_PREFIX = 'fabrika_files_'
 
+/** Every stored file (`@fabrika/db`'s `0008_files.sql`): an application's file column is a foreign key to its `id`. */
+export const STORED_FILES_TABLE = 'fabrika_files'
+
+/** What an application's last adoption migration of a file collection calls, with the collection's name. */
+export const FILES_RELEASE_FUNCTION = 'fabrika_files_release'
+
+/**
+ * What an adoption migration calls right before it reads a collection's table: it copies the rows an older instance
+ * wrote after `0008_files.sql` ran, so every row the migration adopts has its `fabrika_files` row.
+ */
+export const FILES_COPY_FUNCTION = 'fabrika_files_copy_legacy'
+
 /** The columns the scan job keeps: the scanned object's version, and the retry count and time of a file without a verdict. */
 export const FILE_SCAN_COLUMNS = ['object_version TEXT', 'scan_attempts INTEGER NOT NULL DEFAULT 0', 'scan_after TIMESTAMPTZ'] as const
 
@@ -29,14 +41,14 @@ export function fileScanIndex(table: string): string {
 }
 
 /**
- * The name Postgres gave the unnamed status check of a table an earlier `fileTableSql` created:
+ * The name Postgres gave the unnamed status check of a table an older release's `fileTableSql` created:
  * `<table>_status_check`, the table's name cut to 50 characters first (`makeObjectName`).
  */
 export function legacyStatusCheckName(table: string): string {
 	return `${table.slice(0, 63 - '_status_check'.length)}_status_check`
 }
 
-/** The statement of `fileScanSql` that widens a table an earlier `fileTableSql` created: its check and its columns. */
+/** The statement of an older release's `fileScanSql` that widens its collection table: its check and its columns. */
 export function fileScanAlter(table: string): string {
 	const columns = FILE_SCAN_COLUMNS.map((column) => `ADD COLUMN ${column}`).join(', ')
 	return `ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${legacyStatusCheckName(table)}, ADD ${fileStatusCheck(table)}, ${columns}`

package/src/migration-classify.ts

@@ -3,7 +3,14 @@
 // does not recognise: an allowlist at every level, so a form a later Postgres adds is refused, not executed.
 // Runtime-neutral: Control classifies a commit's migrations in a Worker, the runner before it applies them.
 
-import { FILE_TABLE_PREFIX, fileScanAlterTable, legacyStatusCheckName } from './file-table-ddl'
+import {
+	FILE_TABLE_PREFIX,
+	FILES_COPY_FUNCTION,
+	FILES_RELEASE_FUNCTION,
+	fileScanAlterTable,
+	legacyStatusCheckName,
+	STORED_FILES_TABLE,
+} from './file-table-ddl'
 import { lexSql, type SqlToken, topLevelStatements, upperWord } from './migration-sql'
 import { PG_CATALOG_FUNCTIONS, SQL_KEYWORDS } from './pg-catalog-names'
 import {
@@ -13,6 +20,7 @@ import {
 	dmlForeignSchema,
 	frameworkReference,
 	functionUse,
+	isFrameworkName,
 	isName,
 	isPunct,
 	nameReferences,
@@ -328,7 +336,9 @@ function literalBody(token: SqlToken | undefined): SqlToken[] | undefined {
 function checkBody(tokens: readonly SqlToken[], context: Context): void {
 	const unicode = unicodeIdentifier(tokens)
 	if (unicode !== undefined) throw new Refused('a Unicode-escaped identifier (U&"…")', unicode.line)
-	const framework = context.framework ? undefined : frameworkReference(tokens)
+	// The framework's own bundle is reviewed with the framework: its bodies read the catalog and name tables by value.
+	if (context.framework) return
+	const framework = frameworkReference(tokens)
 	if (framework !== undefined) throw new Refused(`a reference to the framework's ${framework.name}`, framework.line)
 	const execute = tokens.find((token) => upperWord(token) === 'EXECUTE')
 	if (execute !== undefined) throw new Refused('a dynamic EXECUTE in a body', execute.line)
@@ -853,9 +863,9 @@ function classifyComment(tokens: readonly SqlToken[], context: Context): void {
 }
 
 /**
- * The framework names a statement may use: a file collection's table (`fabrika_files_<name>`, `fileTableSql`) is
- * created by the application's own migration, with its status check and its indexes, and `fileScanSql` replaces an
- * earlier status check. Every other framework name is refused.
+ * The framework names a statement may use: a file collection's table (`fabrika_files_<name>`) was created by the
+ * application's own migration under an older release's `fileTableSql`, with its status check and its indexes, and its
+ * `fileScanSql` replaced the status check. Every other framework name is refused.
  */
 function fileTableNames(tokens: readonly SqlToken[]): ReadonlySet<string> {
 	const [first, second] = [upperWord(tokens[0]), upperWord(tokens[1])]
@@ -875,19 +885,54 @@ function fileTableNames(tokens: readonly SqlToken[]): ReadonlySet<string> {
 }
 
 /**
- * The names of `@fabrika/db`'s `fileScanSql` statement, which replaces the status check of a file table an earlier
- * `fileTableSql` created and adds the scan columns: that exact statement, and no other `ALTER` of a file table.
+ * The names of an older release's `fileScanSql` statement, which replaces the status check of its collection table
+ * and adds the scan columns: that exact statement, and no other `ALTER` of a file table.
  */
 function fileScanNames(tokens: readonly SqlToken[]): ReadonlySet<string> {
 	const table = fileScanAlterTable(tokens)
 	return table === undefined ? new Set() : new Set([table, legacyStatusCheckName(table), `${table}_status`])
 }
 
+/**
+ * The tokens a statement's framework names are checked over: without each `REFERENCES fabrika_files`, the foreign key
+ * of a file column (`id`, the table's key, is what it references).
+ */
+function withoutFileReferences(tokens: readonly SqlToken[]): readonly SqlToken[] {
+	return tokens.filter((token, index) => !(nameText(token) === STORED_FILES_TABLE && upperWord(tokens[index - 1]) === 'REFERENCES'))
+}
+
+/**
+ * The framework names an `INSERT` may read: a file collection's table, which an adoption migration copies the owner
+ * mapping out of (`INSERT INTO deal_attachments (…) SELECT … FROM fabrika_files_attachments`). It never writes one.
+ */
+function adoptedTableNames(tokens: readonly SqlToken[]): ReadonlySet<string> {
+	const target = nameText(tokens[skipWords(tokens, 1, 'INTO')])
+	if (upperWord(tokens[0]) !== 'INSERT' || target === undefined || isFrameworkName(target)) return new Set()
+	return new Set(tokens.flatMap((token) => {
+		const name = nameText(token)
+		return name?.startsWith(FILE_TABLE_PREFIX) === true ? [name] : []
+	}))
+}
+
+/**
+ * `SELECT fabrika_files_copy_legacy('<collection>');` and `SELECT fabrika_files_release('<collection>');`: the only
+ * calls of a framework function an application migration makes, each a statement of its own.
+ */
+function isFileAdoptionCall(tokens: readonly SqlToken[]): boolean {
+	const [select, name, open, collection, close] = tokens
+	const called = nameText(name)
+	return tokens.length === 5 && upperWord(select) === 'SELECT' && (called === FILES_COPY_FUNCTION || called === FILES_RELEASE_FUNCTION)
+		&& isPunct(open, '(')
+		&& collection?.kind === 'string' && /^[a-z_][a-z0-9_]*$/.test(collection.text ?? '') && isPunct(close, ')')
+}
+
 function classifyStatement(tokens: readonly SqlToken[], context: Context, out: Collected): void {
 	const line = tokens[0]?.line ?? 1
 	const unicode = unicodeIdentifier(tokens)
 	if (unicode !== undefined) throw new Refused('a Unicode-escaped identifier (U&"…")', unicode.line)
-	const framework = context.framework ? undefined : frameworkReference(tokens, fileTableNames(tokens))
+	if (!context.framework && isFileAdoptionCall(tokens)) return
+	const allowed = new Set([...fileTableNames(tokens), ...adoptedTableNames(tokens)])
+	const framework = context.framework ? undefined : frameworkReference(withoutFileReferences(tokens), allowed)
 	if (framework !== undefined) throw new Refused(`a reference to the framework's ${framework.name}`, framework.line)
 	const first = upperWord(tokens[0])
 	if (first === 'INSERT' || first === 'UPDATE' || first === 'DELETE') return checkQuery(tokens, context, first)

package/src/sql.ts

@@ -33,6 +33,8 @@ export {
 export { lexSql, type SqlToken, sqlTokens, type Statement, topLevelStatements, upperWord } from './migration-sql'
 export { PG_CATALOG_FUNCTIONS, SQL_KEYWORDS } from './pg-catalog-names'
 export {
+	afterName,
+	closingParenthesis,
 	ddlForeignSchema,
 	dmlForeignSchema,
 	dmlRelations,
@@ -40,13 +42,17 @@ export {
 	type FunctionUse,
 	functionUse,
 	isFrameworkName,
+	isPunct,
 	type NameReference,
 	nameReferences,
 	type NameRole,
 	nameText,
 	nestedStatement,
+	objectNameAt,
 	parenthesizedTarget,
 	refusedFunctionCall,
+	skipWords,
+	splitAtCommas,
 	statementKind,
 	unicodeIdentifier,
 } from './sql-names'