@ogygie/core 0.1.0 → 0.3.0

package/README.md

@@ -13,18 +13,22 @@ dans `apps/`.
 | `@ogygie/core/spec` | Frontmatter des specs (`parseSpecFrontmatter`) et sections canoniques |
 | `@ogygie/core/db` · `/clock` · `/tenant` · `/test-kit` | Accès DB, horloge injectable, façade multi-tenant, kit de test |
 | `@ogygie/core/web-lint` · `/bundle-budget` | Parties testables des gates front |
-| `@ogygie/core/vocabulary` | Checker du test du vocabulaire (D10) — les stems appartiennent au produit |
+| `@ogygie/core/vocabulary` | Appariement des racines de vocabulaire sur les identifiants machine — les racines appartiennent au produit |
+| `@ogygie/core/vocabulary-audit` | Jugement du gate de vocabulaire : alias interdits du code, pureté des fichiers gouvernés |
 | `@ogygie/core/gateway` | Passerelle publique dérivée du manifeste (ci-dessous) |
 | `@ogygie/core/client` | Client d'API front dérivé du manifeste (clés de cache, invalidations) |
 
 ## Le test du vocabulaire couvre TOUT le core
 
-Le gate `src/product-vocabulary.scan.test.ts` scanne chaque fichier de
-`src/**` — modules, tests, fixtures, JSON d'exemples — et casse la CI au
-moindre stem produit (nom du produit, id de feature, mot du domaine, dans
-les deux langues). Les fixtures fuient le vocabulaire aussi facilement que
-le code : rien n'est exempté, sauf le fichier de scan lui-même, seul endroit
-autorisé à ÉCRIRE les mots interdits.
+Le gate `pnpm ogygie:verify-core-vocabulary` du repo du framework scanne
+chaque fichier de ce package — modules, tests, fixtures, JSON d'exemples — et
+casse la CI à la moindre racine produit (nom du produit, id de feature, mot du
+domaine, dans les deux langues). Les fixtures fuient le vocabulaire aussi
+facilement que le code : rien n'est exempté. Les mots interdits, eux, vivent
+dans `scripts/` du repo du framework, JAMAIS ici : ce package est publié
+(`files: ["src"]`), donc une liste de mots produit stockée dedans SERAIT la
+fuite — c'est exactement ainsi que la 0.1.0 a publié le vocabulaire complet
+d'un domaine produit, dans un fichier de test.
 
 ## Hypothèses structurelles assumées (non-vocabulaires)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Ogygie framework core: manifest/spec/error schemas, generic tenancy and gate tooling. Ships TypeScript sources — Ogygie products run tsx/vitest by construction (D1).",
   "license": "MIT",
   "type": "module",
@@ -15,6 +15,7 @@
   "exports": {
     "./manifest": "./src/manifest.schema.ts",
     "./vocabulary": "./src/vocabulary.ts",
+    "./vocabulary-audit": "./src/vocabulary-audit.ts",
     "./web-lint": "./src/web-lint.ts",
     "./bundle-budget": "./src/bundle-budget.ts",
     "./spec": "./src/spec.schema.ts",
@@ -31,9 +32,6 @@
     "./gateway": "./src/manifest-gateway.ts",
     "./client": "./src/manifest-client.ts"
   },
-  "scripts": {
-    "typecheck": "tsc -p tsconfig.json"
-  },
   "peerDependencies": {
     "@electric-sql/pglite": "^0.3.0",
     "@fastify/helmet": "^13.0.0",
@@ -73,5 +71,8 @@
     "fastify": "^5.0.0",
     "typescript": "^5.8.0",
     "zod": "^4.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
   }
-}
+}

package/src/manifest.schema.test.ts

@@ -253,3 +253,99 @@ describe("manifest — app gateway, suite (D27)", () => {
     expect(parsed.success).toBe(false);
   });
 });
+
+/**
+ * Vocabulary block (spec product-vocabulary-gate B2). The fixture vocabulary
+ * is INVENTED: this package names no product's domain.
+ */
+function manifestWithVocabulary(vocabulary: unknown) {
+  return {
+    version: 1,
+    product: { name: "acme", description: "SaaS générique servant de fixture aux tests du manifeste." },
+    apps: [{ name: "api", path: "apps/api", type: "api", entryPoint: "apps/api/src/server.ts" }],
+    features: [],
+    vocabulary,
+    conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+  };
+}
+
+describe("manifest — bloc vocabulary (spec product-vocabulary-gate B2)", () => {
+  it("un bloc valide (canonique camelCase, alias minuscules) est accepté", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithVocabulary({
+        entries: [
+          { canonical: "gadget", forbiddenAliases: ["widget", "gizmo"], reference: "#gadget" },
+          { canonical: "gadgetRegistry", forbiddenAliases: ["gadget-catalog"] },
+        ],
+      }),
+    );
+    expect(parsed.success).toBe(true);
+  });
+
+  it("un manifeste SANS bloc vocabulary reste valide (le gate n'est jamais bloquant par défaut)", () => {
+    const withoutVocabulary = manifestWithVocabulary(undefined);
+    delete (withoutVocabulary as Record<string, unknown>)["vocabulary"];
+    expect(OgygieManifestSchema.safeParse(withoutVocabulary).success).toBe(true);
+  });
+
+  it("MUTATION : une casse non conforme est refusée, à l'entrée fautive", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithVocabulary({ entries: [{ canonical: "Gadget", forbiddenAliases: ["Widget"] }] }),
+    );
+    expect(parsed.success).toBe(false);
+    const paths = parsed.success ? [] : parsed.error.issues.map((issue) => issue.path.join("."));
+    expect(paths).toContain("vocabulary.entries.0.canonical");
+    expect(paths).toContain("vocabulary.entries.0.forbiddenAliases.0");
+  });
+
+  it("MUTATION : une entrée sans aucun alias interdit est refusée (elle n'interdirait rien)", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithVocabulary({ entries: [{ canonical: "gadget", forbiddenAliases: [] }] }),
+    );
+    expect(parsed.success).toBe(false);
+  });
+
+  it("MUTATION : un alias dupliqué entre deux entrées est refusé, à la seconde", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithVocabulary({
+        entries: [
+          { canonical: "gadget", forbiddenAliases: ["widget"] },
+          { canonical: "sprocket", forbiddenAliases: ["widget"] },
+        ],
+      }),
+    );
+    expect(parsed.success).toBe(false);
+    const issue = parsed.success ? undefined : parsed.error.issues[0];
+    expect(issue?.path.join(".")).toBe("vocabulary.entries.1.forbiddenAliases.0");
+    expect(issue?.message).toContain("already forbidden by entry 0");
+  });
+
+  it("MUTATION : un alias identique au canonique d'une autre entrée est refusé", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithVocabulary({
+        entries: [
+          { canonical: "gadget", forbiddenAliases: ["widget"] },
+          { canonical: "sprocket", forbiddenAliases: ["gadget"] },
+        ],
+      }),
+    );
+    expect(parsed.success).toBe(false);
+    const issue = parsed.success ? undefined : parsed.error.issues[0];
+    expect(issue?.path.join(".")).toBe("vocabulary.entries.1.forbiddenAliases.0");
+    expect(issue?.message).toContain("canonical term of entry 0");
+  });
+
+  it("MUTATION : un canonique déclaré deux fois est refusé", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithVocabulary({
+        entries: [
+          { canonical: "gadget", forbiddenAliases: ["widget"] },
+          { canonical: "gadget", forbiddenAliases: ["gizmo"] },
+        ],
+      }),
+    );
+    expect(parsed.success).toBe(false);
+    const issue = parsed.success ? undefined : parsed.error.issues[0];
+    expect(issue?.path.join(".")).toBe("vocabulary.entries.1.canonical");
+  });
+});

package/src/manifest.schema.ts

@@ -106,6 +106,45 @@ export const FrameworkManifestSchema = z.object({
     .describe("Module declaring the exhaustive list of files `upgrade` may overwrite (D3)"),
 });
 
+/**
+ * One concept of the product domain: THE canonical machine term, and the
+ * aliases the code may never use for it. The machine part lives here and
+ * nowhere else — `AGENTS.product.md` explains the business meaning in prose
+ * and references the canonical term, but a second parseable location would be
+ * a second source of truth.
+ *
+ * Both fields are matched by ROOT and case-insensitively (see
+ * `@ogygie/core/vocabulary`), so an alias is declared in its plainest machine
+ * form — lowercase, kebab-case at most. Anything else (spaces, punctuation,
+ * capitals) would match nothing and give a false sense of protection, so it is
+ * refused at parse time rather than silently ignored.
+ */
+export const VocabularyEntrySchema = z.object({
+  canonical: z
+    .string()
+    .regex(/^[a-z][a-zA-Z0-9]*$/, "camelCase English term required")
+    .describe("The one machine term for this concept, e.g. gadget"),
+  forbiddenAliases: z
+    .array(
+      z
+        .string()
+        .min(2)
+        .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "lowercase root (kebab-case allowed) required"),
+    )
+    .min(1)
+    .describe("Roots the code may never carry for this concept, e.g. widget"),
+  reference: z
+    .string()
+    .optional()
+    .describe("Anchor into AGENTS.product.md where the concept is explained"),
+});
+export type VocabularyEntry = z.infer<typeof VocabularyEntrySchema>;
+
+export const ProductVocabularySchema = z.object({
+  entries: z.array(VocabularyEntrySchema),
+});
+export type ProductVocabulary = z.infer<typeof ProductVocabularySchema>;
+
 export const OgygieManifestSchema = z.object({
   version: z.literal(1),
   product: z.object({
@@ -123,6 +162,9 @@ export const OgygieManifestSchema = z.object({
     }),
   ),
   features: z.array(FeatureManifestSchema),
+  vocabulary: ProductVocabularySchema.optional().describe(
+    "The product's closed vocabulary — declared here, enforced by `ogygie verify-vocabulary`. Absent = gate silent",
+  ),
   conventions: z.object({
     agentsMd: z.literal("AGENTS.md"),
     failuresMd: z.literal("FAILURES.md"),
@@ -135,6 +177,50 @@ export const OgygieManifestSchema = z.object({
   // front CONSUMES contracts, the gateway RELAYS declared routes; neither
   // OWNS any).
   .superRefine((manifest, context) => {
+    // Vocabulary coherence (B2): one concept = one term. A canonical declared
+    // twice, an alias claimed by two entries, or an alias that IS someone's
+    // canonical would make the gate's suggested fix ambiguous — refused here,
+    // at the entry that carries it, rather than discovered at scan time.
+    const canonicalOwners = new Map<string, number>();
+    const aliasOwners = new Map<string, number>();
+    (manifest.vocabulary?.entries ?? []).forEach((entry, index) => {
+      const canonicalRoot = entry.canonical.toLowerCase();
+      const firstOwner = canonicalOwners.get(canonicalRoot);
+      if (firstOwner !== undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["vocabulary", "entries", index, "canonical"],
+          message: `canonical "${entry.canonical}" is already declared by entry ${firstOwner}`,
+        });
+      } else {
+        canonicalOwners.set(canonicalRoot, index);
+      }
+    });
+    (manifest.vocabulary?.entries ?? []).forEach((entry, index) => {
+      entry.forbiddenAliases.forEach((alias, aliasIndex) => {
+        const path = ["vocabulary", "entries", index, "forbiddenAliases", aliasIndex];
+        const canonicalOwner = canonicalOwners.get(alias);
+        if (canonicalOwner !== undefined) {
+          context.addIssue({
+            code: "custom",
+            path,
+            message: `alias "${alias}" is the canonical term of entry ${canonicalOwner} — a term cannot be both`,
+          });
+          return;
+        }
+        const firstOwner = aliasOwners.get(alias);
+        if (firstOwner !== undefined) {
+          context.addIssue({
+            code: "custom",
+            path,
+            message: `alias "${alias}" is already forbidden by entry ${firstOwner} — one alias belongs to one concept`,
+          });
+          return;
+        }
+        aliasOwners.set(alias, index);
+      });
+    });
+
     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

package/src/vocabulary-audit.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @intent Mutation tests of the vocabulary JUDGEMENT (spec
+ * product-vocabulary-gate B3/B4). Everything is proven in memory: files are
+ * handed in as text, so the rules — aliases only in source, every root in
+ * governed files, comments free on one side and judged on the other — are
+ * checked without touching a disk. The fixture vocabulary is INVENTED.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  auditProductVocabulary,
+  canonicalByAlias,
+  vocabularyRootsOf,
+} from "./vocabulary-audit.js";
+
+const VOCABULARY = {
+  entries: [
+    { canonical: "gadget", forbiddenAliases: ["widget", "gizmo"] },
+    { canonical: "gadgetRegistry", forbiddenAliases: ["gadget-catalog"] },
+  ],
+};
+
+describe("auditProductVocabulary — B3 : les alias interdits dans le code produit", () => {
+  it("ÉTANT DONNÉ un alias interdit QUAND le code l'emploie ALORS la violation nomme le fichier, l'identifiant et le canonique", () => {
+    const violations = auditProductVocabulary({
+      vocabulary: VOCABULARY,
+      sourceFiles: [
+        { path: "apps/api/src/features/stock/service.ts", content: "const widgetId = 1;" },
+      ],
+      governedFiles: [],
+    });
+    expect(violations).toEqual([
+      {
+        kind: "FORBIDDEN_ALIAS",
+        filePath: "apps/api/src/features/stock/service.ts",
+        match: { root: "widget", identifier: "widgetId", line: 1 },
+        canonical: "gadget",
+      },
+    ]);
+  });
+
+  it("attrape l'alias sous toutes ses formes d'identifiant (camel, Pascal, snake)", () => {
+    const violations = auditProductVocabulary({
+      vocabulary: VOCABULARY,
+      sourceFiles: [
+        {
+          path: "apps/api/src/features/stock/db.schema.ts",
+          content: ["const widgetId = 1;", "class WidgetTable {}", "const widget_code = 'x';"].join("\n"),
+        },
+      ],
+      governedFiles: [],
+    });
+    expect(violations.map((violation) => violation.match.identifier)).toEqual([
+      "widgetId",
+      "WidgetTable",
+      "widget_code",
+    ]);
+    expect(violations.map((violation) => violation.match.line)).toEqual([1, 2, 3]);
+  });
+
+  it("le terme CANONIQUE dans le code produit ne déclenche rien — c'est le mot juste", () => {
+    expect(
+      auditProductVocabulary({
+        vocabulary: VOCABULARY,
+        sourceFiles: [{ path: "apps/api/src/x.ts", content: "const gadgetId = 1;" }],
+        governedFiles: [],
+      }),
+    ).toEqual([]);
+  });
+
+  it("la prose des commentaires est libre dans le code produit", () => {
+    expect(
+      auditProductVocabulary({
+        vocabulary: VOCABULARY,
+        sourceFiles: [
+          { path: "apps/api/src/x.ts", content: "// on disait widget avant\nconst gadgetId = 1;" },
+        ],
+        governedFiles: [],
+      }),
+    ).toEqual([]);
+  });
+
+  it("un manifeste SANS bloc vocabulary ne produit aucune violation", () => {
+    expect(
+      auditProductVocabulary({
+        vocabulary: undefined,
+        sourceFiles: [{ path: "apps/api/src/x.ts", content: "const widgetId = 1;" }],
+        governedFiles: [{ path: "AGENTS.md", content: "gadget partout" }],
+      }),
+    ).toEqual([]);
+  });
+
+  it("un bloc vocabulary VIDE ne produit aucune violation non plus", () => {
+    expect(
+      auditProductVocabulary({
+        vocabulary: { entries: [] },
+        sourceFiles: [{ path: "apps/api/src/x.ts", content: "const widgetId = 1;" }],
+        governedFiles: [],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("auditProductVocabulary — B4 : la pureté des fichiers gouvernés", () => {
+  it("ÉTANT DONNÉ un fichier gouverné QUAND il nomme un terme CANONIQUE ALORS c'est une violation", () => {
+    const violations = auditProductVocabulary({
+      vocabulary: VOCABULARY,
+      sourceFiles: [],
+      governedFiles: [{ path: "AGENTS.md", content: "Chaque gadget porte un identifiant." }],
+    });
+    expect(violations).toEqual([
+      {
+        kind: "GOVERNED_FILE",
+        filePath: "AGENTS.md",
+        match: { root: "gadget", identifier: "gadget", line: 1 },
+        canonical: null,
+      },
+    ]);
+  });
+
+  it("un commentaire d'un fichier gouverné est jugé lui aussi (il est identique partout)", () => {
+    const violations = auditProductVocabulary({
+      vocabulary: VOCABULARY,
+      sourceFiles: [],
+      governedFiles: [{ path: "tsconfig.base.json", content: "// tuned for the gadget pipeline" }],
+    });
+    expect(violations.map((violation) => violation.match.root)).toEqual(["gadget"]);
+  });
+
+  it("un ALIAS interdit dans un fichier gouverné ne déclenche RIEN (v2)", () => {
+    // An alias is by definition a word the product does NOT use, so finding it
+    // in a generic file proves no contamination — while the framework's own
+    // neutral domain and plain computing English produce such collisions in
+    // bulk (eight false positives out of eighteen on the first real migration).
+    expect(
+      auditProductVocabulary({
+        vocabulary: VOCABULARY,
+        sourceFiles: [],
+        governedFiles: [
+          { path: "AGENTS.md", content: "const widgetId = 1; // gizmo everywhere" },
+        ],
+      }),
+    ).toEqual([]);
+  });
+
+  it("un fichier gouverné strictement générique passe", () => {
+    expect(
+      auditProductVocabulary({
+        vocabulary: VOCABULARY,
+        sourceFiles: [],
+        governedFiles: [{ path: "AGENTS.md", content: "Une feature = un dossier autonome." }],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("dérivations du bloc vocabulary", () => {
+  it("vocabularyRootsOf rend les canoniques ET les alias", () => {
+    expect(vocabularyRootsOf(VOCABULARY)).toEqual([
+      "gadget",
+      "widget",
+      "gizmo",
+      "gadgetRegistry",
+      "gadget-catalog",
+    ]);
+  });
+
+  it("canonicalByAlias donne la correction à suggérer pour chaque alias", () => {
+    expect([...canonicalByAlias(VOCABULARY).entries()]).toEqual([
+      ["widget", "gadget"],
+      ["gizmo", "gadget"],
+      ["gadget-catalog", "gadgetRegistry"],
+    ]);
+  });
+});

package/src/vocabulary-audit.ts

@@ -0,0 +1,111 @@
+/**
+ * @intent The JUDGEMENT of the vocabulary gate (spec product-vocabulary-gate
+ * B3/B4). `@ogygie/core/vocabulary` answers "does this text carry a forbidden
+ * root?"; this module answers "given what the manifest declares, which files
+ * are in violation, and what should the agent write instead?".
+ *
+ * Two rules, and they do not read the same text:
+ * - PRODUCT SOURCE (B3): only forbidden ALIASES are hunted, and only in the
+ *   machine identifiers — comments are blanked out first. The business prose
+ *   of the project keeps its own words; the code has one term per concept.
+ * - GOVERNED FILES (B4): the CANONICAL terms are hunted in the RAW text,
+ *   comments and all. A governed file is identical in every Ogygie project, so
+ *   it may know no product's domain at all, not even in a comment. That is the
+ *   framework/product boundary made mechanical.
+ *   Forbidden aliases are deliberately NOT hunted there (spec v2): an alias is
+ *   by definition a word the product does NOT use, so finding one in a generic
+ *   file proves no contamination — while the framework's own neutral domain
+ *   (`orders`, `customerId`) and plain computing English (`level`, `register`)
+ *   collide with it in bulk. Eight false positives out of eighteen on the first
+ *   real migration, and a gate whose verdicts one learns to ignore protects
+ *   nothing.
+ *
+ * The filesystem is injected (files come in as text), so the whole judgement
+ * is a pure function proven in memory with its mutations.
+ */
+import type { ProductVocabulary } from "./manifest.schema.js";
+import { findProductVocabulary, stripComments, type VocabularyMatch } from "./vocabulary.js";
+
+/** One file handed to the audit, already read by the caller. */
+export interface ScannedFile {
+  /** Path as it should be reported, relative to the project root. */
+  readonly path: string;
+  readonly content: string;
+}
+
+export type VocabularyViolationKind =
+  /** Product source code carrying a forbidden alias (B3). */
+  | "FORBIDDEN_ALIAS"
+  /** A governed file naming any product term at all (B4). */
+  | "GOVERNED_FILE";
+
+export interface VocabularyViolation {
+  readonly kind: VocabularyViolationKind;
+  readonly filePath: string;
+  readonly match: VocabularyMatch;
+  /** The term to use instead — null when the fix is to remove, not rename. */
+  readonly canonical: string | null;
+}
+
+export interface VocabularyAuditInput {
+  /** The manifest's `vocabulary` block — absent means the gate stays silent. */
+  readonly vocabulary: ProductVocabulary | undefined;
+  /** Code files of the product's apps and packages (B3). */
+  readonly sourceFiles: readonly ScannedFile[];
+  /** Framework-governed files as they exist in the project (B4). */
+  readonly governedFiles: readonly ScannedFile[];
+}
+
+/**
+ * Every root the vocabulary declares: canonical terms AND forbidden aliases.
+ * Kept for callers that need the full list; the governed-file rule uses the
+ * canonical terms alone (see above).
+ */
+export function vocabularyRootsOf(vocabulary: ProductVocabulary): readonly string[] {
+  return vocabulary.entries.flatMap((entry) => [entry.canonical, ...entry.forbiddenAliases]);
+}
+
+/** alias → the canonical term to use instead. */
+export function canonicalByAlias(vocabulary: ProductVocabulary): ReadonlyMap<string, string> {
+  const byAlias = new Map<string, string>();
+  for (const entry of vocabulary.entries) {
+    for (const alias of entry.forbiddenAliases) byAlias.set(alias, entry.canonical);
+  }
+  return byAlias;
+}
+
+export function auditProductVocabulary(
+  input: VocabularyAuditInput,
+): readonly VocabularyViolation[] {
+  const { vocabulary } = input;
+  if (vocabulary === undefined || vocabulary.entries.length === 0) return [];
+
+  const canonicalOfAlias = canonicalByAlias(vocabulary);
+  const forbiddenAliases = [...canonicalOfAlias.keys()];
+  const canonicalTerms = vocabulary.entries.map((entry) => entry.canonical);
+  const violations: VocabularyViolation[] = [];
+
+  for (const file of input.sourceFiles) {
+    for (const match of findProductVocabulary(stripComments(file.content), forbiddenAliases)) {
+      violations.push({
+        kind: "FORBIDDEN_ALIAS",
+        filePath: file.path,
+        match,
+        canonical: canonicalOfAlias.get(match.root) ?? null,
+      });
+    }
+  }
+
+  for (const file of input.governedFiles) {
+    for (const match of findProductVocabulary(file.content, canonicalTerms)) {
+      violations.push({
+        kind: "GOVERNED_FILE",
+        filePath: file.path,
+        match,
+        canonical: null,
+      });
+    }
+  }
+
+  return violations;
+}

package/src/vocabulary.test.ts

@@ -1,46 +1,110 @@
 /**
- * @intent Mutation tests of the vocabulary CHECKER itself (D22): the matching
- * semantics — word start, case-insensitivity, hyphens, regex escaping — are
- * what the whole gate rests on, so each one is proven with INVENTED stems.
- * The real forbidden list, and the scan of the core's files against it, live
- * in product-vocabulary.scan.test.ts (the only file allowed to write the
- * forbidden words).
+ * @intent Mutation tests of the vocabulary CHECKER itself: the matching
+ * semantics — segment cutting, prefix on the last segment, case-insensitivity,
+ * multi-segment roots — are what the whole gate rests on, so each one is
+ * proven with an INVENTED fixture vocabulary. No real product word appears
+ * here, or anywhere else in this package: that is the rule the gate enforces,
+ * and a test file ships in the published package like any other source.
  */
 import { describe, expect, it } from "vitest";
-import { findProductVocabulary } from "./vocabulary.js";
+import {
+  findProductVocabulary,
+  segmentsOfIdentifier,
+  stripComments,
+} from "./vocabulary.js";
 
-describe("findProductVocabulary — sémantique du matching", () => {
-  it("détecte un stem en début de mot, jamais en plein milieu", () => {
+describe("findProductVocabulary — semantique de l'appariement", () => {
+  it("apparie une racine au DÉBUT d'un segment, jamais au milieu", () => {
     expect(findProductVocabulary("the embedder policy", ["bed"])).toEqual([]);
-    expect(findProductVocabulary("const bedCount = 2;", ["bed"])).toEqual(["bed"]);
+    expect(findProductVocabulary("const bedCount = 2;", ["bed"])).toEqual([
+      { root: "bed", identifier: "bedCount", line: 1 },
+    ]);
   });
 
-  it("un stem attrape ses dérivés camelCase et ses pluriels", () => {
-    expect(findProductVocabulary("relayGadgets(gadgetId)", ["gadget"])).toEqual(["gadget"]);
+  it("une racine attrape ses dérivés camelCase et ses pluriels", () => {
+    expect(findProductVocabulary("relayGadgets(gadgetId)", ["gadget"])).toEqual([
+      { root: "gadget", identifier: "relayGadgets", line: 1 },
+      { root: "gadget", identifier: "gadgetId", line: 1 },
+    ]);
+  });
+
+  it("snake_case et kebab-case sont découpés comme camelCase", () => {
+    expect(findProductVocabulary("widget_code, widget-code", ["widget"])).toEqual([
+      { root: "widget", identifier: "widget_code", line: 1 },
+      { root: "widget", identifier: "widget-code", line: 1 },
+    ]);
   });
 
-  it("insensible à la casse", () => {
-    expect(findProductVocabulary("import { Gadget } from x", ["gadget"])).toEqual(["gadget"]);
+  it("insensible à la casse, y compris pour un type PascalCase", () => {
+    expect(findProductVocabulary("import { GadgetTable } from x", ["gadget"])).toEqual([
+      { root: "gadget", identifier: "GadgetTable", line: 1 },
+    ]);
+  });
+
+  it("une racine multi-segments exige la SÉQUENCE complète dans un même token", () => {
+    expect(
+      findProductVocabulary("the gadget-registry feature", ["gadget-registry", "registry"]),
+    ).toEqual([
+      { root: "gadget-registry", identifier: "gadget-registry", line: 1 },
+      { root: "registry", identifier: "gadget-registry", line: 1 },
+    ]);
+    expect(findProductVocabulary("widgetRegistry", ["gadget-registry"])).toEqual([]);
   });
 
-  it("un tiret est un début de mot : un id kebab-case déclenche chacun de ses stems", () => {
-    expect(findProductVocabulary("the gadget-registry feature", ["gadget-registry", "registry"])).toEqual([
-      "gadget-registry",
-      "registry",
+  it("rend la LIGNE de chaque trouvaille et dédoublonne par (racine, identifiant)", () => {
+    const source = "a gadget here\nanother gadget there\nand a gadgetId";
+    expect(findProductVocabulary(source, ["gadget"])).toEqual([
+      { root: "gadget", identifier: "gadget", line: 1 },
+      { root: "gadget", identifier: "gadgetId", line: 3 },
     ]);
   });
 
-  it("rend les stems dans l'ordre de la liste, une seule fois chacun", () => {
-    const source = "a gadget, another gadget, a widget";
-    expect(findProductVocabulary(source, ["widget", "gadget"])).toEqual(["widget", "gadget"]);
+  it("une racine qui n'est pas un identifiant machine n'apparie RIEN", () => {
+    // No regex escaping to get wrong: matching compares segments, so a root
+    // carrying punctuation simply matches no segment. This is why the manifest
+    // schema constrains the shape of a declared alias (B2) instead of relying
+    // on the checker to make sense of it.
+    expect(findProductVocabulary("uses c++ everywhere", ["c++"])).toEqual([]);
+    expect(findProductVocabulary("a gadget here", ["gadget."])).toEqual([]);
   });
 
-  it("échappe les caractères spéciaux de regex dans les stems", () => {
-    expect(findProductVocabulary("uses c++ everywhere", ["c++"])).toEqual(["c++"]);
-    expect(findProductVocabulary("plain c here", ["c++"])).toEqual([]);
+  it("un vocabulaire strictement générique ne déclenche rien", () => {
+    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, ["gadget", "widget"])).toEqual([]);
   });
 
-  it("une source sans aucun stem interdit rend une liste vide", () => {
-    expect(findProductVocabulary("generic relay of manifest routes", ["gadget"])).toEqual([]);
+  it("une liste de racines vide ne déclenche rien", () => {
+    expect(findProductVocabulary("gadgetId everywhere", [])).toEqual([]);
+  });
+});
+
+describe("segmentsOfIdentifier — découpage des identifiants machine", () => {
+  it("coupe camelCase, PascalCase, snake_case et kebab-case", () => {
+    expect(segmentsOfIdentifier("gadgetId")).toEqual(["gadget", "id"]);
+    expect(segmentsOfIdentifier("GadgetTable")).toEqual(["gadget", "table"]);
+    expect(segmentsOfIdentifier("gadget_code")).toEqual(["gadget", "code"]);
+    expect(segmentsOfIdentifier("gadget-registry")).toEqual(["gadget", "registry"]);
+  });
+
+  it("garde un acronyme collé au mot qui le suit comme deux segments", () => {
+    expect(segmentsOfIdentifier("HTTPGadget")).toEqual(["http", "gadget"]);
+  });
+});
+
+describe("stripComments — la prose des commentaires est libre", () => {
+  it("efface // et /* */ SANS déplacer les numéros de ligne", () => {
+    const source = ["// gadget in a comment", "const widgetId = 1; // gadget again", "/* gadget", "still gadget */", "const gadgetCount = 2;"].join("\n");
+    const stripped = stripComments(source);
+    expect(stripped.split("\n")).toHaveLength(5);
+    expect(findProductVocabulary(stripped, ["gadget", "widget"])).toEqual([
+      { root: "widget", identifier: "widgetId", line: 2 },
+      { root: "gadget", identifier: "gadgetCount", line: 5 },
+    ]);
   });
 });

package/src/vocabulary.ts

@@ -1,36 +1,123 @@
 /**
- * @intent Testable heart of the vocabulary gate (DECISIONS.md D10 rule 1: a
- * framework module names NO product concept — no domain word, no product name,
- * no feature id). Pure function — source text and stems in, findings out — so
- * the scan test and the mutation tests required by D22 feed it directly.
- * Extracted on its THIRD occurrence (rule of three, AGENTS.md §Workflow 5):
- * the first two copies lived in the vocabulary tests of the manifest-derived
- * gateway and client. The stems themselves are product configuration and do
- * NOT live here: the caller owns its forbidden list.
+ * @intent Testable heart of the vocabulary gate: a product declares its
+ * canonical terms and their forbidden aliases in `ogygie.manifest.json`, and
+ * the gates enforce them. Pure functions — text and roots in, matches out —
+ * so every rule is proven in memory, with its mutations, and the filesystem
+ * stays in the callers (the CLI command, the framework's own CI gate).
+ *
+ * The roots themselves are product configuration and NEVER live here: this
+ * module ships inside `@ogygie/core`, which knows no word of any product
+ * domain. A framework module naming one would be the very leak this gate
+ * exists to catch.
+ *
+ * Matching is done on machine IDENTIFIERS, not on raw substrings: a token is
+ * cut into segments (camelCase, PascalCase, snake_case, kebab-case) and a root
+ * matches a segment by PREFIX — so `gadget` catches `gadgets` and `gadgetId`,
+ * while `bed` never trips on `embedder`. A multi-segment root (`gadget-registry`)
+ * requires its whole consecutive sequence inside one token.
  */
 
+/** One forbidden root, found once, with the identifier that carries it. */
+export interface VocabularyMatch {
+  /** The declared root that matched, exactly as declared. */
+  readonly root: string;
+  /** The whole machine token carrying it, in its original casing. */
+  readonly identifier: string;
+  /** 1-based line number in the scanned text. */
+  readonly line: number;
+}
+
 /**
- * Every forbidden stem the source names, in the order of the given list —
- * one entry per stem, however many times it appears.
- *
- * A stem matches case-insensitively at a WORD START (`(?<![\p{L}\p{N}])`),
- * not as a bare substring: "embedder" must not trip on a stem "bed", but a
- * camel-case usage like "tenantId" must trip on a stem "tenant". Hyphens are
- * word starts too, so a kebab-case id is caught both as a full id and through
- * every stem it contains.
+ * A machine token: a letter-initial run, possibly joined by `-`, `_` or `$`.
+ * Unicode letters on purpose — a French domain word is a root a product may
+ * forbid, and ASCII-only tokenizing would silently miss its accented forms.
  */
-export function findProductVocabulary(
-  source: string,
-  forbiddenStems: readonly string[],
-): string[] {
-  const found: string[] = [];
-  for (const stem of forbiddenStems) {
-    // No "-" in this class: in unicode mode an escaped hyphen is itself an
-    // invalid escape, and a hyphen needs no escaping outside a class.
-    const escaped = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (new RegExp(`(?<![\\p{L}\\p{N}])${escaped}`, "iu").test(source)) {
-      found.push(stem);
+const TOKEN_PATTERN = /\p{L}[\p{L}\p{N}]*(?:[-_$][\p{L}\p{N}]+)*/gu;
+
+/** Cuts a machine token into its lowercase segments. */
+export function segmentsOfIdentifier(token: string): string[] {
+  return token
+    .split(/[-_$]+/)
+    .flatMap((part) =>
+      part
+        // camelCase (and digit-to-upper) boundary, then the ACRONYMWord one.
+        .replace(/(?<=\p{Ll}|\p{N})(?=\p{Lu})/gu, " ")
+        .replace(/(?<=\p{Lu})(?=\p{Lu}\p{Ll})/gu, " ")
+        .split(" "),
+    )
+    .filter((segment) => segment.length > 0)
+    .map((segment) => segment.toLowerCase());
+}
+
+/** Does this token carry that root: segment sequence, prefix on the last one? */
+function tokenCarriesRoot(
+  tokenSegments: readonly string[],
+  rootSegments: readonly string[],
+): boolean {
+  const lastIndex = rootSegments.length - 1;
+  for (let start = 0; start + rootSegments.length <= tokenSegments.length; start += 1) {
+    let leadingSegmentsMatch = true;
+    for (let offset = 0; offset < lastIndex; offset += 1) {
+      if (tokenSegments[start + offset] !== rootSegments[offset]) {
+        leadingSegmentsMatch = false;
+        break;
+      }
+    }
+    const lastTokenSegment = tokenSegments[start + lastIndex];
+    if (
+      leadingSegmentsMatch &&
+      lastTokenSegment !== undefined &&
+      lastTokenSegment.startsWith(rootSegments[lastIndex] ?? "")
+    ) {
+      return true;
     }
   }
-  return found;
+  return false;
+}
+
+/**
+ * Every forbidden root the text names, in order of appearance, deduplicated by
+ * (root, identifier): one finding per distinct faulty identifier, however many
+ * times it is repeated — a gate printing the same identifier two hundred times
+ * is a gate nobody reads.
+ */
+export function findProductVocabulary(
+  sourceText: string,
+  vocabularyRoots: ReadonlyArray<string>,
+): ReadonlyArray<VocabularyMatch> {
+  const roots = vocabularyRoots.map((root) => ({
+    root,
+    segments: segmentsOfIdentifier(root),
+  }));
+  const matches: VocabularyMatch[] = [];
+  const alreadyReported = new Set<string>();
+  sourceText.split("\n").forEach((lineText, lineIndex) => {
+    for (const token of lineText.match(TOKEN_PATTERN) ?? []) {
+      const tokenSegments = segmentsOfIdentifier(token);
+      for (const { root, segments } of roots) {
+        if (segments.length === 0) continue;
+        if (!tokenCarriesRoot(tokenSegments, segments)) continue;
+        const reportKey = `${root} ${token}`;
+        if (alreadyReported.has(reportKey)) continue;
+        alreadyReported.add(reportKey);
+        matches.push({ root, identifier: token, line: lineIndex + 1 });
+      }
+    }
+  });
+  return matches;
+}
+
+/**
+ * Blanks out comments while KEEPING line numbers and line count — the prose of
+ * a comment is free (the domain may speak its own language there), only
+ * machine identifiers are judged. Deliberately lexical and dependency-free: a
+ * comment marker inside a string literal blanks a little more than it should,
+ * which can only ever HIDE a violation in that line's remainder, never invent
+ * one.
+ */
+export function stripComments(sourceText: string): string {
+  const blankKeepingNewlines = (text: string): string => text.replace(/[^\n]/g, " ");
+  return sourceText
+    .replace(/\/\*[\s\S]*?\*\//g, blankKeepingNewlines)
+    .replace(/\/\/[^\n]*/g, blankKeepingNewlines);
 }

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

@@ -1,142 +0,0 @@
-/**
- * @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([]);
-  });
-});