@zmdb/compiler 1.0.0-beta.1

package/src/errors.ts

@@ -0,0 +1,6 @@
+/** A stable diagnostic returned by project compilation. */
+export interface CompilerDiagnostic {
+  readonly code: string;
+  readonly message: string;
+  readonly file?: string;
+}

package/src/index.ts

@@ -0,0 +1,336 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+
+import { type NamingStrategy } from '@zmdb/schema/naming';
+
+import { codegen } from './codegen/index.js';
+import { artifactPaths, isGeneratedPath } from './codegen/witness.js';
+import type { CompilerDiagnostic } from './errors.js';
+import { openPreparedSession, type ReflectSession } from './reflect/session.js';
+
+export { watchCodegen, type CodegenOptions, type CodegenResult, type WatchOptions } from './codegen/index.js';
+
+export type { CompilerDiagnostic } from './errors.js';
+export { zmdbAot, type ConfiguredZmdbAotOptions } from './configured-plugin.js';
+
+export interface CompileProjectOptions {
+  readonly project: string;
+  readonly files?: readonly string[];
+  readonly naming?: NamingStrategy;
+}
+
+export interface CompiledArtifact {
+  /** Rewritten application source. Its path is the matching member of `CompileResult.files`. */
+  readonly source: string;
+  readonly witnessPath: string;
+  readonly runtimePath: string;
+  readonly declarationPath: string;
+  readonly witness: string;
+  readonly runtime: string;
+  readonly declaration: string;
+}
+
+export interface CompileResult {
+  readonly project: string;
+  readonly files: readonly string[];
+  readonly artifacts: readonly CompiledArtifact[];
+  readonly diagnostics: readonly CompilerDiagnostic[];
+  readonly dependencies: readonly string[];
+}
+
+export interface WriteCompileResultOptions {
+  readonly check?: boolean;
+}
+
+export interface WriteCompileResult {
+  readonly written: readonly string[];
+  readonly deleted: readonly string[];
+  readonly stale: readonly string[];
+}
+
+interface SelectedProject {
+  readonly files: readonly string[];
+  readonly shadowFiles: readonly string[];
+  readonly dependencies: readonly string[];
+  readonly diagnostics: readonly CompilerDiagnostic[];
+}
+
+/**
+ * Compile one project without changing it.
+ *
+ * The existing codegen pipeline runs against a disposable sibling shadow. Keeping the
+ * shadow at the same directory depth preserves relative `extends` and `paths` entries,
+ * while the real project remains byte-for-byte untouched until `writeCompileResult`.
+ */
+export async function compileProject(options: CompileProjectOptions): Promise<CompileResult> {
+  const project = resolve(options.project);
+  const root = dirname(project);
+  const shadow = mkdtempSync(join(dirname(root), `.zmdb-compile-${basename(root)}-`));
+  try {
+    copyProject(root, shadow);
+    const shadowProject = join(shadow, relative(root, project));
+    let session: ReflectSession;
+    try {
+      session = openPreparedSession({ project: shadowProject }, config =>
+        writeGeneratedProject(shadowProject, config.fileNames),
+      );
+    } catch (error: unknown) {
+      return {
+        project,
+        files: [],
+        artifacts: [],
+        diagnostics: [
+          {
+            code: 'ZMDB_PROJECT',
+            message: error instanceof Error ? error.message : String(error),
+            file: project,
+          },
+        ],
+        dependencies: [],
+      };
+    }
+
+    try {
+      const selected = selectProjectFiles(session, project, shadowProject, options.files);
+      if (selected.diagnostics.length > 0) {
+        return {
+          project,
+          files: selected.files,
+          artifacts: [],
+          diagnostics: selected.diagnostics,
+          dependencies: selected.dependencies,
+        };
+      }
+
+      const generated = codegen({
+        project: session.project,
+        files: selected.shadowFiles,
+        session,
+        ...(options.naming === undefined ? {} : { naming: options.naming }),
+      });
+      const diagnostics = generated.problems.map((message): CompilerDiagnostic => ({ code: 'ZMDB_COMPILE', message }));
+      const artifacts = selected.files.flatMap((file, index): readonly CompiledArtifact[] => {
+        const shadowFile = selected.shadowFiles[index];
+        if (shadowFile === undefined) return [];
+        const shadowPaths = artifactPaths(shadowFile);
+        if (!existsSync(shadowPaths.witness) || !existsSync(shadowPaths.js) || !existsSync(shadowPaths.dts)) {
+          return [];
+        }
+        const paths = artifactPaths(file);
+        return [
+          {
+            source: readFileSync(shadowFile, 'utf8'),
+            witnessPath: paths.witness,
+            runtimePath: paths.js,
+            declarationPath: paths.dts,
+            witness: readFileSync(shadowPaths.witness, 'utf8'),
+            runtime: readFileSync(shadowPaths.js, 'utf8'),
+            declaration: readFileSync(shadowPaths.dts, 'utf8'),
+          },
+        ];
+      });
+
+      return {
+        project,
+        files: selected.files,
+        artifacts,
+        diagnostics,
+        dependencies: selected.dependencies,
+      };
+    } finally {
+      session.close();
+    }
+  } finally {
+    rmSync(shadow, { recursive: true, force: true });
+  }
+}
+
+function writeGeneratedProject(project: string, files: readonly string[]): string {
+  const root = dirname(project);
+  const prepared = join(root, '.zmdb-compile.tsconfig.json');
+  const extended = relative(root, project).replaceAll(sep, '/');
+  const roots = files.map(file => relative(root, file).replaceAll(sep, '/')).toSorted();
+  writeFileSync(
+    prepared,
+    `${JSON.stringify(
+      {
+        extends: extended.startsWith('.') ? extended : `./${extended}`,
+        files: roots,
+        include: ['**/*.zmdb.witness.ts'],
+        exclude: [],
+      },
+      undefined,
+      2,
+    )}\n`,
+  );
+  return prepared;
+}
+
+/** Apply or check one previously compiled result. No compilation occurs here. */
+export async function writeCompileResult(
+  result: CompileResult,
+  options: WriteCompileResultOptions = {},
+): Promise<WriteCompileResult> {
+  const expected = new Map<string, string>();
+  const artifactByWitness = new Map(result.artifacts.map(artifact => [pathKey(artifact.witnessPath), artifact]));
+
+  for (const file of result.files) {
+    const paths = artifactPaths(file);
+    const artifact = artifactByWitness.get(pathKey(paths.witness));
+    if (artifact === undefined) continue;
+    expected.set(file, artifact.source);
+    expected.set(paths.witness, artifact.witness);
+    expected.set(paths.js, artifact.runtime);
+    expected.set(paths.dts, artifact.declaration);
+  }
+
+  const stale: string[] = [];
+  const deletions: string[] = [];
+  for (const file of result.files) {
+    const paths = artifactPaths(file);
+    if (artifactByWitness.has(pathKey(paths.witness))) continue;
+    for (const path of [paths.witness, paths.js, paths.dts]) {
+      if (existsSync(path)) {
+        deletions.push(path);
+        stale.push(path);
+      }
+    }
+  }
+
+  for (const [path, source] of expected) {
+    if (readText(path) !== source) stale.push(path);
+  }
+
+  const orderedStale = [...new Set(stale)].toSorted();
+  const orderedDeleted = [...new Set(deletions)].toSorted();
+  if (options.check === true) {
+    return { written: [], deleted: orderedDeleted, stale: orderedStale };
+  }
+
+  for (const path of orderedDeleted) unlinkSync(path);
+  const written: string[] = [];
+  let sequence = 0;
+  for (const path of orderedStale) {
+    const source = expected.get(path);
+    if (source === undefined) continue;
+    writeAtomic(path, source, sequence++);
+    written.push(path);
+  }
+  return { written, deleted: orderedDeleted, stale: orderedStale };
+}
+
+function selectProjectFiles(
+  session: ReflectSession,
+  project: string,
+  shadowProject: string,
+  requested: readonly string[] | undefined,
+): SelectedProject {
+  const root = dirname(project);
+  const shadowRoot = dirname(shadowProject);
+  const members = new Map(
+    session
+      .sourceFileNames()
+      .filter(file => isProjectSource(file, shadowRoot))
+      .map(shadowFile => {
+        const file = normalize(join(root, relative(shadowRoot, shadowFile)));
+        return [pathKey(file), { file, shadowFile: normalize(shadowFile) }] as const;
+      }),
+  );
+  const diagnostics: CompilerDiagnostic[] = [];
+  const selected: { readonly file: string; readonly shadowFile: string }[] = [];
+  const seen = new Set<string>();
+  const candidates =
+    requested === undefined
+      ? [...members.values()].map(member => member.file)
+      : requested.map(file => normalize(isAbsolute(file) ? file : resolve(root, file)));
+
+  for (const file of candidates) {
+    const key = pathKey(file);
+    if (seen.has(key)) {
+      diagnostics.push({ code: 'ZMDB_DUPLICATE_FILE', message: `duplicate project file ${file}`, file });
+      continue;
+    }
+    seen.add(key);
+    if (isGeneratedPath(file)) {
+      diagnostics.push({ code: 'ZMDB_GENERATED_INPUT', message: `generated input is not compilable: ${file}`, file });
+      continue;
+    }
+    const member = members.get(key);
+    if (member === undefined) {
+      diagnostics.push({
+        code: 'ZMDB_PROJECT_MEMBER',
+        message: `${file} is not a source member of ${project}`,
+        file,
+      });
+      continue;
+    }
+    selected.push(member);
+  }
+
+  const ordered = selected.toSorted((left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0));
+  const selectedPaths = new Set(ordered.map(member => pathKey(member.file)));
+  const dependencies = [...members.values()]
+    .filter(member => !selectedPaths.has(pathKey(member.file)))
+    .map(member => member.file)
+    .toSorted();
+  return {
+    files: ordered.map(member => member.file),
+    shadowFiles: ordered.map(member => member.shadowFile),
+    dependencies,
+    diagnostics,
+  };
+}
+
+function isProjectSource(file: string, root: string): boolean {
+  if (file.includes(`${sep}node_modules${sep}`) || file.includes('/node_modules/')) return false;
+  if (/\.d\.[cm]?ts$/.test(file) || !/\.[cm]?tsx?$/.test(file) || isGeneratedPath(file)) return false;
+  const inside = relative(root, file);
+  return inside.length > 0 && !inside.startsWith('..') && !isAbsolute(inside);
+}
+
+function copyProject(root: string, shadow: string): void {
+  cpSync(root, shadow, {
+    recursive: true,
+    filter(source) {
+      const name = basename(source);
+      return name !== '.git' && name !== 'node_modules';
+    },
+  });
+  const modules = join(root, 'node_modules');
+  if (existsSync(modules)) symlinkSync(modules, join(shadow, 'node_modules'), 'dir');
+}
+
+function pathKey(path: string): string {
+  const value = normalize(path);
+  return process.platform === 'win32' ? value.toLowerCase() : value;
+}
+
+function readText(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+function writeAtomic(path: string, source: string, sequence: number): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = join(dirname(path), `.${basename(path)}.zmdb-${String(process.pid)}-${String(sequence)}`);
+  try {
+    writeFileSync(temporary, source);
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) rmSync(temporary, { force: true });
+  }
+}

package/src/lint/ast.ts

@@ -0,0 +1,96 @@
+import type { VisitorNode } from './host-types.js';
+
+type CallExpressionNode = VisitorNode<'CallExpression'>;
+type ImportDeclarationNode = VisitorNode<'ImportDeclaration'>;
+type ImportSpecifierNode = Extract<ImportDeclarationNode['specifiers'][number], { type: 'ImportSpecifier' }>;
+type ProgramNode = VisitorNode<'Program'>;
+type PropertyNode = VisitorNode<'Property'>;
+type TSInterfaceDeclarationNode = VisitorNode<'TSInterfaceDeclaration'>;
+type TSTypeNode = VisitorNode<'TSIntersectionType'>['types'][number];
+
+const TAG_MODULES: ReadonlySet<string> = new Set(['@zmdb/schema/tags', 'zmdb/tags']);
+const TAG_EXPORTS: ReadonlySet<string> = new Set([
+  'AnyRelation',
+  'Codec',
+  'Ext',
+  'Fts',
+  'HasDefault',
+  'Length',
+  'ManyToMany',
+  'ManyToOne',
+  'Max',
+  'MaxLength',
+  'Min',
+  'MinLength',
+  'Numeric',
+  'OneToMany',
+  'OneToOne',
+  'Pattern',
+  'PrimaryKey',
+  'Proto',
+  'ProtoField',
+  'References',
+  'Rule',
+  'Sensitive',
+  'Serial',
+  'Sql',
+  'Table',
+  'Unique',
+  'WireAs',
+]);
+
+export interface ImportedTagBindings {
+  readonly tables: ReadonlySet<string>;
+  readonly tags: ReadonlySet<string>;
+}
+
+function importedName(specifier: ImportSpecifierNode): string {
+  return specifier.imported.type === 'Identifier' ? specifier.imported.name : specifier.imported.value;
+}
+
+export function importedTagBindings(program: ProgramNode): ImportedTagBindings {
+  const tables = new Set<string>();
+  const tags = new Set<string>();
+
+  for (const statement of program.body) {
+    if (statement.type !== 'ImportDeclaration' || !TAG_MODULES.has(statement.source.value)) continue;
+    for (const specifier of statement.specifiers) {
+      if (specifier.type !== 'ImportSpecifier') continue;
+      const imported = importedName(specifier);
+      if (TAG_EXPORTS.has(imported)) tags.add(specifier.local.name);
+      if (imported === 'Table') tables.add(specifier.local.name);
+    }
+  }
+
+  return { tables, tags };
+}
+
+export function isTableDeclaration(node: TSInterfaceDeclarationNode, bindings: ImportedTagBindings): boolean {
+  return node.extends.some(
+    heritage =>
+      heritage.expression.type === 'Identifier' &&
+      bindings.tables.has(heritage.expression.name) &&
+      heritage.typeArguments?.params.length === 1,
+  );
+}
+
+export function isImportedTagReference(node: TSTypeNode, bindings: ImportedTagBindings): boolean {
+  return (
+    node.type === 'TSTypeReference' && node.typeName.type === 'Identifier' && bindings.tags.has(node.typeName.name)
+  );
+}
+
+export function staticMemberName(callee: CallExpressionNode['callee']): string | undefined {
+  if (callee.type !== 'MemberExpression') return undefined;
+  if (!callee.computed && callee.property.type === 'Identifier') return callee.property.name;
+  if (callee.computed && callee.property.type === 'Literal' && typeof callee.property.value === 'string') {
+    return callee.property.value;
+  }
+  return undefined;
+}
+
+export function staticPropertyName(property: PropertyNode): string | undefined {
+  if (!property.computed && property.key.type === 'Identifier') return property.key.name;
+  if (property.key.type === 'Literal' && typeof property.key.value === 'string') return property.key.value;
+  return undefined;
+}

package/src/lint/host-types.ts

@@ -0,0 +1,9 @@
+import type { RuleTester } from 'oxlint/plugins-dev';
+
+type Rule = Parameters<RuleTester['run']>[1];
+
+export type HostLintRule = Extract<Rule, { create: unknown }>;
+
+type LintVisitor = ReturnType<HostLintRule['create']>;
+
+export type VisitorNode<Name extends keyof LintVisitor> = Parameters<NonNullable<LintVisitor[Name]>>[0];

package/src/lint/index.ts

@@ -0,0 +1,80 @@
+import { noDistributedNullableTags } from './rules/no-distributed-nullable-tags.js';
+import { noEmptyPatch } from './rules/no-empty-patch.js';
+import { noInterpolatedSql } from './rules/no-interpolated-sql.js';
+import { noUnboundedFind } from './rules/no-unbounded-find.js';
+import { noUnknownJsonColumn } from './rules/no-unknown-json-column.js';
+import { requireSqlOnNumber } from './rules/require-sql-on-number.js';
+import type { LintRule } from './types.js';
+
+export type { LintRule } from './types.js';
+
+interface LintPlugin {
+  readonly meta: {
+    readonly name: string;
+    readonly version: string;
+  };
+  readonly rules: Readonly<Record<string, LintRule>>;
+}
+
+type Severity = 'error' | 'warn';
+
+interface FlatConfig {
+  readonly name: string;
+  readonly plugins: Readonly<Record<string, LintPlugin>>;
+  readonly rules: Readonly<Record<string, Severity>>;
+}
+
+interface LintConfigs {
+  readonly recommended: readonly FlatConfig[];
+  readonly strict: readonly FlatConfig[];
+}
+
+const rules: Readonly<Record<string, LintRule>> = {
+  'no-distributed-nullable-tags': noDistributedNullableTags,
+  'no-empty-patch': noEmptyPatch,
+  'no-interpolated-sql': noInterpolatedSql,
+  'no-unbounded-find': noUnboundedFind,
+  'no-unknown-json-column': noUnknownJsonColumn,
+  'require-sql-on-number': requireSqlOnNumber,
+};
+
+const plugin: LintPlugin = {
+  meta: {
+    name: '@zmdb/compiler',
+    version: '1.0.0-beta.1',
+  },
+  rules,
+};
+
+export const configs: LintConfigs = {
+  recommended: [
+    {
+      name: 'zmdb/recommended',
+      plugins: { zmdb: plugin },
+      rules: {
+        'zmdb/no-distributed-nullable-tags': 'error',
+        'zmdb/no-empty-patch': 'warn',
+        'zmdb/no-interpolated-sql': 'error',
+        'zmdb/no-unbounded-find': 'warn',
+        'zmdb/no-unknown-json-column': 'error',
+        'zmdb/require-sql-on-number': 'warn',
+      },
+    },
+  ],
+  strict: [
+    {
+      name: 'zmdb/strict',
+      plugins: { zmdb: plugin },
+      rules: {
+        'zmdb/no-distributed-nullable-tags': 'error',
+        'zmdb/no-empty-patch': 'error',
+        'zmdb/no-interpolated-sql': 'error',
+        'zmdb/no-unbounded-find': 'error',
+        'zmdb/no-unknown-json-column': 'error',
+        'zmdb/require-sql-on-number': 'error',
+      },
+    },
+  ],
+};
+
+export default plugin;

package/src/lint/rules/no-distributed-nullable-tags.ts

@@ -0,0 +1,76 @@
+import { importedTagBindings, isImportedTagReference, isTableDeclaration, type ImportedTagBindings } from '../ast.js';
+import type { HostLintRule, VisitorNode } from '../host-types.js';
+
+type TSTypeNode = VisitorNode<'TSIntersectionType'>['types'][number];
+type TSUnionTypeNode = VisitorNode<'TSUnionType'>;
+
+const message = 'Move null and undefined outside the tagged intersection; nullish values cannot carry zmdb tags.';
+
+function isNullish(node: TSTypeNode): boolean {
+  return node.type === 'TSNullKeyword' || node.type === 'TSUndefinedKeyword';
+}
+
+export const noDistributedNullableTags: HostLintRule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Keep nullable arms outside intersections with zmdb declaration tags.',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: { distributed: message },
+    schema: [],
+  },
+  create(context) {
+    let bindings: ImportedTagBindings = { tables: new Set<string>(), tags: new Set<string>() };
+
+    return {
+      Program(node) {
+        bindings = importedTagBindings(node);
+      },
+      TSInterfaceDeclaration(node) {
+        if (!isTableDeclaration(node, bindings)) return;
+
+        for (const property of node.body.body) {
+          if (property.type !== 'TSPropertySignature') continue;
+          const annotation = property.typeAnnotation?.typeAnnotation;
+          if (annotation?.type !== 'TSIntersectionType') continue;
+
+          let nullableUnion: TSUnionTypeNode | undefined;
+          const tags: TSTypeNode[] = [];
+          let unsafe = false;
+
+          for (const member of annotation.types) {
+            if (member.type === 'TSUnionType') {
+              const nullishCount = member.types.filter(isNullish).length;
+              if (nullishCount === 1 && nullableUnion === undefined) {
+                nullableUnion = member;
+                continue;
+              }
+            }
+            if (isImportedTagReference(member, bindings)) tags.push(member);
+            else unsafe = true;
+          }
+
+          if (unsafe || nullableUnion === undefined || tags.length === 0) continue;
+          const nullish = nullableUnion.types.find(isNullish);
+          if (nullish === undefined) continue;
+          const data = nullableUnion.types.filter(member => !isNullish(member));
+          if (data.length === 0) continue;
+
+          const tagText = tags.map(tag => context.sourceCode.getText(tag)).join(' & ');
+          const replacement = [
+            ...data.map(member => `(${context.sourceCode.getText(member)} & ${tagText})`),
+            context.sourceCode.getText(nullish),
+          ].join(' | ');
+
+          context.report({
+            node: annotation,
+            messageId: 'distributed',
+            fix: fixer => fixer.replaceText(annotation, replacement),
+          });
+        }
+      },
+    };
+  },
+};

package/src/lint/rules/no-empty-patch.ts

@@ -0,0 +1,26 @@
+import { staticMemberName } from '../ast.js';
+import type { HostLintRule } from '../host-types.js';
+
+const message = 'update(id, {}) performs no write; it reads and returns the matching row.';
+
+export const noEmptyPatch: HostLintRule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Report update calls whose literal patch is empty.',
+      recommended: true,
+    },
+    messages: { emptyPatch: message },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (staticMemberName(node.callee) !== 'update') return;
+        const patch = node.arguments[1];
+        if (patch?.type !== 'ObjectExpression' || patch.properties.length !== 0) return;
+        context.report({ node: patch, messageId: 'emptyPatch' });
+      },
+    };
+  },
+};

package/src/lint/rules/no-interpolated-sql.ts

@@ -0,0 +1,45 @@
+import { staticMemberName, staticPropertyName } from '../ast.js';
+import type { HostLintRule, VisitorNode } from '../host-types.js';
+
+type TemplateLiteralNode = VisitorNode<'TemplateLiteral'>;
+
+const message = 'Do not interpolate values into SQL text; use driver parameters.';
+
+function isSqlSink(node: TemplateLiteralNode): boolean {
+  const parent = node.parent;
+  if (
+    parent.type === 'Property' &&
+    parent.parent.type === 'ObjectExpression' &&
+    staticPropertyName(parent) === 'text' &&
+    parent.parent.properties.some(
+      property => property.type === 'Property' && staticPropertyName(property) === 'parameters',
+    )
+  ) {
+    return true;
+  }
+  return (
+    parent.type === 'CallExpression' &&
+    staticMemberName(parent.callee) === 'execute' &&
+    parent.arguments.some(argument => argument === node)
+  );
+}
+
+export const noInterpolatedSql: HostLintRule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Report interpolated template literals used directly as SQL text.',
+      recommended: true,
+    },
+    messages: { interpolation: message },
+    schema: [],
+  },
+  create(context) {
+    return {
+      TemplateLiteral(node) {
+        if (node.expressions.length === 0 || !isSqlSink(node)) return;
+        context.report({ node, messageId: 'interpolation' });
+      },
+    };
+  },
+};