@ogygie/core 0.9.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/core",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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",
@@ -20,6 +20,7 @@
     "./web-lint": "./src/web-lint.ts",
     "./bundle-budget": "./src/bundle-budget.ts",
     "./spec": "./src/spec.schema.ts",
+    "./impact": "./src/impact.ts",
     "./repo-adapter": "./src/repo-adapter.ts",
     "./decision-refs": "./src/decision-refs.ts",
     "./design-brief": "./src/design-brief.ts",

package/src/impact.test.ts

@@ -0,0 +1,276 @@
+/**
+ * @intent Proves specs/impact-analyzer-core.spec.md on an in-memory repo — the
+ * tests the script NEVER had, though it is the first command of the evolution
+ * protocol.
+ *
+ * Two families here. The four findings it already produced, each with the
+ * mutation that would silence it. And the four blind spots it had, each with
+ * the case that fails against yesterday's version: a dependent under another
+ * app, a dependent that is a package, an import by package specifier, and a
+ * report that does not say what it looked at (D12).
+ */
+import { describe, expect, it } from "vitest";
+import { OgygieFailure } from "./error.schema.js";
+import { analyzeImpact, type ImpactReport } from "./impact.js";
+import { OgygieManifestSchema } from "./manifest.schema.js";
+import { createInMemoryRepoAdapter } from "./repo-adapter.js";
+
+const MANIFEST = {
+  version: 1,
+  product: { name: "acme", description: "SaaS générique servant de fixture aux tests d'impact." },
+  apps: [
+    { name: "api", path: "apps/api", type: "api", entryPoint: "apps/api/src/server.ts" },
+    { name: "web", path: "apps/web", type: "front", entryPoint: "apps/web/src/main.tsx" },
+  ],
+  features: [
+    {
+      name: "orders",
+      intent: "Feature cible : elle possède la table orders et expose une route.",
+      folder: "src/features/orders",
+      spec: "specs/orders.spec.md",
+      routes: [
+        { method: "POST", path: "/api/orders", description: "Crée une commande.", schemaInput: "CreateOrderInputSchema", schemaOutput: "CreateOrderOutputSchema" },
+      ],
+      dbTables: ["orders"],
+      dependsOn: [],
+      status: "delivered",
+    },
+    {
+      name: "invoices",
+      intent: "Feature d'API dépendante : elle importe orders par son index.",
+      folder: "src/features/invoices",
+      spec: "specs/invoices.spec.md",
+      routes: [],
+      dbTables: [],
+      dependsOn: ["orders"],
+      status: "delivered",
+    },
+    {
+      name: "orders-screen",
+      intent: "Feature FRONT : elle importe le contrat d'orders par specifier de package.",
+      app: "web",
+      folder: "src/features/orders-screen",
+      spec: "specs/orders-screen.spec.md",
+      routes: [],
+      dbTables: [],
+      dependsOn: ["orders"],
+      status: "delivered",
+    },
+  ],
+  conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+};
+
+const FILES: Record<string, string> = {
+  "apps/api/src/features/orders/index.ts": "export { createOrder } from './service.js';\n",
+  "apps/api/src/features/orders/service.ts": "export function createOrder() { return 1; }\n",
+  "apps/api/src/features/invoices/service.ts":
+    'import { createOrder } from "../orders/index.js";\nexport const a = createOrder;\n',
+  "apps/web/src/features/orders-screen/queries.ts":
+    'import { ListOrdersOutputSchema } from "@acme/api/features/orders/schemas";\nexport const s = ListOrdersOutputSchema;\n',
+};
+
+function manifestOf(overrides: Record<string, unknown> = {}) {
+  return OgygieManifestSchema.parse({ ...MANIFEST, ...overrides });
+}
+
+async function analyze(
+  files: Record<string, string> = FILES,
+  target = "orders",
+  manifest = manifestOf(),
+): Promise<ImpactReport> {
+  return analyzeImpact({ manifest, adapter: createInMemoryRepoAdapter(files) }, target);
+}
+
+const codesOf = (report: ImpactReport): string[] =>
+  report.findings.map((finding) => finding.code).sort();
+
+describe("B2/B3 — les angles morts d'hier", () => {
+  it("ÉTANT DONNÉ une feature FRONT qui importe le contrat d'une feature d'API ALORS elle est un dépendant", async () => {
+    // Yesterday's version joined every folder to the api app AND only knew
+    // relative imports: this dependent was invisible twice.
+    const report = await analyze();
+    expect(report.dependents.map((dependent) => dependent.name).sort()).toEqual([
+      "invoices",
+      "orders-screen",
+    ]);
+  });
+
+  it("les symboles importés remontent, quelle que soit la forme de l'import", async () => {
+    const report = await analyze();
+    const front = report.dependents.find((dependent) => dependent.name === "orders-screen");
+    expect(front?.importedSymbols).toEqual(["ListOrdersOutputSchema"]);
+  });
+
+  it("ÉTANT DONNÉ un repo SANS app de type api ALORS l'analyse tourne quand même", async () => {
+    // The version of yesterday threw "no app of type api in the manifest" and
+    // analysed nothing at all.
+    const manifest = manifestOf({
+      apps: [{ name: "web", path: "apps/web", type: "front", entryPoint: "apps/web/src/main.tsx" }],
+      features: [MANIFEST.features[2]],
+    });
+    const report = await analyze(FILES, "orders-screen", manifest);
+    expect(report.target.folder).toBe("apps/web/src/features/orders-screen");
+  });
+
+  it("un PACKAGE est une cible comme une autre, et ses dépendants se voient", async () => {
+    const manifest = manifestOf({
+      packages: [
+        {
+          name: "solver",
+          path: "packages/solver",
+          intent: "Package produit servant de fixture : importé par une feature d'API.",
+          spec: "specs/solver.spec.md",
+          dependsOn: [],
+          status: "delivered",
+        },
+      ],
+    });
+    const files = {
+      ...FILES,
+      "packages/solver/index.ts": "export const solve = () => 1;\n",
+      "apps/api/src/features/orders/service.ts":
+        'import { solve } from "solver";\nexport function createOrder() { return solve(); }\n',
+    };
+    const report = await analyze(files, "solver", manifest);
+    expect(report.dependents.map((dependent) => dependent.name)).toEqual(["orders"]);
+  });
+});
+
+describe("B4 — le rapport dit ce qu'il a regardé (D12)", () => {
+  it("le périmètre nomme les dossiers scannés et les natures couvertes", async () => {
+    const report = await analyze();
+    expect(report.scope.scannedFolders).toContain("apps/web/src/features/orders-screen");
+    expect(report.scope.coveredKinds).toContain("feature");
+  });
+
+  it("MUTATION : un PACKAGE sans dépendant interne dit que ses consommateurs EXTERNES sont hors de portée", async () => {
+    // "Aucun dépendant" tout court est le mensonge que D12 interdit.
+    const manifest = manifestOf({
+      packages: [
+        {
+          name: "solver",
+          path: "packages/solver",
+          intent: "Package produit servant de fixture : personne ne l'importe dans ce dépôt.",
+          spec: "specs/solver.spec.md",
+          dependsOn: [],
+          status: "delivered",
+        },
+      ],
+    });
+    const report = await analyze({ ...FILES, "packages/solver/index.ts": "export const a = 1;\n" }, "solver", manifest);
+    expect(report.dependents).toEqual([]);
+    expect(report.scope.outOfReach.join(" ")).toContain("OUTSIDE this repo");
+  });
+
+  it("une entrée dont la carte ne résout pas le dossier est NOMMÉE, l'analyse continue", async () => {
+    const manifest = manifestOf({
+      apps: [{ name: "web", path: "apps/web", type: "front", entryPoint: "apps/web/src/main.tsx" }],
+    });
+    const report = await analyze(FILES, "orders-screen", manifest);
+    // orders and invoices count on an api app that no longer exists: they are
+    // NAMED, and the analysis still returns a report instead of throwing.
+    expect(report.scope.outOfReach.join(" ")).toContain('"orders"');
+    expect(report.scope.outOfReach.join(" ")).toContain('"invoices"');
+    expect(report.target.folder).toBe("apps/web/src/features/orders-screen");
+  });
+});
+
+describe("B5 — les quatre findings, chacun avec sa mutation", () => {
+  it("aucun finding sur un repo conforme", async () => {
+    expect(await analyze().then(codesOf)).toEqual([]);
+  });
+
+  it("FEATURE_BOUNDARY_VIOLATION : importer un fichier INTERNE au lieu de l'index", async () => {
+    const files = {
+      ...FILES,
+      "apps/api/src/features/invoices/service.ts":
+        'import { createOrder } from "../orders/service.js";\nexport const a = createOrder;\n',
+    };
+    const report = await analyze(files);
+    expect(codesOf(report)).toContain("FEATURE_BOUNDARY_VIOLATION");
+    expect(report.dependents.find((d) => d.name === "invoices")?.viaIndexOnly).toBe(false);
+  });
+
+  it("MANIFEST_DEPENDENCY_STALE : un dependsOn que le code ne justifie plus", async () => {
+    const files = { ...FILES, "apps/api/src/features/invoices/service.ts": "export const a = 1;\n" };
+    expect(codesOf(await analyze(files))).toContain("MANIFEST_DEPENDENCY_STALE");
+  });
+
+  it("MANIFEST_DEPENDENCY_UNDECLARED : un import que le manifeste tait", async () => {
+    const manifest = manifestOf({
+      features: MANIFEST.features.map((feature) =>
+        feature.name === "invoices" ? { ...feature, dependsOn: [] } : feature,
+      ),
+    });
+    expect(codesOf(await analyze(FILES, "orders", manifest))).toContain(
+      "MANIFEST_DEPENDENCY_UNDECLARED",
+    );
+  });
+
+  it("TABLE_REFERENCED_OUTSIDE_OWNER : une table touchée hors de son propriétaire", async () => {
+    const files = {
+      ...FILES,
+      "apps/api/src/features/invoices/repository.ts": 'export const t = "orders";\n',
+    };
+    const report = await analyze(files);
+    expect(codesOf(report)).toContain("TABLE_REFERENCED_OUTSIDE_OWNER");
+    expect(report.tableReadersOutsideOwner[0]?.feature).toBe("invoices");
+  });
+
+  it("MUTATION : le nom d'une table dans une feature FRONT ne compte pas — elle ne parle pas à la base", async () => {
+    // Found on a real repo: widening the scan to other apps turned every
+    // `queryKey: ["orders", "list"]` into a boundary violation — fifteen in one
+    // report. A front feature holds no database client; the string is a query
+    // key or a route, and a rule applied where its premise does not hold makes
+    // noise, which is how a report stops being read.
+    const files = {
+      ...FILES,
+      "apps/web/src/features/orders-screen/queries.ts":
+        'import { ListOrdersOutputSchema } from "@acme/api/features/orders/schemas";\nexport const key = ["orders", "list"];\nexport const s = ListOrdersOutputSchema;\n',
+    };
+    const report = await analyze(files);
+    expect(codesOf(report)).not.toContain("TABLE_REFERENCED_OUTSIDE_OWNER");
+    // …et la dérogation se DIT, elle ne s'applique pas en silence (D12).
+    expect(report.scope.outOfReach.join(" ")).toContain("front/gateway");
+  });
+
+  it("une feature d'API touchant la table d'une autre reste signalée — la règle garde sa portée", async () => {
+    const files = {
+      ...FILES,
+      "apps/api/src/features/invoices/repository.ts": 'export const t = "orders";\n',
+    };
+    expect(codesOf(await analyze(files))).toContain("TABLE_REFERENCED_OUTSIDE_OWNER");
+  });
+
+  it("MUTATION : la même table dans un TEST ne compte pas — c'est le patron de fixture", async () => {
+    const files = {
+      ...FILES,
+      "apps/api/src/features/invoices/service.test.ts": 'const t = "orders";\nexport default t;\n',
+    };
+    expect(codesOf(await analyze(files))).not.toContain("TABLE_REFERENCED_OUTSIDE_OWNER");
+  });
+});
+
+describe("B5 — la commande de test couvre TOUS les dépendants", () => {
+  it("elle nomme les dossiers réels, de toutes les apps", async () => {
+    const report = await analyze();
+    // Yesterday it prefixed everything with `features/`, so a front dependent
+    // was named by a path that runs nothing.
+    expect(report.testCommand).toContain("apps/api/src/features/orders");
+    expect(report.testCommand).toContain("apps/web/src/features/orders-screen");
+  });
+});
+
+describe("refus", () => {
+  it("MUTATION : une cible inconnue est refusée AVEC la liste de ce que la carte déclare", async () => {
+    try {
+      await analyze(FILES, "jamais-declaree");
+      expect.unreachable("l'analyse aurait dû être refusée");
+    } catch (thrown) {
+      expect(thrown).toBeInstanceOf(OgygieFailure);
+      const failure = thrown as OgygieFailure;
+      expect(failure.error.code).toBe("IMPACT_UNKNOWN_FEATURE");
+      expect(failure.error.suggestedFix).toContain("orders-screen");
+    }
+  });
+});

package/src/impact.ts

@@ -0,0 +1,384 @@
+/**
+ * @intent The blast radius of a change, as a FUNCTION (spec
+ * impact-analyzer-core). `pnpm ogygie:impact <target>` is the first command of
+ * the evolution protocol — the one run before touching delivered code — so
+ * what it says has to be true, and what it cannot see has to be said (D12).
+ *
+ * The judgement lives here, in the core: it reads through a `RepoAdapter`
+ * (D10), so a test attacks it with an in-memory repo and the MCP server can
+ * call it on a repo it serves. The governed script keeps the collecting half.
+ *
+ * Deliberate limits, all declared in the report's `scope`:
+ * - textual import reading, no TypeScript compiler — same trade as
+ *   `module-purity`, and the same one the analyzer already made;
+ * - depth 1: direct dependents only. Transitivity is read by re-running;
+ * - nothing outside the map, and nothing outside the repo.
+ */
+import { z } from "zod";
+import {
+  OgygieErrorSchema,
+  ogygieError,
+  throwOgygieError,
+  type OgygieError,
+} from "./error.schema.js";
+import { declaredEntries, type MapEntry } from "./manifest-owners.js";
+import type { OgygieManifest } from "./manifest.schema.js";
+import { parseModuleImports } from "./module-purity.js";
+import type { RepoAdapter } from "./repo-adapter.js";
+import { dbTableNamesOf } from "./shared-tables.js";
+
+export const MapEntryKindSchema = z.enum(["feature", "package", "framework-package"]);
+
+/**
+ * What the analysis really covered, and what it cannot reach (D12). A vacant
+ * `dependents` means nothing without it: "none" and "I did not look there"
+ * read the same.
+ */
+export const ImpactScopeSchema = z.object({
+  scannedFolders: z.array(z.string()),
+  coveredKinds: z.array(MapEntryKindSchema),
+  outOfReach: z.array(z.string()),
+});
+
+export const ImpactReportSchema = z.object({
+  target: z.object({
+    name: z.string(),
+    kind: MapEntryKindSchema,
+    folder: z.string(),
+  }),
+  dependents: z.array(
+    z.object({
+      name: z.string(),
+      kind: MapEntryKindSchema,
+      importedSymbols: z.array(z.string()),
+      viaIndexOnly: z.boolean(),
+    }),
+  ),
+  routes: z.array(
+    z.object({ method: z.string(), path: z.string(), description: z.string() }),
+  ),
+  ownedTables: z.array(z.string()),
+  tableReadersOutsideOwner: z.array(
+    z.object({ table: z.string(), feature: z.string(), file: z.string() }),
+  ),
+  findings: z.array(OgygieErrorSchema),
+  testCommand: z.string(),
+  scope: ImpactScopeSchema,
+});
+export type ImpactReport = z.infer<typeof ImpactReportSchema>;
+
+export interface AnalyzeImpactDeps {
+  manifest: OgygieManifest;
+  /** The repo, read-only (D10): no path, no fs, no cwd. */
+  adapter: RepoAdapter;
+}
+
+const SOURCE_EXTENSIONS = [".ts", ".tsx"];
+
+function isSource(path: string): boolean {
+  return SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension));
+}
+
+function isTest(path: string): boolean {
+  return /\.test\.tsx?$/.test(path);
+}
+
+/** Named/default/namespace symbols of one import clause ("type" stripped). */
+export function symbolsOfImportClause(clause: string): string[] {
+  const symbols: string[] = [];
+  const braces = /\{([^}]*)\}/.exec(clause);
+  if (braces?.[1] !== undefined) {
+    for (const rawEntry of braces[1].split(",")) {
+      const name = rawEntry.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
+      if (name !== undefined && name !== "") symbols.push(name);
+    }
+  }
+  const outsideBraces = clause.replace(/\{[^}]*\}/, "").replace(/^type\s+/, "").trim();
+  if (/\*\s*as\s+/.test(outsideBraces)) symbols.push("*");
+  else if (outsideBraces.replace(/,/g, "").trim() !== "") symbols.push("default");
+  return symbols;
+}
+
+/**
+ * Every way a module can name the target, derived from the MAP — never
+ * guessed. Two families, because a repo has two:
+ * - the relative path between two features of the same app (`../orders/…`),
+ *   the only one the analyzer used to know;
+ * - the package specifier, which is how a front imports an API contract
+ *   (`@product/api/features/orders/schemas`) and how anything imports a
+ *   package. Missing it made every front dependent invisible.
+ */
+function specifiersMatching(target: MapEntry, source: string): boolean {
+  const folder = target.folder;
+  if (folder === null) return false;
+  const directory = folder.split("/").pop() ?? folder;
+  if (new RegExp(`(^|/)\\.\\./${directory}/`).test(source)) return true;
+  if (source.startsWith(`../${directory}/`) || source === `../${directory}`) return true;
+  // Package specifier: the target's name, or its folder segment, as a path
+  // segment of the specifier — `@acme/api/features/orders/schemas` names
+  // `orders`, `@acme/solver` names `solver`.
+  if (source === target.name || source.startsWith(`${target.name}/`)) return true;
+  const segments = source.split("/");
+  return segments.includes(directory) && !source.startsWith(".");
+}
+
+/**
+ * Whether an import pierces the target's public door — and it is only ever
+ * ASKED of a relative import between neighbours.
+ *
+ * The rule it serves ("a feature imports another only through its index.ts")
+ * governs siblings inside one app. A front importing an API contract —
+ * `@product/api/features/orders/schemas`, the canonical rail of the stack —
+ * names a file that is NOT an index and is not a violation for it: that path
+ * is precisely what AGENTS.md prescribes. Judging it by the same measure would
+ * flag every front screen in every project.
+ */
+function piercesTheIndex(specifier: string): boolean {
+  if (!specifier.startsWith(".")) return false;
+  return !/(^|\/)index(\.js)?$/.test(specifier);
+}
+
+interface DependentAccumulator {
+  kind: MapEntry["kind"];
+  importedSymbols: Set<string>;
+  viaIndexOnly: boolean;
+}
+
+/**
+ * The blast radius of `targetName`: who depends on it, which of its symbols
+ * they use, which tables it owns and who else touches them, plus the exact
+ * test command to keep every dependent green.
+ */
+export async function analyzeImpact(
+  deps: AnalyzeImpactDeps,
+  targetName: string,
+): Promise<ImpactReport> {
+  const entries = declaredEntries(deps.manifest);
+  const target = entries.find((entry) => entry.name === targetName);
+  if (target === undefined) {
+    // The code stays IMPACT_UNKNOWN_FEATURE although a target may now be a
+    // package: it is the code projects already know, and renaming it would
+    // restrict a contract for nothing. What changes is the list offered —
+    // every nature the map declares, not only the features.
+    return throwOgygieError({
+      code: "IMPACT_UNKNOWN_FEATURE",
+      message: `"${targetName}" is unknown to the manifest.`,
+      file: "ogygie.manifest.json",
+      cause: `no entry of the map is named "${targetName}"`,
+      suggestedFix: `Pick one of: ${entries.map((entry) => entry.name).join(", ") || "<the map declares nothing>"}.`,
+    });
+  }
+  return buildReport(deps, entries, target);
+}
+
+/** Kept apart so the refusal above stays a one-liner and the report a whole. */
+async function buildReport(
+  deps: AnalyzeImpactDeps,
+  entries: MapEntry[],
+  target: MapEntry,
+): Promise<ImpactReport> {
+  const findings: OgygieError[] = [];
+  const scannedFolders: string[] = [];
+  const outOfReach: string[] = [];
+
+  if (target.folder === null) {
+    outOfReach.push(
+      `the target "${target.name}" has no folder the map can resolve — its app is not declared`,
+    );
+  }
+
+  const dependents = new Map<string, DependentAccumulator>();
+  const tableReadersOutsideOwner: ImpactReport["tableReadersOutsideOwner"] = [];
+  const ownedTables = target.kind === "feature" ? tablesOf(deps.manifest, target.name) : [];
+
+  for (const entry of entries) {
+    if (entry.name === target.name) continue;
+    if (entry.folder === null) {
+      outOfReach.push(
+        `"${entry.name}" (${entry.kind}) — the map declares no resolvable folder for it`,
+      );
+      continue;
+    }
+    const files = (await deps.adapter.listDirectory(entry.folder)).filter((file) =>
+      isSource(file.path),
+    );
+    if (files.length > 0) scannedFolders.push(entry.folder);
+
+    for (const file of files) {
+      const filePath = `${entry.folder}/${file.path}`;
+      const content = await deps.adapter.readFile(filePath);
+
+      for (const imported of parseModuleImports(content)) {
+        if (!specifiersMatching(target, imported.specifier)) continue;
+        const accumulator = dependents.get(entry.name) ?? {
+          kind: entry.kind,
+          importedSymbols: new Set<string>(),
+          viaIndexOnly: true,
+        };
+        for (const symbol of symbolsOfImportClause(clauseOf(imported.statement))) {
+          accumulator.importedSymbols.add(symbol);
+        }
+        if (piercesTheIndex(imported.specifier)) {
+          accumulator.viaIndexOnly = false;
+          findings.push(
+            ogygieError({
+              code: "FEATURE_BOUNDARY_VIOLATION",
+              message: `"${entry.name}" imports an internal file of "${target.name}" instead of its index.ts.`,
+              file: filePath,
+              cause: `import from "${imported.specifier}" bypasses the public index of ${target.name}`,
+              suggestedFix: `Export the needed symbols from the index of ${target.name} and import them from there.`,
+            }),
+          );
+        }
+        dependents.set(entry.name, accumulator);
+      }
+
+      // A table belongs to ONE feature. Tests are exempt: populating another
+      // feature's table as a fixture is the canonical bench pattern, and
+      // flagging it would make every run red.
+      if (isTest(file.path)) continue;
+      // So is anything that cannot touch a database. A front feature consumes
+      // contracts and a gateway relays — neither holds Drizzle — so the string
+      // a table name in their code is a query key or a route, not a table. Found
+      // on a real repo: widening the scan to other apps turned every
+      // `queryKey: ["orders", "list"]` into a boundary violation (15 of them in
+      // one report). A rule applied where its premise does not hold produces
+      // noise, and noise is how a report stops being read.
+      if (entry.appType === "front" || entry.appType === "gateway") continue;
+      for (const table of ownedTables) {
+        if (!content.includes(`"${table}"`)) continue;
+        tableReadersOutsideOwner.push({ table, feature: entry.name, file: filePath });
+        findings.push(
+          ogygieError({
+            code: "TABLE_REFERENCED_OUTSIDE_OWNER",
+            message: `Table "${table}" is owned by "${target.name}" but referenced by production code of "${entry.name}".`,
+            file: filePath,
+            cause: `"${table}" found in a non-test file outside its owner`,
+            suggestedFix: `Go through the public contracts of ${target.name} instead of touching the table — one table, one owner.`,
+          }),
+        );
+      }
+    }
+  }
+
+  findings.push(...manifestDependencyFindings(deps.manifest, target, dependents));
+
+  const feature = deps.manifest.features.find((candidate) => candidate.name === target.name);
+  const report = {
+    target: { name: target.name, kind: target.kind, folder: target.folder ?? "" },
+    dependents: [...dependents.entries()]
+      .map(([name, accumulator]) => ({
+        name,
+        kind: accumulator.kind,
+        importedSymbols: [...accumulator.importedSymbols].sort(),
+        viaIndexOnly: accumulator.viaIndexOnly,
+      }))
+      .sort((left, right) => (left.name < right.name ? -1 : 1)),
+    routes: (feature?.routes ?? []).map((route) => ({
+      method: route.method,
+      path: route.path,
+      description: route.description,
+    })),
+    ownedTables,
+    tableReadersOutsideOwner,
+    findings,
+    testCommand: testCommandFor(target, [...dependents.keys()], entries),
+    scope: {
+      scannedFolders: scannedFolders.sort(),
+      coveredKinds: [...new Set(entries.map((entry) => entry.kind))],
+      outOfReach: [...outOfReach, ...outOfReachOf(target, entries)],
+    },
+  };
+  return ImpactReportSchema.parse(report);
+}
+
+/** The import clause of a statement, for the symbols it carries. */
+function clauseOf(statement: string): string {
+  const match = /\bimport\b([\s\S]*?)\bfrom\b/.exec(statement);
+  return match?.[1] ?? "";
+}
+
+function tablesOf(manifest: OgygieManifest, featureName: string): string[] {
+  const feature = manifest.features.find((candidate) => candidate.name === featureName);
+  return feature === undefined ? [] : dbTableNamesOf(feature);
+}
+
+/** What no analysis of this repo can reach, named rather than implied (D12). */
+function outOfReachOf(target: MapEntry, entries: readonly MapEntry[]): string[] {
+  const limits = [
+    "code that no manifest entry declares — the map is the only chart",
+    "anything outside this repo: no network, no npm registry",
+  ];
+  // Said rather than silently applied: a table rule that skips some folders
+  // has to name them, or its silence reads as "nothing found there".
+  const spared = entries.filter(
+    (entry) => entry.appType === "front" || entry.appType === "gateway",
+  );
+  if (spared.length > 0 && target.kind === "feature") {
+    limits.push(
+      `table ownership was NOT checked in ${spared.length} front/gateway entr${spared.length === 1 ? "y" : "ies"} — that code holds no database client, so a table name there is a query key or a route`,
+    );
+  }
+  if (target.kind === "framework-package" || target.kind === "package") {
+    limits.unshift(
+      `consumers of "${target.name}" OUTSIDE this repo — it is a package, and a published package is imported by projects this analysis cannot see`,
+    );
+  }
+  return limits;
+}
+
+/** The map must not lie by omission, in either direction. */
+function manifestDependencyFindings(
+  manifest: OgygieManifest,
+  target: MapEntry,
+  dependents: Map<string, DependentAccumulator>,
+): OgygieError[] {
+  const findings: OgygieError[] = [];
+  const declared = manifest.features.filter((feature) =>
+    feature.dependsOn.includes(target.name),
+  );
+  for (const feature of declared) {
+    if (!dependents.has(feature.name)) {
+      findings.push(
+        ogygieError({
+          code: "MANIFEST_DEPENDENCY_STALE",
+          message: `Feature "${feature.name}" declares dependsOn "${target.name}" but never imports it.`,
+          file: `ogygie.manifest.json#features.${feature.name}`,
+          cause: `dependsOn contains "${target.name}", no import of it found in its code`,
+          suggestedFix:
+            "Remove the stale dependsOn entry, or make the dependency real through the entry's index.ts.",
+        }),
+      );
+    }
+  }
+  for (const [name, accumulator] of dependents) {
+    if (accumulator.kind !== "feature") continue;
+    if (declared.some((feature) => feature.name === name)) continue;
+    findings.push(
+      ogygieError({
+        code: "MANIFEST_DEPENDENCY_UNDECLARED",
+        message: `Feature "${name}" imports "${target.name}" but does not declare it in dependsOn.`,
+        file: `ogygie.manifest.json#features.${name}`,
+        cause: `imports of "${target.name}" found in its code, absent from its dependsOn`,
+        suggestedFix: `Add "${target.name}" to the dependsOn of "${name}" — the manifest must never lie by omission.`,
+      }),
+    );
+  }
+  return findings;
+}
+
+/**
+ * The command that keeps every dependent green. It names FOLDERS, not a
+ * `features/` prefix: dependents now come from several apps and from
+ * packages, and a prefix that only fits api features would run nothing.
+ */
+function testCommandFor(
+  target: MapEntry,
+  dependentNames: string[],
+  entries: MapEntry[],
+): string {
+  const folders = [target, ...entries.filter((entry) => dependentNames.includes(entry.name))]
+    .map((entry) => entry.folder)
+    .filter((folder): folder is string => folder !== null);
+  return ["pnpm test --", ...[...new Set(folders)].sort()].join(" ");
+}

package/src/manifest-owners.test.ts

@@ -5,7 +5,7 @@
  * confirm, and that neither shadows the other.
  */
 import { describe, expect, it } from "vitest";
-import { findSpecOwner } from "./manifest-owners.js";
+import { declaredEntries, findSpecOwner } from "./manifest-owners.js";
 import { OgygieManifestSchema } from "./manifest.schema.js";
 
 function manifestWith(extra: Record<string, unknown>) {
@@ -144,3 +144,109 @@ describe("findSpecOwner — le package d'un framework confirme aussi", () => {
   });
 
 });
+
+/**
+ * The list every tool of the framework reads. What these guard is the defect
+ * that made the impact analyzer blind: a folder resolved through ONE globally
+ * chosen app instead of the app that carries each entry.
+ */
+describe("declaredEntries — tout ce que la carte déclare, à un seul endroit", () => {
+  const front = {
+    name: "web-shell",
+    intent: "Feature front servant de fixture : elle vit sous l'app web, pas sous l'api.",
+    app: "web",
+    folder: "src/features/web-shell",
+    spec: "specs/web-shell.spec.md",
+    routes: [],
+    dbTables: [],
+    dependsOn: [],
+    status: "delivered",
+  };
+  const api = {
+    name: "orders",
+    intent: "Feature d'API servant de fixture aux tests du propriétaire de spec.",
+    folder: "src/features/orders",
+    spec: "specs/orders.spec.md",
+    routes: [],
+    dbTables: [],
+    dependsOn: [],
+    status: "delivered",
+  };
+  const withApps = (extra: Record<string, unknown>) =>
+    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" },
+        { name: "web", path: "apps/web", type: "front", entryPoint: "apps/web/src/main.tsx" },
+      ],
+      features: [],
+      conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+      ...extra,
+    });
+
+  it("ÉTANT DONNÉ des features sous DEUX apps ALORS chaque dossier passe par l'app qui la porte", () => {
+    // The mutation this kills: joining every folder to the api app, which
+    // sends the front feature's reader to apps/api/src/features/web-shell —
+    // a path that does not exist, so the feature looks empty instead of wrong.
+    const entries = declaredEntries(withApps({ features: [api, front] }));
+    expect(entries.map((entry) => entry.folder)).toEqual([
+      "apps/api/src/features/orders",
+      "apps/web/src/features/web-shell",
+    ]);
+  });
+
+  it("les TROIS natures entrent dans la liste, chacune avec sa spec", () => {
+    const entries = declaredEntries(
+      withApps({
+        features: [api],
+        packages: [
+          {
+            name: "solver",
+            path: "packages/solver",
+            intent: "Package produit servant de fixture aux tests de la carte.",
+            spec: "specs/solver.spec.md",
+            dependsOn: [],
+            status: "in-progress",
+          },
+        ],
+        ...frameworkWith([mcpPackage]),
+      }),
+    );
+    expect(entries.map((entry) => [entry.kind, entry.name, entry.specId])).toEqual([
+      ["feature", "orders", "orders"],
+      ["package", "solver", "solver"],
+      ["framework-package", "@acme/mcp", "acme-mcp"],
+    ]);
+  });
+
+  it("MUTATION : une feature dont l'app est INTROUVABLE garde un dossier null, sans faire tomber la liste", () => {
+    // Today the analyzer throws on this case and analyses NOTHING. The map
+    // says what it can, and names what it cannot — the rest is still usable.
+    const entries = declaredEntries(
+      OgygieManifestSchema.parse({
+        version: 1,
+        product: { name: "acme", description: "SaaS générique servant de fixture aux tests du manifeste." },
+        // No app of type api at all: the case of a framework repo.
+        apps: [{ name: "studio", path: "packages/studio", type: "front", entryPoint: "packages/studio/src/start.ts" }],
+        features: [api],
+        conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+      }),
+    );
+    expect(entries).toEqual([
+      {
+        kind: "feature",
+        name: "orders",
+        status: "delivered",
+        folder: null,
+        specId: "orders",
+        // No app carries it, so nothing can be said of what it may touch.
+        appType: null,
+      },
+    ]);
+  });
+
+  it("un manifeste minimal rend une liste VIDE — jamais une exception", () => {
+    expect(declaredEntries(withApps({}))).toEqual([]);
+  });
+});

package/src/manifest-owners.ts

@@ -52,57 +52,110 @@ export interface SpecOwner {
   folder: string | null;
 }
 
+/** One entry of the map, with everything a tool needs to go read its code. */
+export interface MapEntry extends SpecOwner {
+  /** The spec this entry owns, or null when it owns none. */
+  specId: string | null;
+  /**
+   * Type of the app carrying this entry — null for a package, which lives
+   * under no app.
+   *
+   * It answers a question no tool can guess from a folder: WHAT this code is
+   * allowed to touch. A front feature never speaks to the database (it
+   * consumes contracts), a gateway only relays — so a rule about database
+   * tables has no business examining either.
+   */
+  appType: "api" | "front" | "gateway" | 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.
+ * EVERYTHING the map declares, each entry with its folder already resolved
+ * through the app that carries it.
+ *
+ * One resolution for the whole framework. The spec-lifecycle gate and the
+ * impact analyzer used to resolve folders on their own, and the analyzer got
+ * it wrong in the way that does not show: it picked ONE app —
+ * `apps.find(app => app.type === "api")` — and joined every feature's folder
+ * to that one, so a front feature was looked for under the api app and never
+ * found. It also refused to run at all when no api app existed. The map
+ * already answered per entry, through `feature.app`, which the schema REQUIRES
+ * a front or gateway feature to declare.
+ *
+ * A fourth nature of entry is therefore added HERE, once, and every tool sees
+ * it (FAILURES.md 2026-08-25: a verifier that ignores a category cannot report
+ * it).
  */
-export function findSpecOwner(
-  manifest: OgygieManifest,
-  specId: string,
-): SpecOwner | undefined {
-  const feature = manifest.features.find((candidate) => candidate.name === specId);
-  if (feature !== undefined) {
+export function declaredEntries(manifest: OgygieManifest): MapEntry[] {
+  const entries: MapEntry[] = [];
+
+  for (const feature of manifest.features) {
+    // The app that CARRIES this feature — never a globally chosen one.
     const owningApp =
       feature.app === undefined
         ? manifest.apps.find((app) => app.type === "api")
         : manifest.apps.find((app) => app.name === feature.app);
-    return {
+    entries.push({
       kind: "feature",
       name: feature.name,
       status: feature.status,
       folder: owningApp === undefined ? null : `${owningApp.path}/${feature.folder}`,
-    };
+      specId: feature.name,
+      appType: owningApp?.type ?? null,
+    });
   }
 
-  const productPackage = (manifest.packages ?? []).find(
-    (candidate) => candidate.name === specId,
-  );
-  if (productPackage !== undefined) {
-    return {
+  for (const productPackage of manifest.packages ?? []) {
+    entries.push({
       kind: "package",
       name: productPackage.name,
       status: productPackage.status,
       folder: productPackage.path,
-    };
+      specId: productPackage.name,
+      appType: null,
+    });
   }
 
-  const frameworkPackages = (manifest.framework?.packages ?? []).filter(
-    (candidate) => candidate.spec !== null && specIdOf(candidate.spec) === specId,
-  );
-  const leastAdvanced = frameworkPackages
-    .slice()
-    .sort((a, b) => ADVANCEMENT.indexOf(a.status) - ADVANCEMENT.indexOf(b.status))[0];
-  if (leastAdvanced !== undefined) {
-    return {
+  for (const frameworkPackage of manifest.framework?.packages ?? []) {
+    entries.push({
       kind: "framework-package",
-      name: leastAdvanced.name,
-      status: leastAdvanced.status,
-      folder: leastAdvanced.path,
-    };
+      name: frameworkPackage.name,
+      status: frameworkPackage.status,
+      folder: frameworkPackage.path,
+      // A published npm name is not a spec id: the link is DECLARED.
+      specId: frameworkPackage.spec === null ? null : specIdOf(frameworkPackage.spec),
+      appType: null,
+    });
   }
 
-  return undefined;
+  return entries;
+}
+
+/**
+ * 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 owning = declaredEntries(manifest).filter((entry) => entry.specId === specId);
+  if (owning.length === 0) return undefined;
+  // Feature first: names are unique across the map (the schema refuses a
+  // package named like a feature), so the order decides which lookup runs
+  // first, never which answer is right. Among several framework packages
+  // pointing at the SAME spec — a framework spec often spans the core and the
+  // CLI — the LEAST advanced answers: a spec is delivered when all its code is.
+  const byPriority = owning.slice().sort((left, right) => {
+    if (left.kind !== right.kind) {
+      const order: SpecOwnerKind[] = ["feature", "package", "framework-package"];
+      return order.indexOf(left.kind) - order.indexOf(right.kind);
+    }
+    return ADVANCEMENT.indexOf(left.status) - ADVANCEMENT.indexOf(right.status);
+  });
+  const owner = byPriority[0];
+  if (owner === undefined) return undefined;
+  return { kind: owner.kind, name: owner.name, status: owner.status, folder: owner.folder };
 }
 
 /** What a refusal should suggest — both natures, never one that cannot exist. */