@ogygie/core 0.1.0

package/src/manifest.schema.ts

@@ -0,0 +1,187 @@
+/**
+ * @intent Zod schema of `ogygie.manifest.json`, the machine-readable map of the repo.
+ * It is the FIRST file an agent reads after AGENTS.md. Verified in CI: any
+ * divergence between the manifest and the actual code breaks the build.
+ * Keys and enum values are English (DECISIONS.md D11 — machine-readable = English).
+ */
+import { z } from "zod";
+
+export const FeatureNameSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "kebab-case required");
+
+export const HttpRouteSchema = z.object({
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: z.string().startsWith("/api/"),
+  description: z.string().min(10),
+  schemaInput: z
+    .string()
+    .describe("Exported name of the input Zod schema, e.g. CreateOrderInputSchema"),
+  schemaOutput: z.string().describe("Exported name of the output Zod schema"),
+  invalidates: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Cache roots this mutation stales BEYOND its own path root (cross-feature dependency, read by the manifest-derived client — never guessed in a screen). Each value must be an existing feature name or route root",
+    ),
+});
+
+/**
+ * One table owned by a feature. A bare string is the DEFAULT and by far the
+ * common case: a TENANT-SCOPED table, carrying the tenant column, reachable
+ * only through `tenantDb`, protected by its RLS policy.
+ *
+ * The object form declares a SHARED referential table (AGENTS.md §Multi-tenant
+ * rule 4): universal knowledge no tenant owns (an external open-data edition
+ * loaded by an extraction script), hence NO tenant column, NO tenant RLS policy, and
+ * read-only for the API. It is a deliberate hole in the strongest rail of the
+ * product, so it is declared HERE, machine-readably, and the gates check it
+ * (see shared-tables.ts) — never left to a reader's judgement.
+ * `shared` is a literal `true`: a table is either shared (and says so) or
+ * tenant-scoped (and stays a plain string) — no `shared: false` third state.
+ */
+export const DbTableDeclarationSchema = z.union([
+  z.string(),
+  z.object({ name: z.string(), shared: z.literal(true) }),
+]);
+export type DbTableDeclaration = z.infer<typeof DbTableDeclarationSchema>;
+
+export const FeatureManifestSchema = z.object({
+  name: FeatureNameSchema,
+  intent: z.string().min(20).max(300).describe("The feature's 'why' in 1-3 sentences"),
+  app: z
+    .string()
+    .optional()
+    .describe("Name of the owning app (apps[].name); defaults to the api app"),
+  folder: z
+    .string()
+    .describe("Path relative to the app root, e.g. src/features/orders"),
+  spec: z
+    .string()
+    .nullable()
+    .describe("Path to the spec, e.g. specs/orders.spec.md, null for technical features"),
+  routes: z.array(HttpRouteSchema),
+  dbTables: z
+    .array(DbTableDeclarationSchema)
+    .describe(
+      "Drizzle tables owned by this feature (one table = one owner). String = tenant-scoped; { name, shared: true } = shared referential",
+    ),
+  dependsOn: z
+    .array(FeatureNameSchema)
+    .describe("Features imported through their index.ts — nothing else"),
+  status: z.enum(["skeleton", "in-progress", "delivered"]),
+});
+
+/**
+ * Version of the Ogygie framework a CONSUMER project is pinned to
+ * (spec ogygie-standalone-repo). Injected by `ogygie init`, bumped only by
+ * `ogygie upgrade`, checked in CI by `ogygie check` against the installed
+ * @ogygie/cli and @ogygie/core versions (lockstep, D2). Absent from the
+ * framework repo's own manifest — the framework IS the version.
+ */
+export const OgygieVersionSchema = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+$/, "expected a plain x.y.z version");
+
+/**
+ * Self-description of the FRAMEWORK repo (spec ogygie-standalone-repo B1):
+ * the published packages, the template folders `init` copies, and the module
+ * declaring the governed-files list — so an agent reading the manifest knows
+ * them without exploring the repo. Consumer manifests never carry this block.
+ */
+export const FrameworkManifestSchema = z.object({
+  packages: z.array(
+    z.object({
+      name: z.string().describe("Published npm name, e.g. @ogygie/core"),
+      path: z.string().describe("Folder relative to the repo root"),
+      intent: z.string().min(20),
+    }),
+  ),
+  templates: z.object({
+    project: z.string().describe("Folder copied by `ogygie init`"),
+    feature: z.string().describe("Reserved for `ogygie generate feature` (not wired yet)"),
+  }),
+  governedFiles: z
+    .string()
+    .describe("Module declaring the exhaustive list of files `upgrade` may overwrite (D3)"),
+});
+
+export const OgygieManifestSchema = z.object({
+  version: z.literal(1),
+  product: z.object({
+    name: z.string(),
+    description: z.string().min(20),
+  }),
+  ogygieVersion: OgygieVersionSchema.optional(),
+  framework: FrameworkManifestSchema.optional(),
+  apps: z.array(
+    z.object({
+      name: z.string(),
+      path: z.string(),
+      type: z.enum(["api", "front", "gateway"]),
+      entryPoint: z.string(),
+    }),
+  ),
+  features: z.array(FeatureManifestSchema),
+  conventions: z.object({
+    agentsMd: z.literal("AGENTS.md"),
+    failuresMd: z.literal("FAILURES.md"),
+    specsFolder: z.literal("specs/"),
+  }),
+})
+  // Non-api features (front and gateway specs): `app` must reference a
+  // declared app, and a feature owned by a front or gateway app declares
+  // neither HTTP routes nor DB tables — those belong to api features (the
+  // front CONSUMES contracts, the gateway RELAYS declared routes; neither
+  // OWNS any).
+  .superRefine((manifest, context) => {
+    const appsByName = new Map(manifest.apps.map((app) => [app.name, app]));
+    // `invalidates` targets must EXIST: a feature name, or the root segment of
+    // a declared route path ("/api/order-archive" → "order-archive"). A typo
+    // here would silently never invalidate anything — refused at parse time.
+    const knownInvalidationTargets = new Set<string>(
+      manifest.features.map((feature) => feature.name),
+    );
+    for (const feature of manifest.features) {
+      for (const route of feature.routes) {
+        const root = route.path.split("/")[2];
+        if (root !== undefined) knownInvalidationTargets.add(root);
+      }
+    }
+    manifest.features.forEach((feature, index) => {
+      feature.routes.forEach((route, routeIndex) => {
+        for (const target of route.invalidates ?? []) {
+          if (!knownInvalidationTargets.has(target)) {
+            context.addIssue({
+              code: "custom",
+              path: ["features", index, "routes", routeIndex, "invalidates"],
+              message: `invalidates target "${target}" matches no feature name and no route root`,
+            });
+          }
+        }
+      });
+    });
+    manifest.features.forEach((feature, index) => {
+      if (feature.app === undefined) return;
+      const owningApp = appsByName.get(feature.app);
+      if (owningApp === undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["features", index, "app"],
+          message: `app "${feature.app}" is not declared in apps[]`,
+        });
+        return;
+      }
+      if (owningApp.type !== "api" && (feature.routes.length > 0 || feature.dbTables.length > 0)) {
+        context.addIssue({
+          code: "custom",
+          path: ["features", index],
+          message:
+            "a non-api feature owns no HTTP routes and no DB tables — declare them on the api feature",
+        });
+      }
+    });
+  });
+
+export type OgygieManifest = z.infer<typeof OgygieManifestSchema>;
+export type FeatureManifest = z.infer<typeof FeatureManifestSchema>;

package/src/module-purity.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @intent Proves the purity checker AND its mutations (DECISIONS.md D22): a
+ * gate is only worth its negative test. Every case below is a source a pure
+ * module could plausibly drift into — the checker must catch each one, and
+ * must NOT cry wolf on the erased forms.
+ */
+import { describe, expect, it } from "vitest";
+import { findImpureImports, parseModuleImports } from "./module-purity.js";
+
+const PURE_MODULE = `
+/** @intent A pure module: value objects in, numbers out. */
+import type { LineCostInputs } from "./schemas.js";
+
+export function computeLineCost(inputs: LineCostInputs): number {
+  return inputs.quantity * inputs.amountCents;
+}
+`;
+
+describe("module-purity", () => {
+  it("un module sans aucun import runtime est pur", () => {
+    expect(findImpureImports(PURE_MODULE)).toEqual([]);
+    expect(findImpureImports("export const RATE = 2;\n")).toEqual([]);
+  });
+
+  it("accepte les formes ERASÉES : import type, et bindings tous préfixés type", () => {
+    expect(findImpureImports(`import type { A } from "./schemas.js";`)).toEqual([]);
+    expect(findImpureImports(`import { type A, type B } from "./schemas.js";`)).toEqual([]);
+    expect(
+      findImpureImports(`import type {\n  A,\n  B,\n} from "./schemas.js";`),
+    ).toEqual([]);
+  });
+
+  // ------------------------------------------------------------- mutations
+  it("MUTATION — un import de valeur casse la pureté (db, clock, réseau, feature voisine)", () => {
+    for (const impure of [
+      `import { tenantDb } from "@ogygie/core/tenant";`,
+      `import { fixedClock } from "@ogygie/core/clock";`,
+      `import { listOrders } from "../orders/index.js";`,
+      `import { z } from "zod";`,
+    ]) {
+      const found = findImpureImports(`${PURE_MODULE}\n${impure}`);
+      expect(found, impure).toHaveLength(1);
+      expect(found[0]?.typeOnly).toBe(false);
+    }
+  });
+
+  it("MUTATION — un import à effet de bord nu (sans binding) est détecté", () => {
+    const found = findImpureImports(`import "./fastify-decorations.js";`);
+    expect(found).toHaveLength(1);
+    expect(found[0]?.specifier).toBe("./fastify-decorations.js");
+  });
+
+  it("MUTATION — un binding de valeur mêlé à des types ne s'efface pas", () => {
+    const found = findImpureImports(`import { type A, computeThing } from "./schemas.js";`);
+    expect(found).toHaveLength(1);
+  });
+
+  it("MUTATION — import par défaut ou namespace : jamais erasé", () => {
+    expect(findImpureImports(`import schemas from "./schemas.js";`)).toHaveLength(1);
+    expect(findImpureImports(`import * as schemas from "./schemas.js";`)).toHaveLength(1);
+  });
+
+  it("MUTATION — le chargement dynamique (import(), require()) est une arête runtime", () => {
+    expect(findImpureImports(`const db = await import("@ogygie/core/db");`)).toHaveLength(1);
+    expect(findImpureImports(`const db = require("@ogygie/core/db");`)).toHaveLength(1);
+  });
+
+  it("MUTATION — un ré-export est une arête runtime (la forme même d'un index.ts)", () => {
+    for (const impure of [
+      `export * from "./loader.js";`,
+      `export * as loader from "./loader.js";`,
+      `export { runLoader } from "./loader.js";`,
+      `export { runLoader as loader } from "./loader.js";`,
+    ]) {
+      const found = findImpureImports(impure);
+      expect(found, impure).toHaveLength(1);
+      expect(found[0]?.specifier, impure).toBe("./loader.js");
+    }
+  });
+
+  it("les ré-exports ERASÉS ne comptent pas, et un export local ne s'apparie pas avec un import", () => {
+    expect(findImpureImports(`export type { Order } from "./schemas.js";`)).toEqual([]);
+    expect(findImpureImports(`export { type Order } from "./schemas.js";`)).toEqual([]);
+    const localThenImport = `export const RATE = 2;\nimport type { A } from "./a.js";\n`;
+    expect(findImpureImports(localThenImport)).toEqual([]);
+  });
+
+  it("MUTATION — signale TOUS les imports fautifs d'un coup, pas seulement le premier", () => {
+    const found = findImpureImports(
+      `import { a } from "./a.js";\nimport { b } from "./b.js";\nimport type { C } from "./c.js";\n`,
+    );
+    expect(found.map((moduleImport) => moduleImport.specifier)).toEqual(["./a.js", "./b.js"]);
+  });
+
+  it("un import commenté ou cité en prose ne compte pas comme une arête", () => {
+    expect(
+      findImpureImports(`/* import { tenantDb } from "@ogygie/core/tenant"; */\n`),
+    ).toEqual([]);
+    expect(findImpureImports(`// import { z } from "zod";\n`)).toEqual([]);
+  });
+
+  it("la politique peut autoriser explicitement un spécificateur runtime", () => {
+    const source = `import { z } from "zod";`;
+    expect(findImpureImports(source)).toHaveLength(1);
+    expect(findImpureImports(source, { allowedRuntimeSpecifiers: ["zod"] })).toEqual([]);
+  });
+
+  it("parseModuleImports rend le relevé complet, type-only compris", () => {
+    const imports = parseModuleImports(
+      `import type { A } from "./a.js";\nimport { b } from "./b.js";\n`,
+    );
+    expect(imports).toEqual([
+      { specifier: "./a.js", typeOnly: true, statement: `import type { A } from "./a.js"` },
+      { specifier: "./b.js", typeOnly: false, statement: `import { b } from "./b.js"` },
+    ]);
+  });
+});

package/src/module-purity.ts

@@ -0,0 +1,127 @@
+/**
+ * @intent Static purity check for the product's PURE modules (computation
+ * formulas, costing engines — anything advertised as "pure compute"):
+ * a pure module must have NO runtime import at all — no db, no clock, no
+ * network, no sibling feature — so its results depend on nothing but its
+ * arguments, and a test can attack it directly.
+ *
+ * Generic tooling, hence the core (DECISIONS.md D10 amended): it knows no
+ * product vocabulary, only TypeScript import syntax. Deliberately a source
+ * scan and not a runtime probe: an import with a side effect has already run
+ * by the time a test could observe it.
+ *
+ * Type-only imports (`import type ...`, and specifiers whose bindings are all
+ * `type X`) are ERASED at compile time: they carry no runtime edge and stay
+ * allowed. Everything else — value imports, bare side-effect imports,
+ * re-exports (`export ... from`), `import(...)`, `require(...)` — is impure
+ * unless explicitly allowed. A re-export is an import that hides its name: it
+ * loads the module all the same, and it is the form an `index.ts` is made of.
+ */
+
+export interface ModuleImport {
+  /** Module specifier as written, e.g. "./schemas.js". */
+  specifier: string;
+  /** True when the whole statement is erased at compile time. */
+  typeOnly: boolean;
+  /** Raw statement, quoted back in failures so the fix is obvious. */
+  statement: string;
+}
+
+/** `import ... from "x"` / `import "x"` — the multiline form included. */
+const IMPORT_STATEMENT = /\bimport\b(?![.(])([\s\S]*?)from\s*["']([^"']+)["']|\bimport\s+["']([^"']+)["']/g;
+/** Dynamic loading: no static form, no way to erase it — always a runtime edge. */
+const DYNAMIC_LOAD = /\b(?:import\s*\(|require\s*\()\s*["']([^"']+)["']/g;
+/**
+ * `export * from "x"` / `export * as ns from "x"` / `export { a } from "x"`.
+ * The clause is spelled out rather than matched lazily so a plain
+ * `export const a = 1` followed by an import never pairs up by accident.
+ */
+const REEXPORT_STATEMENT =
+  /\bexport\s+(type\s+)?(\*(?:\s+as\s+[A-Za-z_$][\w$]*)?|\{[^}]*\})\s*from\s*["']([^"']+)["']/g;
+
+/**
+ * Every static import of a module source. Comments are stripped first so a
+ * commented-out example never counts as a real edge.
+ */
+export function parseModuleImports(source: string): ModuleImport[] {
+  const code = stripComments(source);
+  const imports: ModuleImport[] = [];
+
+  for (const match of code.matchAll(IMPORT_STATEMENT)) {
+    const [statement, clause, fromSpecifier, bareSpecifier] = match;
+    const specifier = fromSpecifier ?? bareSpecifier;
+    if (specifier === undefined) continue;
+    imports.push({
+      specifier,
+      typeOnly: clause !== undefined && isTypeOnlyClause(clause),
+      statement: normalizeWhitespace(statement),
+    });
+  }
+  for (const match of code.matchAll(REEXPORT_STATEMENT)) {
+    const [statement, typeKeyword, clause, specifier] = match;
+    if (specifier === undefined || clause === undefined) continue;
+    imports.push({
+      specifier,
+      typeOnly: typeKeyword !== undefined || isTypeOnlyClause(clause),
+      statement: normalizeWhitespace(statement),
+    });
+  }
+  for (const match of code.matchAll(DYNAMIC_LOAD)) {
+    const [statement, specifier] = match;
+    if (specifier === undefined) continue;
+    imports.push({
+      specifier,
+      typeOnly: false,
+      statement: normalizeWhitespace(statement),
+    });
+  }
+  return imports;
+}
+
+export interface PurityPolicy {
+  /**
+   * Specifiers a pure module may import AT RUNTIME. Empty by default: the
+   * strictest form, and the one the product's pure modules hold themselves to.
+   */
+  allowedRuntimeSpecifiers?: readonly string[];
+}
+
+/**
+ * The imports that break purity — empty array means the module is pure.
+ * Report them all at once: a module fixed one import per run is a module
+ * fixed three times.
+ */
+export function findImpureImports(
+  source: string,
+  policy: PurityPolicy = {},
+): ModuleImport[] {
+  const allowed = new Set(policy.allowedRuntimeSpecifiers ?? []);
+  return parseModuleImports(source).filter(
+    (moduleImport) => !moduleImport.typeOnly && !allowed.has(moduleImport.specifier),
+  );
+}
+
+/**
+ * A clause is erased when the statement itself says `type`, or when EVERY
+ * named binding does (`import { type A, type B } from ...`). A default or
+ * namespace binding among them keeps the import alive.
+ */
+function isTypeOnlyClause(clause: string): boolean {
+  const trimmed = clause.trim();
+  if (trimmed.startsWith("type ")) return true;
+  const named = /^\{([\s\S]*)\}$/.exec(trimmed);
+  if (named === null || named[1] === undefined) return false;
+  const bindings = named[1]
+    .split(",")
+    .map((binding) => binding.trim())
+    .filter((binding) => binding.length > 0);
+  return bindings.length > 0 && bindings.every((binding) => binding.startsWith("type "));
+}
+
+function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+
+function normalizeWhitespace(statement: string): string {
+  return statement.replace(/\s+/g, " ").trim();
+}

package/src/product-vocabulary.scan.test.ts

@@ -0,0 +1,142 @@
+/**
+ * @intent D10 rule 1 ("test du vocabulaire") applied to the WHOLE core
+ * (Phase 3 extension): EVERY file under packages/ogygie-core/src/** — modules,
+ * tests, fixtures, JSON examples — must name no product concept: no domain
+ * word, no product name, no feature id. Fixtures leak vocabulary just as
+ * easily as code, so nothing is exempt.
+ *
+ * This file is deliberately the ONLY place allowed to WRITE the forbidden
+ * words, and therefore the only file excluded from the scan. The checker is a
+ * pure shared function (@ogygie/core/vocabulary — extracted here on its third
+ * occurrence, rule of three); its matching semantics have their own mutation
+ * tests in vocabulary.test.ts. The mutations below prove the GATE: a module
+ * that does name a product concept is caught.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { findProductVocabulary } from "./vocabulary.js";
+
+/**
+ * Forbidden stems, matched case-insensitively at a word start (so "plot"
+ * catches "plots" and "plotId", "variet" catches variety/varietes/varieties).
+ * Two families: the consuming product's identity and feature ids, and the
+ * agricultural domain itself in both languages.
+ */
+const FORBIDDEN_STEMS = [
+  // product identity and feature ids
+  "nisaba",
+  "exploitations-et-comptes",
+  "plan-semis",
+  "calculs-quantites",
+  "catalogue-prix",
+  "socle-web",
+  "bff-gateway",
+  "especes-eppo",
+  "referentiel-cycles",
+  "couts-previsionnels",
+  // domain vocabulary (fr / en)
+  "agricol",
+  "agricultur",
+  "maraich",
+  "exploitation",
+  "ferme",
+  "farm",
+  "parcelle",
+  "plot",
+  "planche",
+  "culture",
+  "crop",
+  "variet",
+  "semis",
+  "sowing",
+  "graine",
+  "seed",
+  "recolte",
+  "récolte",
+  "harvest",
+  "intrant",
+  "engrais",
+  "fertilizer",
+  "paillage",
+  "mulch",
+  "campagne",
+  "campaign",
+  "fournisseur",
+  "supplier",
+  "prix",
+  "price",
+  "espece",
+  "species",
+  "eppo",
+] as const;
+
+const SRC_DIR = fileURLToPath(new URL(".", import.meta.url));
+const SELF = fileURLToPath(import.meta.url);
+
+/** Every file under src/**, whatever its extension — fixtures included. */
+function listFilesRecursively(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const entryPath = join(dir, entry);
+    if (statSync(entryPath).isDirectory()) {
+      files.push(...listFilesRecursively(entryPath));
+    } else {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}
+
+const scannedFiles = listFilesRecursively(SRC_DIR).filter((path) => path !== SELF);
+
+describe("core — test du vocabulaire (D10) sur tout src/**", () => {
+  it("le scan couvre réellement le répertoire (garde anti-liste-vide)", () => {
+    expect(scannedFiles.length).toBeGreaterThan(20);
+  });
+
+  for (const filePath of scannedFiles) {
+    it(`ÉTANT DONNÉ ${relative(SRC_DIR, filePath)} QUAND on le lit ALORS il ne nomme aucun concept produit`, () => {
+      expect(findProductVocabulary(readFileSync(filePath, "utf8"), FORBIDDEN_STEMS)).toEqual([]);
+    });
+  }
+
+  // ------------------------------------------------------------- mutations
+  it("MUTATION : un module qui nomme un concept du domaine est DÉTECTÉ", () => {
+    const source = `
+      /** @intent Relays the plots of the farm. */
+      export function relayPlots(farmId: string, campaignName: string) {
+        return { farmId, campaignName };
+      }
+    `;
+    expect(findProductVocabulary(source, FORBIDDEN_STEMS)).toEqual([
+      "farm",
+      "plot",
+      "campaign",
+    ]);
+  });
+
+  it("MUTATION : une référence au produit ou à une feature est DÉTECTÉE", () => {
+    const source = `import { buildSchemaRegistry } from "@nisaba/gateway/schemaRegistry";
+      // derived for the plan-semis feature`;
+    // "plan-semis" is caught twice over: as a feature id, and as the domain
+    // stem "semis" it contains — hyphens are word starts too.
+    expect(findProductVocabulary(source, FORBIDDEN_STEMS)).toEqual([
+      "nisaba",
+      "plan-semis",
+      "semis",
+    ]);
+  });
+
+  it("un vocabulaire strictement générique passe (pas de faux positif)", () => {
+    const source = `
+      /** @intent Generic relay: manifest routes become typed relays. */
+      const embedderPolicy = "cross-origin-embedder-policy";
+      export function mountRelay(upstreamBaseUrl: string) {
+        return { upstreamBaseUrl, embedderPolicy };
+      }
+    `;
+    expect(findProductVocabulary(source, FORBIDDEN_STEMS)).toEqual([]);
+  });
+});