@ogygie/core 0.5.4 → 0.6.0

package/README.md

@@ -9,6 +9,7 @@ dans `apps/`.
 | Export | Rôle |
 |---|---|
 | `@ogygie/core/errors` | Format `OgygieError` (code stable, `file`, `cause`, `suggestedFix`) |
+| `@ogygie/core/manifest-owners` | Quelle entrée de la carte possède une spec — feature ou package du produit |
 | `@ogygie/core/manifest` | Schéma du manifeste `ogygie.manifest.json` |
 | `@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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/core",
-  "version": "0.5.4",
+  "version": "0.6.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",
@@ -14,6 +14,7 @@
   },
   "exports": {
     "./manifest": "./src/manifest.schema.ts",
+    "./manifest-owners": "./src/manifest-owners.ts",
     "./vocabulary": "./src/vocabulary.ts",
     "./vocabulary-audit": "./src/vocabulary-audit.ts",
     "./web-lint": "./src/web-lint.ts",

package/src/manifest-owners.test.ts

@@ -0,0 +1,79 @@
+/**
+ * @intent Mutation tests of the spec-lifecycle lookup (spec manifest-packages
+ * B2). The rule it serves is unchanged — a spec claims `implemented` only when
+ * the map confirms — so what is proven here is that BOTH natures of entry can
+ * confirm, and that neither shadows the other.
+ */
+import { describe, expect, it } from "vitest";
+import { findSpecOwner } from "./manifest-owners.js";
+import { OgygieManifestSchema } from "./manifest.schema.js";
+
+function manifestWith(extra: Record<string, unknown>) {
+  return OgygieManifestSchema.parse({
+    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: [],
+    conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+    ...extra,
+  });
+}
+
+const gadgetEngine = {
+  name: "gadget-engine",
+  path: "packages/gadget-engine",
+  intent: "Moteur pur : aucune I/O, aucune horloge, portable navigateur.",
+  spec: "specs/gadget-engine.spec.md",
+  dependsOn: [],
+  status: "delivered",
+};
+
+describe("findSpecOwner — feature ou package, la carte confirme les deux", () => {
+  it("ÉTANT DONNÉ une spec dont le code vit dans un PACKAGE ALORS la carte le confirme", () => {
+    const owner = findSpecOwner(manifestWith({ packages: [gadgetEngine] }), "gadget-engine");
+    expect(owner).toEqual({
+      kind: "package",
+      name: "gadget-engine",
+      status: "delivered",
+      folder: "packages/gadget-engine",
+    });
+  });
+
+  it("une feature reste trouvée, et son dossier est joint au chemin de son app", () => {
+    const owner = findSpecOwner(
+      manifestWith({
+        features: [
+          {
+            name: "orders",
+            intent: "Feature d'exemple servant de fixture aux tests du manifeste.",
+            folder: "src/features/orders",
+            spec: "specs/orders.spec.md",
+            routes: [],
+            dbTables: [],
+            dependsOn: [],
+            status: "delivered",
+          },
+        ],
+      }),
+      "orders",
+    );
+    expect(owner?.kind).toBe("feature");
+    expect(owner?.folder).toBe("apps/api/src/features/orders");
+  });
+
+  it("une spec sans entrée dans la carte n'a AUCUN propriétaire — le refus reste dû", () => {
+    expect(findSpecOwner(manifestWith({}), "inconnue")).toBeUndefined();
+  });
+
+  it("le statut du package est rendu tel quel : un package en cours ne vaut pas livré", () => {
+    const owner = findSpecOwner(
+      manifestWith({ packages: [{ ...gadgetEngine, status: "in-progress" }] }),
+      "gadget-engine",
+    );
+    expect(owner?.status).toBe("in-progress");
+  });
+
+  it("un manifeste SANS bloc packages se comporte exactement comme avant", () => {
+    expect(findSpecOwner(manifestWith({}), "gadget-engine")).toBeUndefined();
+  });
+});

package/src/manifest-owners.ts

@@ -0,0 +1,72 @@
+/**
+ * @intent Answers the ONE question the spec lifecycle rests on: which entry of
+ * the map owns this spec, and how far along is it?
+ *
+ * The rule itself does not change — a spec only claims `implemented` when the
+ * manifest confirms it. What changes is that the map now has two kinds of
+ * entry able to confirm: a feature living under an app, and a PRODUCT PACKAGE
+ * living outside every app (spec manifest-packages). Before that, a spec whose
+ * code sat in `packages/` could never be marked finished, and nothing said why
+ * — the gate answered `manifest status=absent` and suggested two fixes, both
+ * impossible.
+ *
+ * Lives in the core, not in the gate script, so the rule travels with the
+ * versioned package instead of with a copy each project keeps.
+ */
+import type { OgygieManifest } from "./manifest.schema.js";
+
+export type SpecOwnerKind = "feature" | "package";
+
+export interface SpecOwner {
+  kind: SpecOwnerKind;
+  name: string;
+  status: "skeleton" | "in-progress" | "delivered";
+  /**
+   * Folder holding the code, relative to the REPO root — already joined with
+   * the owning app's path for a feature, whose own `folder` is relative to it.
+   * Null when the map cannot say (a feature whose app is not declared).
+   */
+  folder: string | null;
+}
+
+/**
+ * The entry owning `specId`, feature first. Names are unique across the whole
+ * map (the schema refuses a package named like a feature), so the order only
+ * decides which lookup runs first, never which answer is right.
+ */
+export function findSpecOwner(
+  manifest: OgygieManifest,
+  specId: string,
+): SpecOwner | undefined {
+  const feature = manifest.features.find((candidate) => candidate.name === specId);
+  if (feature !== undefined) {
+    const owningApp =
+      feature.app === undefined
+        ? manifest.apps.find((app) => app.type === "api")
+        : manifest.apps.find((app) => app.name === feature.app);
+    return {
+      kind: "feature",
+      name: feature.name,
+      status: feature.status,
+      folder: owningApp === undefined ? null : `${owningApp.path}/${feature.folder}`,
+    };
+  }
+
+  const productPackage = (manifest.packages ?? []).find(
+    (candidate) => candidate.name === specId,
+  );
+  if (productPackage !== undefined) {
+    return {
+      kind: "package",
+      name: productPackage.name,
+      status: productPackage.status,
+      folder: productPackage.path,
+    };
+  }
+
+  return undefined;
+}
+
+/** What a refusal should suggest — both natures, never one that cannot exist. */
+export const SPEC_OWNER_FIX =
+  "Set the owning entry to delivered in the manifest — a feature under `features`, or a library under `packages` — or keep the spec in validated.";

package/src/manifest.schema.test.ts

@@ -373,3 +373,86 @@ describe("manifest — apps vendored (spec product-vocabulary-gate B3, v3)", ()
     expect(OgygieManifestSchema.safeParse(manifestWithApp({ vendored: false })).success).toBe(false);
   });
 });
+
+/** Packages du produit (spec manifest-packages B1/B3). */
+function manifestWithPackages(packages: unknown, features: 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,
+    packages,
+    conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+  };
+}
+
+const enginePackage = {
+  name: "gadget-engine",
+  path: "packages/gadget-engine",
+  intent: "Moteur pur : aucune I/O, aucune horloge, portable navigateur.",
+  spec: "specs/gadget-engine.spec.md",
+  dependsOn: [],
+  status: "delivered",
+};
+
+const featureNamed = (name: string, dependsOn: string[] = []) => ({
+  name,
+  intent: "Feature d'exemple servant de fixture aux tests du manifeste.",
+  folder: `src/features/${name}`,
+  spec: null,
+  routes: [],
+  dbTables: [],
+  dependsOn,
+  status: "delivered",
+});
+
+describe("manifest — packages du produit (spec manifest-packages)", () => {
+  it("un bloc packages valide est accepté", () => {
+    expect(OgygieManifestSchema.safeParse(manifestWithPackages([enginePackage])).success).toBe(true);
+  });
+
+  it("un manifeste SANS bloc packages reste valide (l'extension est invisible)", () => {
+    const withoutPackages = manifestWithPackages(undefined);
+    delete (withoutPackages as Record<string, unknown>)["packages"];
+    expect(OgygieManifestSchema.safeParse(withoutPackages).success).toBe(true);
+  });
+
+  it("une feature peut dépendre d'un package déclaré", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithPackages([enginePackage], [featureNamed("orders", ["package:gadget-engine"])]),
+    );
+    expect(parsed.success).toBe(true);
+  });
+
+  it("MUTATION : une dépendance vers un package INEXISTANT est refusée", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithPackages([enginePackage], [featureNamed("orders", ["package:fantome"])]),
+    );
+    expect(parsed.success).toBe(false);
+    const issue = parsed.success ? undefined : parsed.error.issues[0];
+    expect(issue?.message).toContain("matches no declared package");
+  });
+
+  it("MUTATION : un package portant le nom d'une feature est refusé", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithPackages([{ ...enginePackage, name: "orders" }], [featureNamed("orders")]),
+    );
+    expect(parsed.success).toBe(false);
+    const messages = parsed.success ? [] : parsed.error.issues.map((issue) => issue.message);
+    expect(messages.join(" ")).toContain("already the name of a feature");
+  });
+
+  it("MUTATION : un package déclaré deux fois est refusé", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithPackages([enginePackage, { ...enginePackage, path: "packages/autre" }]),
+    );
+    expect(parsed.success).toBe(false);
+  });
+
+  it("MUTATION : un package ne dépend PAS d'une feature (forme package:<nom> exigée)", () => {
+    const parsed = OgygieManifestSchema.safeParse(
+      manifestWithPackages([{ ...enginePackage, dependsOn: ["orders"] }], [featureNamed("orders")]),
+    );
+    expect(parsed.success).toBe(false);
+  });
+});

package/src/manifest.schema.ts

@@ -10,6 +10,30 @@ export const FeatureNameSchema = z
   .string()
   .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "kebab-case required");
 
+/**
+ * A dependency on a PRODUCT package, written `package:<name>` so it can never
+ * be confused with a feature name. The prefix is the whole point: two tiroirs
+ * of the map, one syntax each, and no guessing about what a bare name means.
+ */
+export const PackageDependencySchema = z
+  .string()
+  .regex(/^package:[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "expected package:<kebab-case-name>");
+
+/**
+ * A package of the PRODUCT: code that does not run and belongs to no app — a
+ * pure library, a portable engine, a computation without I/O. It answers the
+ * same questions as a feature, minus the ones that make no sense outside an
+ * app: no routes, no tables, no owning app.
+ *
+ * Without this, such code had nowhere to be declared, and the spec describing
+ * it could never say `implemented` — the gate rightly refuses a spec the map
+ * does not confirm, and the map had no way to confirm it (spec
+ * manifest-packages).
+ *
+ * Not to be confused with `framework.packages`, which describes what a
+ * FRAMEWORK repo publishes on npm. This block describes what a product keeps
+ * for itself.
+ */
 export const HttpRouteSchema = z.object({
   method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
   path: z.string().startsWith("/api/"),
@@ -67,8 +91,10 @@ export const FeatureManifestSchema = z.object({
       "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"),
+    .array(z.union([FeatureNameSchema, PackageDependencySchema]))
+    .describe(
+      "Features imported through their index.ts, and product packages as package:<name> — nothing else",
+    ),
   status: z.enum(["skeleton", "in-progress", "delivered"]),
 });
 
@@ -145,6 +171,18 @@ export const ProductVocabularySchema = z.object({
 });
 export type ProductVocabulary = z.infer<typeof ProductVocabularySchema>;
 
+export const PackageManifestSchema = z.object({
+  name: FeatureNameSchema,
+  path: z.string().describe("Folder relative to the repo root, e.g. packages/solver"),
+  intent: z.string().min(20).max(300).describe("The package's 'why' in 1-3 sentences"),
+  spec: z.string().nullable(),
+  dependsOn: z
+    .array(PackageDependencySchema)
+    .describe("Other PRODUCT packages, as package:<name> — never a feature: a package that depended on one would live under an app, and would be a feature"),
+  status: z.enum(["skeleton", "in-progress", "delivered"]),
+});
+export type PackageManifest = z.infer<typeof PackageManifestSchema>;
+
 export const OgygieManifestSchema = z.object({
   version: z.literal(1),
   product: z.object({
@@ -175,6 +213,10 @@ export const OgygieManifestSchema = z.object({
     }),
   ),
   features: z.array(FeatureManifestSchema),
+  packages: z
+    .array(PackageManifestSchema)
+    .optional()
+    .describe("Product code living outside every app — libraries, engines. Absent = the project has none"),
   vocabulary: ProductVocabularySchema.optional().describe(
     "The product's closed vocabulary — declared here, enforced by `ogygie verify-vocabulary`. Absent = gate silent",
   ),
@@ -190,6 +232,54 @@ export const OgygieManifestSchema = z.object({
   // front CONSUMES contracts, the gateway RELAYS declared routes; neither
   // OWNS any).
   .superRefine((manifest, context) => {
+    // One name, one thing in the map (spec manifest-packages B1): a package
+    // sharing a feature's name would make `dependsOn` ambiguous — and worse,
+    // silently so, since both would resolve.
+    const featureNames = new Set(manifest.features.map((feature) => feature.name));
+    const packageNames = new Set<string>();
+    (manifest.packages ?? []).forEach((packageEntry, index) => {
+      if (featureNames.has(packageEntry.name)) {
+        context.addIssue({
+          code: "custom",
+          path: ["packages", index, "name"],
+          message: `"${packageEntry.name}" is already the name of a feature — one name designates one thing`,
+        });
+      }
+      if (packageNames.has(packageEntry.name)) {
+        context.addIssue({
+          code: "custom",
+          path: ["packages", index, "name"],
+          message: `package "${packageEntry.name}" is declared twice`,
+        });
+      }
+      packageNames.add(packageEntry.name);
+    });
+
+    // Every `package:<name>` must designate a DECLARED package, wherever it is
+    // written: a dangling dependency describes a map nobody can follow.
+    const checkPackageDependencies = (
+      dependsOn: readonly string[],
+      path: (string | number)[],
+    ): void => {
+      dependsOn.forEach((dependency, dependencyIndex) => {
+        if (!dependency.startsWith("package:")) return;
+        const target = dependency.slice("package:".length);
+        if (!packageNames.has(target)) {
+          context.addIssue({
+            code: "custom",
+            path: [...path, dependencyIndex],
+            message: `dependency "${dependency}" matches no declared package`,
+          });
+        }
+      });
+    };
+    manifest.features.forEach((feature, index) => {
+      checkPackageDependencies(feature.dependsOn, ["features", index, "dependsOn"]);
+    });
+    (manifest.packages ?? []).forEach((packageEntry, index) => {
+      checkPackageDependencies(packageEntry.dependsOn, ["packages", index, "dependsOn"]);
+    });
+
     // 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,