@ogygie/generate 0.0.0-stage → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x10sion LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @ogygie/generate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Le générateur d'Ogygie : il lit une spec portant une section `# Génération`
+(D18) et le `schemas.ts` de la feature (D19), produit tout ce qui se déduit
+— routes, pipeline, base, fabriques, tests — de façon déterministe et sans
+modèle (D21, D22), et réserve ce qui se pense sous forme de **trous typés**
+dans `logic.ts`, chacun livré avec sa signature, ses exemples, son test rouge
+et son contexte (D23). Les trous se remplissent par bibliothèque, puis
+tirage-vérification, puis escalade (D24).
+
+Sixième paquet du lockstep (D55), publié construit : `ogygie generate
+<check|generate|verify|preview|fill|schemas>` le relaie depuis le projet
+(installé en `devDependencies` à la version du framework), le TypeScript du
+produit est chargé par l'API de `tsx` quand `node` nu ne le sait pas. Les
+fixtures dorées et le banc de test restent dans le dépôt, hors du paquet.
+
+## Lot 1 — ce que le paquet sait faire aujourd'hui
+
+| Module | Rôle |
+|---|---|
+| `spec-sections.ts` | isole le bloc YAML de `# Génération` et recolle les lignes de `# Comportements` |
+| `generation-block.schema.ts` | schéma Zod des quatre clés (`contracts`, `operations`, `motifs`, `holes`) et leurs références croisées — `OGYGIE_GENERATION_BLOCK_INVALID` |
+| `motif-catalog.ts` | le catalogue fermé des motifs (`appendOnlySupersedes`, `allOrNothingImport`) : méthodes, statuts, vocabulaire |
+| `behavior-grammar.ts` | le parseur de la grammaire D20 (`ÉTANT DONNÉ … ALORS … [et …] [[hole:…]]`) |
+| `vocabulary.ts` | le vocabulaire d'une opération : cas, valeurs nommées, phrases, codes et statuts |
+| `behavior-binding.ts` | lie une ligne à son opération : dérivable, portée par un trou, ou `OGYGIE_BEHAVIOR_UNBOUND` |
+| `manifest-generation.schema.ts` | le bloc `generation.guards` du manifeste (ce qui est produit, pas feature) |
+| `check-spec.ts` | la commande `check` : section → bloc → lignes → liaison, avec son décompte |
+| `verify-generation.ts` | la commande `verify` (D27) telle que le lot 1 peut la tenir : `check` de chaque spec du repo, et toute dérive — ce générateur ne reproduit rien encore, donc tout fichier généré en est une ; périmètre déclaré (D12) ; appelée par `pnpm verify` |
+| `vocabulary-leak.test.ts` | rejoue sur ce paquet le gate de vocabulaire du framework, jusqu'au gate de promotion Phase 3 (D25) |
+
+La fixture jumelle `fixtures/publication-de-taux.spec.md` rejoue, dans un
+domaine neutre, la forme exacte de la feature réelle sur laquelle la thèse se
+prouve ; la spec du paquet est elle-même parsée par le paquet dans ses tests.
+
+## Hors périmètre du lot 1
+
+Génération des fichiers, introspection de `schemas.ts`, bibliothèque et
+tirage-vérification, relais `ogygie generate` dans le CLI : lot 2, après
+validation humaine de la spec, des grammaires et de D25 — faite le 2026-10-17.

package/dist/behavior-binding.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @intent Binds a parsed behavior line to the block it belongs to
+ * (DECISIONS.md D20) and answers one of three things: the line is DERIVABLE
+ * (every word has a factory behind it — its test needs no model), the line is
+ * CARRIED BY A HOLE (it names `[hole:<id>]`, a hole the operation lists — its
+ * test is generated with a `todo` body), or the line is UNBOUND —
+ * `OGYGIE_BEHAVIOR_UNBOUND`, with the offending part in `details` (`operation`,
+ * `status`, `code`, `hole`, `case`, `expectation`, `line`) and, for a case or
+ * an expectation, the vocabulary of the operation as the suggested fix.
+ *
+* Order of the checks is the order of what is cheapest to fix: the grammar,
+ * the operation, the status against the kind, the code and its status, the
+ * hole marker, then the vocabulary — and the vocabulary is only demanded of
+ * HTTP operations: a `command` writes its tests by hand, one per line (D20).
+ * The hole marker excuses cases and expectations outside the vocabulary and
+ * NOTHING else: a carried line still parses `ÉTANT DONNÉ <op> … ALORS
+ * <statut> [<code>]`, names a declared operation and a carried code.
+ */
+import { type OgygieError } from "@ogygie/core/errors";
+import type { BehaviorParseResult } from "./behavior-grammar.js";
+import { type GenerationBlock, type Operation } from "./generation-block.schema.js";
+import { type GuardRegistry } from "./manifest-generation.schema.js";
+export declare const BEHAVIOR_UNBOUND = "OGYGIE_BEHAVIOR_UNBOUND";
+export interface BindingContext {
+    block: GenerationBlock;
+    guards?: GuardRegistry;
+    /** D37: the code the target answers to a violated contract; CONTRACT_VALIDATION_FAILED in a line always means it. */
+    contractViolationCode?: string;
+    /** Spec path, relative to the repo root — the `file` of a refusal. */
+    specPath: string;
+    /** 1-based line of the behavior in the spec file. */
+    line: number;
+}
+export type BindingOutcome = {
+    ok: true;
+    status: "derivable";
+    operation: Operation;
+} | {
+    ok: true;
+    status: "hole";
+    hole: string;
+    operation: Operation;
+} | {
+    ok: false;
+    error: OgygieError;
+};
+export declare function bindBehavior(parse: BehaviorParseResult, context: BindingContext): BindingOutcome;

package/dist/behavior-grammar.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @intent The parser of the closed behavior grammar (DECISIONS.md D20):
+ *
+ *   ÉTANT DONNÉ <op> (avec|sans) <cas>[, [avec|sans] <cas>]* ALORS <statut> [<CODE>] [et <attendu>[, <attendu>]*] [[hole:<id>]]
+ *
+ * Pure text in, structure out — no vocabulary here (that is the binder's
+ * job, behavior-binding.ts): this module only says whether a line HAS the
+ * shape, and when it has not, WHY, in one sentence an agent can act on. The
+ * keywords are French because a spec is for the humans of the project
+ * (AGENTS.md principle 8); the identifiers a line cites — operation ids,
+ * error codes, output paths — are the code's, hence English.
+ */
+export interface BehaviorCase {
+    polarity: "with" | "without";
+    phrase: string;
+}
+export interface BehaviorExpectation {
+    raw: string;
+    /** `details.errors[].line` — null when the expectation is a bare phrase. */
+    path: string | null;
+    /** Right side of `=`, raw — a literal or a named value of the vocabulary. */
+    value: string | null;
+}
+export type BehaviorOutcome = {
+    kind: "http";
+    status: number;
+} | {
+    kind: "command";
+    result: "success" | "refusal";
+};
+export interface ParsedBehavior {
+    raw: string;
+    operation: string;
+    cases: BehaviorCase[];
+    outcome: BehaviorOutcome;
+    code: string | null;
+    expectations: BehaviorExpectation[];
+    hole: string | null;
+}
+export type BehaviorParseResult = {
+    ok: true;
+    behavior: ParsedBehavior;
+} | {
+    ok: false;
+    raw: string;
+    hole: string | null;
+    reason: string;
+};
+export declare const OPENING_KEYWORD = "\u00C9TANT DONN\u00C9";
+/** A JSON-ish literal a `<path> = …` may compare to without any vocabulary. */
+export declare function isLiteralValue(value: string): boolean;
+export declare function parseExpectation(raw: string): BehaviorExpectation;
+export declare function parseBehavior(input: string): BehaviorParseResult;

package/dist/check-spec.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @intent The `check` command of the generator (spec ogygie-generate B1, B2):
+ * section → block → behavior lines → binding, without writing anything. A
+ * spec without a `# Génération` section is not generated and passes as such
+ * (`generated: false`); a spec with one must carry a valid block and bind
+ * every behavior line, or the report names each refusal as an OgygieError.
+ * The tally (derivable / hole / unbound) is the measure the thesis rests on
+ * (spec ogygie-generate, « Épreuve de vérité »).
+ */
+import type { OgygieError } from "@ogygie/core/errors";
+import { type BindingOutcome } from "./behavior-binding.js";
+import { type GenerationBlock } from "./generation-block.schema.js";
+import { type ScreenBlock } from "./screen-block.schema.js";
+import { type ConsumedFeatureCheckInput } from "./screen-checks.js";
+import { type ScreenBindingOutcome } from "./screen-vocabulary.js";
+import { type GuardRegistry, type ManifestGeneration } from "./manifest-generation.schema.js";
+import type { SchemaModels } from "./zod-introspection.js";
+export interface CheckSpecInput {
+    markdown: string;
+    /** Spec path relative to the repo root — the `file` of every refusal. */
+    specPath: string;
+    guards?: GuardRegistry;
+    /** The manifest's generation block when known: its guards, and what a motif requires of it (signedWrite → signature). */
+    generation?: ManifestGeneration | null;
+    /** The introspected schemas module (D19); absent, the module-level checks do not run. */
+    schemas?: SchemaModels | null;
+    /** For a SCREEN spec (D41): the consumed features as the project resolved them; absent, the consumption checks do not run. */
+    consumed?: ReadonlyMap<string, ConsumedFeatureCheckInput> | null;
+}
+export interface CheckedBehavior {
+    raw: string;
+    line: number;
+    outcome: BindingOutcome | ScreenBindingOutcome;
+}
+export interface CheckTally {
+    derivable: number;
+    hole: number;
+    unbound: number;
+}
+export interface CheckSpecReport {
+    ok: boolean;
+    /** True when the spec carries a `# Génération` section. */
+    generated: boolean;
+    /** D41: a feature block (`contracts`) or a screen block (`consumes`); null when the section is absent or unreadable. */
+    kind: "feature" | "screen" | null;
+    block: GenerationBlock | null;
+    /** The screen block, when the spec is a screen's. */
+    screen: ScreenBlock | null;
+    behaviors: CheckedBehavior[];
+    problems: OgygieError[];
+    tally: CheckTally;
+}
+export declare function checkSpec(input: CheckSpecInput): CheckSpecReport;