@ogygie/generate 0.0.0-stage → 0.20.0

package/dist/cli/schemas-command.d.ts

@@ -0,0 +1,31 @@
+import { type ModelClient } from "@ogygie/core/model";
+import type { CommandOutput } from "./output.js";
+import { type GenerateProject } from "./project.js";
+/** `--model <model>`: the spec model of D24, overridable. */
+export declare function parseSchemasFlags(argv: readonly string[]): {
+    model: string;
+};
+/** An external gate of the product: a script of its package.json, run without any secret; red lines come back as problems. */
+export interface SchemasGateRunner {
+    (input: {
+        projectRoot: string;
+        script: string;
+    }): {
+        green: boolean;
+        lines: string[];
+    };
+}
+/** D52 names them: the product's typecheck and the purity of its contracts. */
+export declare const SCHEMAS_GATE_SCRIPTS: readonly ["typecheck", "ogygie:verify-contracts"];
+export declare const pnpmGateRunner: SchemasGateRunner;
+export interface SchemasCommandDeps {
+    modelApiKey?: string | undefined;
+    fetchImpl?: typeof fetch;
+    /** A client in place of the Messages client — tests script the model here. */
+    client?: ModelClient;
+    gateRunner?: SchemasGateRunner;
+    summaryPath?: string | undefined;
+}
+/** The feature folder of the api app, as its sibling features are laid out (`src/features` when none says otherwise). */
+export declare function featureFolderFor(project: GenerateProject, featureId: string): string;
+export declare function runSchemasCommand(project: GenerateProject, featureId: string | undefined, argv: readonly string[], out: CommandOutput, deps?: SchemasCommandDeps): Promise<number>;

package/dist/cli/verify-command.d.ts

@@ -0,0 +1,3 @@
+import type { CommandOutput } from "./output.js";
+import { type GenerateProject } from "./project.js";
+export declare function runVerifyCommand(project: GenerateProject, out: CommandOutput): Promise<number>;

package/dist/consumed-feature.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @intent What a screen may consume of a feature of the map (D41, precision
+ * of lot 4 M3): the operations it can name. A feature whose spec carries a
+ * `# Génération` block offers the HTTP operations of that block. A feature
+ * WITHOUT a block — hand-written, delivered — offers its READS only: every GET
+ * route the map declares for it becomes a read operation named after its
+ * input schema (`GetReferentialInputSchema` → `getReferential`), its contracts
+ * read in the `schemas.ts` of its folder; its writes are not consumable — a
+ * screen that needs one asks the feature for a block. The map does not say
+ * which guard such a route carries, so a derived read names an undeclared
+ * guard and the generator emits no refusal of its own for it.
+ */
+import { type GenerationBlock, type HttpOperation, type ReadOperation } from "./generation-block.schema.js";
+/** A route of a consumed feature as the map declares it — where `invalidates` lives. */
+export interface ConsumedRoute {
+    method: string;
+    path: string;
+    schemaInput: string;
+    schemaOutput: string;
+    invalidates?: string[] | undefined;
+}
+/** The guard a derived read names: the map does not tell which guard the route carries. */
+export declare const DERIVED_READ_GUARD = "undeclared";
+/** `GetReferentialInputSchema` → `getReferential`, `ListNotesInputSchema` → `listNotes`, `RateHistoryQuerySchema` → `rateHistoryQuery`. */
+export declare function readIdOfInputSchema(schemaInput: string): string;
+/** The reads a feature without a block offers: one per GET route of the map, in the map's order. */
+export declare function derivedReadsOf(routes: readonly ConsumedRoute[]): ReadOperation[];
+/** The operations a screen may consume of a feature: the HTTP operations of its block, or the reads derived from its routes when it has none. */
+export declare function consumableOperationsOf(feature: {
+    block: GenerationBlock | null;
+    routes: readonly ConsumedRoute[];
+}): HttpOperation[];

package/dist/emit/db.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @intent Emits the Drizzle tables (`db.schema.gen.ts`) and the SQL migration
+ * (`<n>_<table>.gen.sql`) of a feature from its plan: the resource table —
+ * one column per resource field (type from the Zod structure, override from
+ * `contracts.columns`), the tenant column with its foreign key, the declared
+ * indexes prefixed by the tenant column, the unique that makes the business
+ * key a key (D28), the append-only motif's partial unique index on the current
+ * rows and its DEFERRABLE `superseded_by` foreign key —, the slot tables and
+ * the owned reference tables (D28: composite foreign key to the tenant column
+ * and the resource key, cascade for a slot, restrict for a reference), the
+ * read-only mapping of every view hole (D32: Drizzle sees a table, the
+ * repository reads it through the tenant facade, nothing is ever written
+ * through it), and the Row-Level Security policy every tenant table carries
+ * (AGENTS.md §Multi-tenant 3). The migration is regenerated AROUND the SQL
+ * bodies of the view holes, between `-- @hole <id>` and `-- @end-hole <id>`:
+ * those lines are the human's, kept as they are; a view nobody wrote yet is an
+ * empty marker pair the bench fails on.
+ */
+import type { FeaturePlan, TablePlan } from "./plan.js";
+/** Every table of the feature, resource first, then slots, then the references with a schema — adopted ones included (D36). */
+export declare function tablesOf(plan: FeaturePlan): TablePlan[];
+/** The tables the generator CREATES and owns: every table of the feature but the adopted ones (D36). */
+export declare function ownedTables(plan: FeaturePlan): TablePlan[];
+export declare function emitDbSchema(plan: FeaturePlan): string;
+/** The SQL bodies of the view holes an existing migration carries, by hole id. */
+export declare function viewBodiesOf(existingMigration: string | null): Map<string, string>;
+export declare function emitMigration(plan: FeaturePlan, existingMigration?: string | null): string;

package/dist/emit/factories.d.ts

@@ -0,0 +1,14 @@
+import type { FeaturePlan, OperationPlan } from "./plan.js";
+/** Valid inputs of an operation: variant 0 overlays the first accept examples, variant n the n-th. */
+export declare function validInputsOf(plan: FeaturePlan, operation: OperationPlan): Record<string, unknown>[];
+/** The derived fields of the create's valid input, from the derive holes' first example outputs — what an arranged row carries. */
+export declare function derivedOf(operation: OperationPlan, variant?: number): Record<string, unknown>;
+/** The import file the transform hole accepts, and what it yields. */
+export declare function importFixturesOf(plan: FeaturePlan): {
+    validCsv: string;
+    rowCount: number;
+    unreadableCsv: string;
+    faultyLineCsv: string;
+    faultyLineNumber: number;
+} | null;
+export declare function emitFactories(plan: FeaturePlan): string;

package/dist/emit/hole-doc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @intent Emits `holes/<id>.gen.md`, the ONE context handed to whoever fills a
+ * hole (D23, D32, budget 2 000 tokens): what the hole is for and where it is
+ * called, its generated signature (or, for a view, the SQL columns it must
+ * produce and where its body lives), the fields it reads with their types,
+ * the examples its test rests on, the spec lines that cite it, its normalized
+ * shape, the library's neighbours of the same shape (D24 — bodies filled
+ * elsewhere, as templates), and the conventions a body obeys. French prose:
+ * a document for the humans and agents of the project; identifiers stay
+ * English.
+ */
+import type { HoleLibraryEntry } from "../hole-shape.js";
+import type { FeaturePlan, HolePlan } from "./plan.js";
+export declare const MARKDOWN_HEADER_PREFIX = "<!-- @generated by ogygie-generate ";
+export declare function markdownGeneratedHeader(version: string): string;
+/** The operations calling a hole, as `\`id\` (METHOD /path)` — shared with the spec's generated contracts. */
+export declare function carriersOf(hole: HolePlan, plan: FeaturePlan): string[];
+export declare function emitHoleDoc(plan: FeaturePlan, hole: HolePlan, library: readonly HoleLibraryEntry[]): string;

package/dist/emit/hole-tests.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @intent Emits `holes.gen.test.ts`: the PURE test of every hole, derived from
+ * its examples (D23, D32) — each accept example passes (a derive answers its
+ * example output, a project shapes the example output from the example
+ * context), the reject example answers the hole's code with a non-empty
+ * suggestedFix (and, for a transform, the faulty line). Red at generation,
+ * since a `todo` body throws; what lot 2 bis will run a candidate body
+ * against, in milliseconds, without the bench. A view hole has no pure test:
+ * its SQL is proven on the bench by the behavior tests, and documented in its
+ * holes/<id>.gen.md.
+ */
+import { type FieldModel } from "../zod-introspection.js";
+import type { FeaturePlan, OperationPlan } from "./plan.js";
+/** A partial example laid over a full sample, arrays merged by position — so the test parses a COMPLETE output. */
+export declare function deepOverlay(base: unknown, overlay: unknown): unknown;
+/** A COMPLETE value of the model under a partial example: every field the example omits is sampled, every array item completed by its element. */
+export declare function sampleUnder(model: FieldModel, overlay: unknown): unknown;
+/** The complete output a project hole receives in its test: the read's output sample under the example's input. */
+export declare function projectInputOf(plan: FeaturePlan, carrier: OperationPlan, partial: unknown): unknown;
+/** The instant the emitted tests freeze the clock at — the same one `tests.ts` uses, so a hole and its operation see one today (épreuve pdlc 2026-10-29). */
+export declare const HOLE_TESTS_CLOCK_INSTANT = "2026-01-01T00:00:00.000Z";
+/** A hole that declares the clock effect receives it as its second parameter: the test passes the frozen one. */
+export declare function holeDeclaresClock(hole: {
+    hole: {
+        effects?: readonly string[];
+    };
+}): boolean;
+export declare function emitHoleTests(plan: FeaturePlan): string;

package/dist/emit/manifest-entry.d.ts

@@ -0,0 +1,44 @@
+import type { FeaturePlan, OperationPlan } from "./plan.js";
+export interface ManifestRouteEntry {
+    method: string;
+    path: string;
+    description: string;
+    schemaInput: string;
+    schemaOutput: string;
+    invalidates?: string[];
+}
+export interface GeneratedManifestEntry {
+    routes: ManifestRouteEntry[];
+    dbTables: string[];
+}
+/** What the map says about the feature today — the two generated fields, as declared. */
+export interface DeclaredManifestEntry {
+    routes: unknown;
+    dbTables: unknown;
+}
+export type ManifestEntryField = "routes" | "dbTables";
+export interface ApplyManifestEntryResult {
+    manifest: Record<string, unknown>;
+    /** `created` when no entry carried the feature's name, `updated` when a generated field changed. */
+    outcome: "created" | "updated" | "unchanged";
+}
+/** The French sentence the map shows for a route — domain-free words, identifiers in backticks. */
+export declare function routeDescriptionOf(operation: OperationPlan, plan: FeaturePlan): string;
+export declare function manifestEntryOf(plan: FeaturePlan): GeneratedManifestEntry;
+/** The generated fields the declared entry gets wrong — empty when the map tells the truth. */
+export declare function manifestEntryDrift(declared: DeclaredManifestEntry | undefined, plan: FeaturePlan): Array<ManifestEntryField | "entry">;
+/** First paragraph of the spec's `# @intent` section, one line — null when the section has none. */
+export declare function intentOfSpec(markdown: string): string | null;
+/** The intent as the manifest accepts it: whole sentences within the core's bounds. */
+export declare function intentForManifest(intent: string | null, specPath: string): string;
+/**
+ * The manifest with the feature's generated fields in place. The raw JSON is
+ * taken as parsed (never through the core's schema, which strips the keys it
+ * does not know): everything but `routes` and `dbTables` of the entry is left
+ * untouched, and a feature absent from `features[]` is added after the others.
+ */
+/** The status a created entry gets: `skeleton` while the spec is still `draft` (a folder on a branch is a proposal, not a delivery — verify-specs refuses `in-progress` under a draft), `in-progress` once it is validated; `delivered` stays a human word (D25). */
+export declare function entryStatusForSpec(specStatus: string | null | undefined): "skeleton" | "in-progress";
+export declare function applyManifestEntry(rawManifest: unknown, plan: FeaturePlan, intent: string | null, entryStatus?: "skeleton" | "in-progress"): ApplyManifestEntryResult;
+/** The manifest as the repo keeps it: two-space JSON and a final newline. */
+export declare function serializeManifest(manifest: Record<string, unknown>): string;

package/dist/emit/mssql/migration.d.ts

@@ -0,0 +1,2 @@
+import type { FeaturePlan } from "../plan.js";
+export declare function emitMssqlMigration(plan: FeaturePlan, existingMigration?: string | null): string;

package/dist/emit/mssql/repository.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @intent Emits `repository.gen.ts` for the SQL Server target (D33,
+ * `mssql-raw`): the only file of the feature touching the database, through
+ * the product's `Database.query` port — parameterised T-SQL (`@name`), never a
+ * concatenation —, the row types the driver answers (dates as Date), the
+ * statements as an exported `SQL` constant (the stub answers the SAME texts),
+ * and the functions the service calls, named like the Postgres ones: the
+ * reads, the slot and reference reads, the view reads, the keyed writes of D28
+ * (load by key or the operation's 404; update the fields sent through
+ * COALESCE, OUTPUT INSERTED telling written from not found; set or clear a slot
+ * with the idempotent rule of D31; delete unless referenced, 409 with the
+ * count in cause), uniqueKey (409 on a taken key, the unique constraint as the
+ * belt) and the signature of every write. No tenant column: the target has
+ * no tenant.
+ */
+import type { FeaturePlan } from "../plan.js";
+export declare function emitMssqlRepository(plan: FeaturePlan): string;

package/dist/emit/mssql/sql-types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @intent What the SQL Server target (D33, `mssql-raw`) makes of a column
+ * plan: the T-SQL type for the Postgres type the plan carries, the PascalCase
+ * column name when the target says `naming: pascal`, and the qualified table
+ * name under the target's schema. One place, so the migration, the repository
+ * and the stub agree on every name — the stub is emitted from the SAME source
+ * as the SQL it answers.
+ */
+import type { ColumnPlan, FeaturePlan, TablePlan } from "../plan.js";
+/** `label` → `Label` (pascal) or `label` (camel) — of the LOGICAL column name, which an adopted table may declare apart from the key (D36). */
+export declare function sqlColumnName(plan: FeaturePlan, column: Pick<ColumnPlan, "columnName">): string;
+/** The column of a table by its TS key, or a loud failure — the emitters never guess a column. */
+export declare function columnNamed(table: TablePlan, key: string): ColumnPlan;
+/** `grades` → `app.grades` under a schema, `grades` without. */
+export declare function qualifiedTable(plan: FeaturePlan, sqlName: string): string;
+/** The T-SQL type of a column, from the Postgres type the plan resolved from the Zod structure. */
+export declare function tsqlTypeOf(column: ColumnPlan): string;
+/** The CHECK a column carries, translated: `in (...)` keeps its values. */
+export declare function tsqlCheckOf(plan: FeaturePlan, column: ColumnPlan): string | null;
+/** The columns a table writes — never the one the database defaults (`id` when it has a default). */
+export declare function tableColumns(table: TablePlan): ColumnPlan[];
+/** The TypeScript type of a row field as the driver returns it: dates come back as Date, numbers as number. */
+export declare function tsRowTypeOf(column: ColumnPlan): string;

package/dist/emit/mssql/statements.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @intent The T-SQL statements of a feature on the SQL Server target (D33,
+ * `mssql-raw`), as DATA: one descriptor per statement — its key in the `SQL`
+ * constant the repository exports, its text with `@named` parameters, the
+ * table it touches and what it MEANS (`kind`) — so the repository emits the
+ * text and the stub emits, from the same descriptors, the in-memory answer of
+ * each statement (D33: the stub is emitted with the SQL, nothing can drift
+ * between a query and its simulated reply). Columns are read back under their
+ * camelCase alias (`g.Label AS label`), the keyed writes answer through
+ * `OUTPUT INSERTED` / `OUTPUT DELETED` so a miss is an empty result, a limit
+ * is `OFFSET … FETCH`.
+ */
+import type { ColumnPlan, FeaturePlan, SlotPlan } from "../plan.js";
+export type StatementKind = "selectAll" | "selectByKey" | "selectByUniqueKey" | "countByColumn" | "countByKey" | "insert" | "updateByKey" | "selectSlot" | "insertSlot" | "updateSlotById" | "updateSlotByKey" | "deleteById" | "deleteSlotByKey" | "deleteByKey" | "selectView";
+export interface Statement {
+    /** Key in the exported `SQL` constant, e.g. `selectListAll`. */
+    key: string;
+    kind: StatementKind;
+    text: string;
+    /** The owned table (or view) the statement touches, by SQL name. */
+    table: string;
+    /** Row type the statement returns (its camelCase aliases). */
+    rowType: string;
+    /** Parameter names in `@name` order of appearance. */
+    parameters: string[];
+    /** Extra meaning the stub needs: ordering, limit, the columns written, the key or slot fields. */
+    order?: Array<{
+        field: string;
+        direction: "asc" | "desc";
+        enumValues: Array<string | number> | null;
+    }>;
+    limit?: number | null;
+    written?: string[];
+    keyField?: string;
+    slot?: {
+        parentKey: string;
+        key: string;
+        value: string;
+    };
+    unique?: string[];
+    countColumn?: string;
+    signed?: {
+        by: string;
+        at: string;
+    } | null;
+    /** The fields an OUTPUT clause hands back when it is not the whole row: `["id"]`, or the key fields of a table without id (D36). */
+    outputs?: string[];
+}
+/** `g.Id AS id, g.Code AS code, …` for every column of a table. */
+export declare function selectList(plan: FeaturePlan, prefix: string, columns: readonly ColumnPlan[]): string;
+export declare function mssqlStatements(plan: FeaturePlan): Statement[];
+/** The statement of a key, or a loud failure — the emitters never guess a name. */
+export declare function statementNamed(statements: readonly Statement[], key: string): Statement;
+/** The slot plan a statement belongs to. */
+export declare function slotOf(plan: FeaturePlan, statement: Statement): SlotPlan | null;

package/dist/emit/mssql/stub.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @intent Emits `repository.stub.gen.ts` for a SQL Server target tested on a
+ * stub (D33, `tests: stub`): an in-memory `Database` whose `query` answers the
+ * SAME statements the repository exports — matched on the exact text of the
+ * `SQL` constant, never on a fragment — by executing their meaning over plain
+ * arrays: a select returns the table ordered as the statement orders it, a
+ * keyed write answers OUTPUT rows (one per row touched, none when the key is
+ * unknown), an insert simulates the unique constraint (error 2627), a delete
+ * cascades the slot rows as the foreign key would, a view returns the rows the
+ * test arranged (a view's SQL is not run on a stub, D32). The stub is emitted
+ * from the statement descriptors the repository was emitted from: a repository
+ * that changes its SQL changes its stub in the same generation. `answer…Query`
+ * returns `undefined` for a text it does not know, so a product's own test kit
+ * can chain it with other stubs.
+ */
+import type { FeaturePlan } from "../plan.js";
+export declare function emitMssqlStub(plan: FeaturePlan): string;

package/dist/emit/names.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @intent Naming and header helpers every emitter shares (DECISIONS.md D21):
+ * the `@generated` header is LINE 1 of every emitted file, the `@intent` block
+ * comes next; identifiers derive mechanically from the feature id and the
+ * schema names (kebab → Pascal, camel → snake), so the same spec always yields
+ * the same names. Deterministic string building only — no clock, no random.
+ */
+export declare const GENERATOR_NAME = "ogygie-generate";
+/** `// @generated by ogygie-generate <version> — do not edit` — line 1 of a TypeScript file. */
+export declare function tsGeneratedHeader(version: string): string;
+/** The same header for SQL, where `--` opens a comment. */
+export declare function sqlGeneratedHeader(version: string): string;
+/** A `/** @intent … *\/` block from wrapped lines. */
+export declare function intentBlock(lines: readonly string[]): string;
+/** Wraps a sentence at ~78 columns on word boundaries, for comments. */
+export declare function wrap(text: string, width?: number): string[];
+/** `publication-de-taux` → `PublicationDeTaux`. */
+export declare function pascalCaseOf(kebab: string): string;
+/** `PublicationDeTaux` → `publicationDeTaux`. */
+export declare function camelCaseOf(kebab: string): string;
+/** `effectiveDate` → `effective_date`. */
+export declare function snakeCaseOf(camel: string): string;
+/** `rate_publications` → `ratePublications`. */
+export declare function camelOfSnake(snake: string): string;
+/** `CreateRateInputSchema` → `CreateRateInput` (AGENTS.md template 2: the inferred type sits next to the schema). */
+export declare function typeNameOfSchema(schemaName: string): string;
+/** `import` → `runImport` — service functions never collide with a reserved word. */
+export declare function serviceFunctionNameOf(operationId: string): string;
+/** Relative import path from a folder to a module, both repo-relative, `.ts` → `.js`, always `./`-or-`../`-prefixed. */
+export declare function relativeImportPath(fromFolder: string, toModule: string): string;
+/** A TypeScript string literal, JSON-quoted. */
+export declare function quote(value: string): string;
+/** Lines joined with newlines and a trailing newline — every emitted file ends with one. `null` omits a part; `""` is a blank line. */
+export declare function fileOf(...parts: ReadonlyArray<string | null>): string;