@an5/orm 1.0.9 → 1.1.0

package/dist/provider-support.d.ts

@@ -0,0 +1,27 @@
+import { Provider } from './generator/src/field-types';
+/**
+ * Which commands can only run against SQL Server.
+ *
+ * `db:push` is not among them: it goes through the dialect layer in
+ * `./generator/src/dialect`, so it writes the DDL each provider understands. These
+ * three do not — they read `sys.tables`/`sys.columns`/`sys.foreign_keys`, quote
+ * identifiers with brackets, and emit T-SQL. Running them against another database
+ * fails on the first catalog query with a driver error that says nothing about the
+ * real problem, or worse, half-applies a change before it does. So the provider is
+ * checked up front, where the message can name it.
+ *
+ * Not a reason to narrow the type tables though: the tables describe what each
+ * provider accepts, which is what the generated client and the schema files must
+ * stay within, whoever runs the commands.
+ */
+export declare const SQL_SERVER_ONLY_COMMANDS: Record<string, string>;
+/**
+ * Why a command cannot run against this provider, or null when it can.
+ *
+ * Returns the message instead of printing it and exiting, so this stays a plain
+ * function: it is shared by four command files, and a module that calls
+ * `process.exit` cannot be imported outside a Node CLI — nor unit tested for the
+ * thing it exists to say.
+ */
+export declare function sqlServerOnlyError(provider: Provider, command: string): string | null;
+//# sourceMappingURL=provider-support.d.ts.map

package/dist/provider-support.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQL_SERVER_ONLY_COMMANDS = void 0;
+exports.sqlServerOnlyError = sqlServerOnlyError;
+const field_types_1 = require("./generator/src/field-types");
+/**
+ * Which commands can only run against SQL Server.
+ *
+ * `db:push` is not among them: it goes through the dialect layer in
+ * `./generator/src/dialect`, so it writes the DDL each provider understands. These
+ * three do not — they read `sys.tables`/`sys.columns`/`sys.foreign_keys`, quote
+ * identifiers with brackets, and emit T-SQL. Running them against another database
+ * fails on the first catalog query with a driver error that says nothing about the
+ * real problem, or worse, half-applies a change before it does. So the provider is
+ * checked up front, where the message can name it.
+ *
+ * Not a reason to narrow the type tables though: the tables describe what each
+ * provider accepts, which is what the generated client and the schema files must
+ * stay within, whoever runs the commands.
+ */
+exports.SQL_SERVER_ONLY_COMMANDS = {
+    'db:pull': 'read the catalog and write schema files',
+    'db:migrate': 'diff the schema against the database and apply migrations',
+    'db:migrate:diff': 'diff the schema against the database',
+    'db:migrate:generate': 'write a migration file from the schema files',
+    'db:migrate:apply': 'apply pending migrations',
+    'db:migrate:rollback': 'roll a migration back',
+    'db:migrate:status': 'list schema models, database tables and migration state',
+    'db:cleanup': 'drop tables and foreign keys that are no longer in the schema',
+};
+/**
+ * Why a command cannot run against this provider, or null when it can.
+ *
+ * Returns the message instead of printing it and exiting, so this stays a plain
+ * function: it is shared by four command files, and a module that calls
+ * `process.exit` cannot be imported outside a Node CLI — nor unit tested for the
+ * thing it exists to say.
+ */
+function sqlServerOnlyError(provider, command) {
+    if (provider === 'mssql')
+        return null;
+    const what = exports.SQL_SERVER_ONLY_COMMANDS[command] ?? 'run';
+    return (`❌ ${command} only supports SQL Server, but the connection string selects ` +
+        `${field_types_1.PROVIDER_LABELS[provider]}.\n` +
+        `   ${command} ${what} using sys.* catalog views and T-SQL, so pointing it at ` +
+        `${field_types_1.PROVIDER_LABELS[provider]} would run the wrong SQL.\n` +
+        '   Use a SQL Server connection string, or generate and apply the schema with ' +
+        `${field_types_1.PROVIDER_LABELS[provider]}'s own tooling.`);
+}
+//# sourceMappingURL=provider-support.js.map

package/generator/src/api.ts

@@ -0,0 +1,45 @@
+/**
+ * Side-effect-free entrypoint for programmatic use of the code generator.
+ *
+ * Importing `./index` runs the CLI (`main()`), so tooling that wants to drive
+ * the generator in-process — such as the an5Agent `generateClientCode` tool —
+ * imports this module instead.
+ *
+ * The provider is optional and defaults to SQL Server. Pass one derived from
+ * the connection string when the schema targets another database, so field
+ * types are checked against that database's types — `providerForProject` reads
+ * it from the config file for callers that only know the project directory:
+ *
+ * ```ts
+ * import { SchemaParser, RustGenerator, providerForProject } from '@an5/orm/generator';
+ *
+ * const provider = providerForProject(__dirname);
+ * const models = await new SchemaParser('an5Schema', provider).parse();
+ * new RustGenerator('an5Client/rust').generate(models);
+ * ```
+ */
+export { SchemaParser, sqlTypeToTs } from './parser';
+export { CodeGenerator } from './code-generator';
+export { MetadataGenerator } from './metadata-generator';
+export { PythonGenerator } from './python-generator';
+export { DotnetGenerator } from './dotnet-generator';
+export { GolangGenerator } from './golang-generator';
+export { RustGenerator } from './rust-generator';
+export { detectProvider, providerFromConfig, providerForProject } from './config';
+export { dialectFor, defaultClause, sqlLiteral } from './dialect';
+export { fieldKind } from './type-kinds';
+export type { FieldKind } from './type-kinds';
+export type { ColumnSpec, PushDialect } from './dialect';
+export {
+  DEFAULT_PROVIDER,
+  FieldTypeError,
+  PROVIDERS,
+  PROVIDER_FIELD_TYPES,
+  PROVIDER_LABELS,
+  defaultSqlTypeForTs,
+  fieldTypesFor,
+  resolveFieldType,
+  unknownFieldTypeMessage,
+} from './field-types';
+export type { FieldTypeIssue, Provider, TsType } from './field-types';
+export type { Model, Field, Relation } from './types';

package/generator/src/config.ts

@@ -0,0 +1,496 @@
+/**
+ * Loading and validation for an5Orm.config.js
+ *
+ * The config used to be read as `any` and every field fell back through
+ * `config.outputs?.typescript?.outputDir || 'default'`. That made a typo
+ * invisible: `outputDirs` was not an error, it just quietly wrote to the
+ * default directory while the config file said otherwise.
+ *
+ * So the file is described once, here, and validated before anything uses it.
+ * A wrong type or an unknown key stops generation with a message naming the
+ * offending path, rather than being discovered later as output in the wrong
+ * place.
+ */
+import fs from 'fs';
+import path from 'path';
+import { DEFAULT_PROVIDER, Provider } from './field-types';
+import { suggest } from './suggest';
+
+/** TypeScript client output. */
+export interface TypeScriptOutput {
+  /** Directory for the generated .ts files. */
+  outputDir: string;
+  /** Path of the generated metadata module. */
+  metadataFile: string;
+}
+
+export interface PythonOutput {
+  /** Path of the generated metadata module. */
+  metadataFile: string;
+}
+
+export interface DotnetOutput {
+  outputDir: string;
+}
+
+export interface GolangOutput {
+  outputDir: string;
+}
+
+export interface RustOutput {
+  outputDir: string;
+}
+
+export interface An5OrmConfig {
+  /**
+   * Database connection for the commands that need one — db:push, db:pull,
+   * db:migrate:*, db:cleanup.
+   *
+   * Optional on purpose: DATABASE_URL overrides it, so a checked-in config can
+   * hold a development database while CI supplies its own. Leave it unset
+   * rather than committing a password, and keep secrets in the environment.
+   *
+   * `| undefined` is explicit because the project compiles with
+   * exactOptionalPropertyTypes, which otherwise rejects an omitted value.
+   */
+  connectionString?: string | undefined;
+  /** Schema directory, relative to the config file. */
+  schemaDir: string;
+  outputs: {
+    typescript: TypeScriptOutput;
+    python: PythonOutput;
+    dotnet: DotnetOutput;
+    golang: GolangOutput;
+    rust: RustOutput;
+  };
+  pull: {
+    /** Regex patterns; tables matching any of them are skipped by db:pull. */
+    exclude: string[];
+    /** Keep relations that already exist in the schema. */
+    preserveRelations: boolean;
+  };
+  generation: {
+    /** Write the metadata module alongside the client. */
+    generateMetadata: boolean;
+  };
+}
+
+export const DEFAULT_CONFIG: An5OrmConfig = {
+  schemaDir: 'an5Schema',
+  outputs: {
+    typescript: {
+      outputDir: 'an5Client/typescript',
+      metadataFile: 'an5Client/typescript/an5Metadata.ts',
+    },
+    python: { metadataFile: 'an5Client/python/an5_metadata.py' },
+    dotnet: { outputDir: 'an5Client/dotnet' },
+    golang: { outputDir: 'an5Client/golang' },
+    rust: { outputDir: 'an5Client/rust' },
+  },
+  pull: {
+    exclude: ['^__', '^sys\\.', '^igrations'],
+    preserveRelations: true,
+  },
+  generation: {
+    generateMetadata: true,
+  },
+};
+
+/** Output paths resolved against the config file's directory. */
+export interface ResolvedOutputs {
+  schemaDir: string;
+  typescriptDir: string;
+  typescriptMetadataFile: string;
+  pythonMetadataFile: string;
+  dotnetDir: string;
+  golangDir: string;
+  rustDir: string;
+}
+
+export function resolveOutputs(config: An5OrmConfig, rootDir: string): ResolvedOutputs {
+  const resolve = (relative: string) => path.resolve(rootDir, relative);
+  return {
+    schemaDir: resolve(config.schemaDir),
+    typescriptDir: resolve(config.outputs.typescript.outputDir),
+    typescriptMetadataFile: resolve(config.outputs.typescript.metadataFile),
+    pythonMetadataFile: resolve(config.outputs.python.metadataFile),
+    dotnetDir: resolve(config.outputs.dotnet.outputDir),
+    golangDir: resolve(config.outputs.golang.outputDir),
+    rustDir: resolve(config.outputs.rust.outputDir),
+  };
+}
+
+/**
+ * The environment variables a caller can pass in.
+ *
+ * Spelled structurally rather than as `NodeJS.ProcessEnv`: that type is a Node
+ * global, and a parameter type ends up in the emitted `.d.ts`, so any consumer
+ * without `@types/node` would fail to compile against this package. `process.env` is
+ * assignable to it, and so is a plain `{}` in a test.
+ */
+export type EnvLike = Record<string, string | undefined>;
+
+/** One problem found in the config file. */
+export interface ConfigIssue {
+  /** Dotted path, e.g. `outputs.typescript.outputDir`. */
+  path: string;
+  message: string;
+}
+
+export class ConfigError extends Error {
+  readonly issues: ConfigIssue[];
+
+  constructor(issues: ConfigIssue[]) {
+    super('Invalid an5Orm.config.js');
+    this.issues = issues;
+  }
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return typeof value;
+}
+
+/**
+ * Validates one level of an object: every key is known, every value has the
+ * expected primitive shape. Returns the accepted value.
+ */
+type FieldSpec = 'string' | 'string[]' | 'boolean' | 'object';
+
+function checkObject(
+  raw: unknown,
+  spec: Record<string, FieldSpec>,
+  at: string,
+  issues: ConfigIssue[],
+): Record<string, unknown> {
+  if (raw === undefined) return {};
+  if (typeName(raw) !== 'object' || Array.isArray(raw)) {
+    issues.push({ path: at, message: `expected an object, received ${typeName(raw)}` });
+    return {};
+  }
+
+  const source = raw as Record<string, unknown>;
+  const accepted: Record<string, unknown> = {};
+
+  for (const key of Object.keys(source)) {
+    if (!(key in spec)) {
+      const hint = suggest(key, Object.keys(spec));
+      issues.push({
+        path: at ? `${at}.${key}` : key,
+        message: hint
+          ? `unknown option; did you mean "${hint}"?`
+          : `unknown option; expected one of ${Object.keys(spec).map((k) => `"${k}"`).join(', ')}`,
+      });
+      continue;
+    }
+
+    const expected = spec[key]!;
+    const value = source[key];
+    const here = at ? `${at}.${key}` : key;
+
+    if (expected === 'object') {
+      // Only the shape is checked here. A nested section is validated by the
+      // caller with its own key list, so this must not look at the keys — it
+      // has no spec for them and would reject all of them as unknown.
+      if (value !== undefined && (typeName(value) !== 'object' || Array.isArray(value))) {
+        issues.push({ path: here, message: `expected an object, received ${typeName(value)}` });
+        continue;
+      }
+      accepted[key] = value;
+      continue;
+    }
+
+    if (value === undefined) continue;
+
+    if (expected === 'string[]') {
+      if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        issues.push({ path: here, message: `expected an array of strings, received ${typeName(value)}` });
+        continue;
+      }
+      accepted[key] = value;
+      continue;
+    }
+
+    if (typeof value !== expected) {
+      issues.push({
+        path: here,
+        message: `expected a${expected === 'string' ? ' string' : ` ${expected}`}, received ${typeName(value)}`,
+      });
+      continue;
+    }
+
+    accepted[key] = value;
+  }
+
+  return accepted;
+}
+
+const OUTPUT_SPEC: Record<string, FieldSpec> = {
+  typescript: 'object',
+  python: 'object',
+  dotnet: 'object',
+  golang: 'object',
+  rust: 'object',
+};
+
+const OUTPUT_SECTION_SPEC: Record<string, Record<string, FieldSpec>> = {
+  typescript: { outputDir: 'string', metadataFile: 'string' },
+  python: { metadataFile: 'string' },
+  dotnet: { outputDir: 'string' },
+  golang: { outputDir: 'string' },
+  rust: { outputDir: 'string' },
+};
+
+const TOP_LEVEL_SPEC: Record<string, FieldSpec> = {
+  connectionString: 'string',
+  schemaDir: 'string',
+  outputs: 'object',
+  pull: 'object',
+  generation: 'object',
+};
+
+const PULL_SPEC: Record<string, FieldSpec> = {
+  exclude: 'string[]',
+  preserveRelations: 'boolean',
+};
+
+const GENERATION_SPEC: Record<string, FieldSpec> = {
+  generateMetadata: 'boolean',
+};
+
+/**
+ * Checks a loaded config object and returns it with defaults applied.
+ * Throws ConfigError listing every problem found, not just the first.
+ */
+export function validateConfig(raw: unknown): An5OrmConfig {
+  const issues: ConfigIssue[] = [];
+
+  const top = checkObject(raw, TOP_LEVEL_SPEC, '', issues);
+  const rawOutputs = checkObject(top.outputs, OUTPUT_SPEC, 'outputs', issues);
+  // Each output section has its own allowed keys, so a typo in one is caught
+  // where it was written rather than as a missing value much later.
+  const outputs: Record<string, Record<string, unknown>> = {};
+  for (const section of Object.keys(OUTPUT_SECTION_SPEC)) {
+    outputs[section] = checkObject(
+      rawOutputs[section],
+      OUTPUT_SECTION_SPEC[section]!,
+      `outputs.${section}`,
+      issues,
+    );
+  }
+  const pull = checkObject(top.pull, PULL_SPEC, 'pull', issues);
+  const generation = checkObject(top.generation, GENERATION_SPEC, 'generation', issues);
+
+  if (issues.length > 0) throw new ConfigError(issues);
+
+  return {
+    // Absent rather than defaulted: there is no sensible fallback connection.
+    connectionString: top.connectionString as string | undefined,
+    schemaDir: (top.schemaDir as string) ?? DEFAULT_CONFIG.schemaDir,
+    outputs: {
+      typescript: {
+        outputDir:
+          (outputs.typescript as Record<string, unknown> | undefined)?.outputDir as string ??
+          DEFAULT_CONFIG.outputs.typescript.outputDir,
+        metadataFile:
+          ((outputs.typescript as Record<string, unknown> | undefined)?.metadataFile as string) ??
+          DEFAULT_CONFIG.outputs.typescript.metadataFile,
+      },
+      python: {
+        metadataFile:
+          ((outputs.python as Record<string, unknown> | undefined)?.metadataFile as string) ??
+          DEFAULT_CONFIG.outputs.python.metadataFile,
+      },
+      dotnet: {
+        outputDir:
+          (outputs.dotnet as Record<string, unknown> | undefined)?.outputDir as string ??
+          DEFAULT_CONFIG.outputs.dotnet.outputDir,
+      },
+      golang: {
+        outputDir:
+          (outputs.golang as Record<string, unknown> | undefined)?.outputDir as string ??
+          DEFAULT_CONFIG.outputs.golang.outputDir,
+      },
+      rust: {
+        outputDir:
+          (outputs.rust as Record<string, unknown> | undefined)?.outputDir as string ??
+          DEFAULT_CONFIG.outputs.rust.outputDir,
+      },
+    },
+    pull: {
+      exclude: (pull.exclude as string[] | undefined) ?? DEFAULT_CONFIG.pull.exclude,
+      preserveRelations:
+        (pull.preserveRelations as boolean | undefined) ?? DEFAULT_CONFIG.pull.preserveRelations,
+    },
+    generation: {
+      generateMetadata:
+        (generation.generateMetadata as boolean | undefined) ?? DEFAULT_CONFIG.generation.generateMetadata,
+    },
+  };
+}
+
+/**
+ * The connection string to use, or an error explaining where to put one.
+ *
+ * DATABASE_URL wins over the config file: it is the documented override and the
+ * one CI sets. A project may therefore commit a development connection and
+ * still have a different one in a pipeline without editing the file.
+ */
+export function resolveConnectionString(
+  config: An5OrmConfig,
+  env: EnvLike = process.env,
+  command = 'this command',
+): string {
+  const fromEnv = env.DATABASE_URL;
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv;
+
+  const fromConfig = config.connectionString;
+  if (typeof fromConfig === 'string' && fromConfig.trim() !== '') return fromConfig;
+
+  throw new ConfigError([
+    {
+      path: 'connectionString',
+      message:
+        `required for ${command}; not set in an5Orm.config.js and DATABASE_URL is empty. ` +
+        'Set DATABASE_URL, or add a connectionString to the config file.',
+    },
+  ]);
+}
+
+/**
+ * The provider a connection string points at.
+ *
+ * Reads the scheme exactly as `An5Adapter` does
+ * (`an5Adapters/typescript/src/an5Adapter.ts`) so the generator and the adapter
+ * always talk about the same database: the same connection string must give the
+ * same provider, otherwise validation checks the types of one database while the
+ * SQL runs on another.
+ *
+ * Falls back to SQL Server when the scheme is unknown — it is the default
+ * provider, and ADO-style strings (`Server=...;Database=...`) have no scheme to
+ * read. `sqlite://`, a bare path ending in `.sqlite`, `.sqlite3` or `.db` — the same
+ * list `An5Adapter` uses.
+ */
+export function detectProvider(connectionString: string | undefined | null): Provider {
+  // Lower-cased: a URI scheme is case-insensitive, so `MySQL://` is the same
+  // connection as `mysql://`. `an5Adapters/typescript/src/an5Adapter.ts` compares
+  // the same way, and the two have to agree or this picks a provider whose DDL the
+  // adapter never runs.
+  const cs = (connectionString ?? '').trim().toLowerCase();
+  if (cs === '') return DEFAULT_PROVIDER;
+  if (cs.startsWith('googlesheets://')) return 'googlesheets';
+  if (cs.startsWith('postgres://') || cs.startsWith('postgresql://')) return 'postgres';
+  if (cs.startsWith('mysql://') || cs.startsWith('mariadb://')) return 'mysql';
+  if (SQLITE_FILE_SUFFIXES.some((suffix) => cs.endsWith(suffix))) return 'sqlite';
+  return DEFAULT_PROVIDER;
+}
+
+/** File extensions that mean SQLite when there is no scheme to read. */
+const SQLITE_FILE_SUFFIXES = ['.sqlite', '.sqlite3', '.db'];
+
+/**
+ * The provider for this run: `DATABASE_URL` first, then the connection string in
+ * the config file, then the default.
+ *
+ * Does not throw when there is no connection string — `generate` has to work
+ * with an empty config, and the default provider still validates the schema as
+ * before.
+ */
+export function providerFromConfig(
+  config: An5OrmConfig,
+  env: EnvLike = process.env,
+): Provider {
+  const fromEnv = typeof env.DATABASE_URL === 'string' && env.DATABASE_URL.trim() !== '' ? env.DATABASE_URL : undefined;
+  return detectProvider(fromEnv ?? config.connectionString);
+}
+
+/**
+ * The provider configured for a project directory.
+ *
+ * For the tools outside this package that read `.an5` files — the an5Agent
+ * schema tools, the VS Code extension — so they validate against the same
+ * database the generator does instead of silently assuming SQL Server.
+ *
+ * Never throws: no config, an unreadable one, or an invalid one all mean the
+ * default provider, which is what the parser does on its own anyway.
+ */
+export function providerForProject(
+  cwd: string = process.cwd(),
+  env: EnvLike = process.env,
+): Provider {
+  try {
+    return providerFromConfig(loadConfig(cwd).config, env);
+  } catch {
+    return DEFAULT_PROVIDER;
+  }
+}
+
+/**
+ * Renders issues for the terminal, one per line, paths aligned.
+ *
+ * Takes the shape rather than `ConfigIssue` so field type errors
+ * (`FieldTypeIssue`, from `./field-types`) print through the same code — both
+ * are "a path in the file and what is wrong with it".
+ */
+export function formatIssues(issues: ReadonlyArray<{ path: string; message: string }>): string {
+  const width = Math.max(...issues.map((issue) => issue.path.length));
+  return issues
+    .map((issue) => `  ${issue.path.padEnd(width)}  ${issue.message}`)
+    .join('\n');
+}
+
+export interface LoadedConfig {
+  /** The validated config, with defaults applied. */
+  config: An5OrmConfig;
+  /** Directory the config file lives in; every relative path resolves against it. */
+  rootDir: string;
+  /** Absolute output paths. */
+  outputs: ResolvedOutputs;
+  /** Absolute path of the config file, or null when none was found. */
+  configPath: string | null;
+}
+
+/**
+ * Finds, loads and validates an5Orm.config.js.
+ *
+ * Searched in order: the working directory, the same directory as `.cjs`, and
+ * the parent directory for each. When no file is found the defaults are used,
+ * so a project can generate without a config.
+ */
+export function loadConfig(cwd: string = process.cwd()): LoadedConfig {
+  // Resolved before the search because `require` treats a bare specifier as a
+  // package name: with a relative `cwd` the file is found (`existsSync` is
+  // relative to the process directory) but `require('./an5Orm.config.js')` is
+  // really `require('an5Orm.config.js')`, which throws MODULE_NOT_FOUND and
+  // loses the config without saying so.
+  const startDir = path.resolve(cwd);
+  const candidates = [
+    path.join(startDir, 'an5Orm.config.js'),
+    path.join(startDir, 'an5Orm.config.cjs'),
+    path.join(startDir, '..', 'an5Orm.config.js'),
+    path.join(startDir, '..', 'an5Orm.config.cjs'),
+  ];
+
+  const configPath = candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+
+  if (configPath === null) {
+    // A schema directory one level up is the common monorepo layout; without a
+    // config the paths would otherwise point at a directory that does not exist.
+    const rootDir = fs.existsSync(path.join(startDir, '..', 'an5Schema'))
+      ? path.resolve(startDir, '..')
+      : startDir;
+    return {
+      config: DEFAULT_CONFIG,
+      rootDir,
+      outputs: resolveOutputs(DEFAULT_CONFIG, rootDir),
+      configPath: null,
+    };
+  }
+
+  const rootDir = path.dirname(configPath);
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const raw = require(configPath);
+  const config = validateConfig(raw);
+  return { config, rootDir, outputs: resolveOutputs(config, rootDir), configPath };
+}