@an5/orm 1.0.9 → 1.1.0

package/README.md

@@ -4,14 +4,14 @@ The Schema, Code Generator, and Migration Toolkit for the AN5 ecosystem.
 
 ## Overview
 
-`@an5/orm` provides core schema parsing, multi-language code generation (TypeScript, Python, .NET C#, Golang), database introspection (`pull`), schema deployment (`push`), and automated database migrations.
+`@an5/orm` provides core schema parsing, multi-language code generation (TypeScript, Python, .NET C#, Golang, Rust), database introspection (`pull`), schema deployment (`push`), and automated database migrations.
 
-Runtime database connections, query building, transactions, and multi-database drivers (MSSQL, PostgreSQL, MySQL, SQLite, Google Sheets) are powered by **[@an5/adapters](https://github.com/an5ORM/an5/tree/main/an5Adapters)**.
+Runtime database connections, query building, transactions, and multi-database drivers (MSSQL, PostgreSQL, MySQL, SQLite, Google Sheets) are powered by **[@an5/adapters](https://github.com/an5ORM/an5Adapters)**.
 
 ## Features
 
 - **Schema Definition:** Define models and relationships using concise `.an5` syntax with native database types.
-- **Multi-Language Generator:** Generate typed clients and entity models for TypeScript, Python, .NET (C#), and Golang.
+- **Multi-Language Generator:** Generate typed clients and entity models for TypeScript, Python, .NET (C#), Golang, and Rust.
 - **Database Introspection (`db:pull`):** Inspect an existing database schema and generate matching `.an5` models.
 - **Direct Schema Push (`db:push`):** Synchronize `.an5` schema definitions directly to the database.
 - **Automated Migrations (`db:migrate`):** Diff schema against database, generate up/down migration SQL scripts, apply, rollback, and check migration status.
@@ -141,6 +141,13 @@ await db.$disconnect();
 
 ## Schema Definition (`.an5`)
 
+Field types are validated against the database you are generating for. The provider
+comes from the connection string (`DATABASE_URL` first, then `connectionString` in
+`an5Orm.config.js`): `sqlserver://` (and the fallback) is SQL Server, `postgres://`
+PostgreSQL, `mysql://` MySQL, `sqlite://` SQLite, `googlesheets://` Google Sheets.
+A type the provider does not have stops generation with every offending field
+listed at once — see `PROVIDER_FIELD_TYPES` in `generator/src/field-types.ts`.
+
 ```an5
 model User {
   id        NVARCHAR(1000) @id @default(uuid())

package/dist/config.d.ts

@@ -1,2 +1,10 @@
-export declare const config: any;
+/**
+ * Workspace Configuration for an5Orm
+ *
+ * Re-exported from the generator so the CLI commands and the generator agree on
+ * one config shape. These files used to load an5Orm.config.js themselves with
+ * `any`, which meant the four of them could disagree about what was valid.
+ */
+export { loadConfig, validateConfig, resolveOutputs, resolveConnectionString, formatIssues, ConfigError, DEFAULT_CONFIG, } from './generator/src/config';
+export type { An5OrmConfig, TypeScriptOutput, ResolvedOutputs, LoadedConfig, ConfigIssue, } from './generator/src/config';
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -1,24 +1,19 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = void 0;
+exports.DEFAULT_CONFIG = exports.ConfigError = exports.formatIssues = exports.resolveConnectionString = exports.resolveOutputs = exports.validateConfig = exports.loadConfig = void 0;
 /**
  * Workspace Configuration for an5Orm
- * Reads from an5Orm.config.js and environment variables.
+ *
+ * Re-exported from the generator so the CLI commands and the generator agree on
+ * one config shape. These files used to load an5Orm.config.js themselves with
+ * `any`, which meant the four of them could disagree about what was valid.
  */
-const path_1 = __importDefault(require("path"));
-let workspaceConfig = {};
-try {
-    const configPath = path_1.default.join(__dirname, '..', 'an5Orm.config.js');
-    workspaceConfig = require(configPath);
-}
-catch { /* ignore */ }
-exports.config = {
-    ...workspaceConfig,
-    llm: workspaceConfig.llm || {
-        providers: [],
-    },
-};
+var config_1 = require("./generator/src/config");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
+Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return config_1.validateConfig; } });
+Object.defineProperty(exports, "resolveOutputs", { enumerable: true, get: function () { return config_1.resolveOutputs; } });
+Object.defineProperty(exports, "resolveConnectionString", { enumerable: true, get: function () { return config_1.resolveConnectionString; } });
+Object.defineProperty(exports, "formatIssues", { enumerable: true, get: function () { return config_1.formatIssues; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_1.ConfigError; } });
+Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_CONFIG; } });
 //# sourceMappingURL=config.js.map

package/dist/generator/src/api.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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/dist/generator/src/api.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unknownFieldTypeMessage = exports.resolveFieldType = exports.fieldTypesFor = exports.defaultSqlTypeForTs = exports.PROVIDER_LABELS = exports.PROVIDER_FIELD_TYPES = exports.PROVIDERS = exports.FieldTypeError = exports.DEFAULT_PROVIDER = exports.fieldKind = exports.sqlLiteral = exports.defaultClause = exports.dialectFor = exports.providerForProject = exports.providerFromConfig = exports.detectProvider = exports.RustGenerator = exports.GolangGenerator = exports.DotnetGenerator = exports.PythonGenerator = exports.MetadataGenerator = exports.CodeGenerator = exports.sqlTypeToTs = exports.SchemaParser = void 0;
+/**
+ * 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);
+ * ```
+ */
+var parser_1 = require("./parser");
+Object.defineProperty(exports, "SchemaParser", { enumerable: true, get: function () { return parser_1.SchemaParser; } });
+Object.defineProperty(exports, "sqlTypeToTs", { enumerable: true, get: function () { return parser_1.sqlTypeToTs; } });
+var code_generator_1 = require("./code-generator");
+Object.defineProperty(exports, "CodeGenerator", { enumerable: true, get: function () { return code_generator_1.CodeGenerator; } });
+var metadata_generator_1 = require("./metadata-generator");
+Object.defineProperty(exports, "MetadataGenerator", { enumerable: true, get: function () { return metadata_generator_1.MetadataGenerator; } });
+var python_generator_1 = require("./python-generator");
+Object.defineProperty(exports, "PythonGenerator", { enumerable: true, get: function () { return python_generator_1.PythonGenerator; } });
+var dotnet_generator_1 = require("./dotnet-generator");
+Object.defineProperty(exports, "DotnetGenerator", { enumerable: true, get: function () { return dotnet_generator_1.DotnetGenerator; } });
+var golang_generator_1 = require("./golang-generator");
+Object.defineProperty(exports, "GolangGenerator", { enumerable: true, get: function () { return golang_generator_1.GolangGenerator; } });
+var rust_generator_1 = require("./rust-generator");
+Object.defineProperty(exports, "RustGenerator", { enumerable: true, get: function () { return rust_generator_1.RustGenerator; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "detectProvider", { enumerable: true, get: function () { return config_1.detectProvider; } });
+Object.defineProperty(exports, "providerFromConfig", { enumerable: true, get: function () { return config_1.providerFromConfig; } });
+Object.defineProperty(exports, "providerForProject", { enumerable: true, get: function () { return config_1.providerForProject; } });
+var dialect_1 = require("./dialect");
+Object.defineProperty(exports, "dialectFor", { enumerable: true, get: function () { return dialect_1.dialectFor; } });
+Object.defineProperty(exports, "defaultClause", { enumerable: true, get: function () { return dialect_1.defaultClause; } });
+Object.defineProperty(exports, "sqlLiteral", { enumerable: true, get: function () { return dialect_1.sqlLiteral; } });
+var type_kinds_1 = require("./type-kinds");
+Object.defineProperty(exports, "fieldKind", { enumerable: true, get: function () { return type_kinds_1.fieldKind; } });
+var field_types_1 = require("./field-types");
+Object.defineProperty(exports, "DEFAULT_PROVIDER", { enumerable: true, get: function () { return field_types_1.DEFAULT_PROVIDER; } });
+Object.defineProperty(exports, "FieldTypeError", { enumerable: true, get: function () { return field_types_1.FieldTypeError; } });
+Object.defineProperty(exports, "PROVIDERS", { enumerable: true, get: function () { return field_types_1.PROVIDERS; } });
+Object.defineProperty(exports, "PROVIDER_FIELD_TYPES", { enumerable: true, get: function () { return field_types_1.PROVIDER_FIELD_TYPES; } });
+Object.defineProperty(exports, "PROVIDER_LABELS", { enumerable: true, get: function () { return field_types_1.PROVIDER_LABELS; } });
+Object.defineProperty(exports, "defaultSqlTypeForTs", { enumerable: true, get: function () { return field_types_1.defaultSqlTypeForTs; } });
+Object.defineProperty(exports, "fieldTypesFor", { enumerable: true, get: function () { return field_types_1.fieldTypesFor; } });
+Object.defineProperty(exports, "resolveFieldType", { enumerable: true, get: function () { return field_types_1.resolveFieldType; } });
+Object.defineProperty(exports, "unknownFieldTypeMessage", { enumerable: true, get: function () { return field_types_1.unknownFieldTypeMessage; } });

package/dist/generator/src/config.d.ts

@@ -0,0 +1,162 @@
+import { Provider } from './field-types';
+/** 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 declare const DEFAULT_CONFIG: An5OrmConfig;
+/** 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 declare function resolveOutputs(config: An5OrmConfig, rootDir: string): ResolvedOutputs;
+/**
+ * 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 declare class ConfigError extends Error {
+    readonly issues: ConfigIssue[];
+    constructor(issues: ConfigIssue[]);
+}
+/**
+ * Checks a loaded config object and returns it with defaults applied.
+ * Throws ConfigError listing every problem found, not just the first.
+ */
+export declare function validateConfig(raw: unknown): An5OrmConfig;
+/**
+ * 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 declare function resolveConnectionString(config: An5OrmConfig, env?: EnvLike, command?: string): string;
+/**
+ * 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 declare function detectProvider(connectionString: string | undefined | null): Provider;
+/**
+ * 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 declare function providerFromConfig(config: An5OrmConfig, env?: EnvLike): Provider;
+/**
+ * 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 declare function providerForProject(cwd?: string, env?: EnvLike): 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 declare function formatIssues(issues: ReadonlyArray<{
+    path: string;
+    message: string;
+}>): string;
+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 declare function loadConfig(cwd?: string): LoadedConfig;