@ogygie/core 0.8.0 → 0.10.0

package/src/impact.ts

@@ -0,0 +1,366 @@
+/**
+ * @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;
+      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)],
+    },
+  };
+  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): string[] {
+  const limits = [
+    "code that no manifest entry declares — the map is the only chart",
+    "anything outside this repo: no network, no npm registry",
+  ];
+  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>) {
@@ -77,3 +77,168 @@ describe("findSpecOwner — feature ou package, la carte confirme les deux", ()
     expect(findSpecOwner(manifestWith({}), "gadget-engine")).toBeUndefined();
   });
 });
+
+/**
+ * The nature added the day a framework spec could not be confirmed. The
+ * mutation these tests guard is the one that was there for months: the lookup
+ * IGNORING a nature the map declares, and answering "no owner" instead of
+ * "this owner, not delivered yet".
+ */
+const frameworkWith = (packages: unknown[]) => ({
+  framework: {
+    packages,
+    templates: { project: "templates/project", feature: "templates/feature" },
+    governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+  },
+});
+
+const mcpPackage = {
+  name: "@acme/mcp",
+  path: "packages/acme-mcp",
+  intent: "Serveur du protocole, publié à part parce qu'il porte sa propre dépendance.",
+  spec: "specs/acme-mcp.spec.md",
+  status: "delivered",
+};
+
+describe("findSpecOwner — le package d'un framework confirme aussi", () => {
+  it("ÉTANT DONNÉ une spec décrite par un package du framework ALORS la carte le confirme", () => {
+    const owner = findSpecOwner(manifestWith(frameworkWith([mcpPackage])), "acme-mcp");
+    expect(owner).toEqual({
+      kind: "framework-package",
+      name: "@acme/mcp",
+      status: "delivered",
+      folder: "packages/acme-mcp",
+    });
+  });
+
+  it("l'appariement se fait par le champ `spec`, JAMAIS par le nom npm publié", () => {
+    // The mutation this kills: matching `candidate.name === specId`, which
+    // silently finds nothing — "@acme/mcp" is not "acme-mcp".
+    expect(findSpecOwner(manifestWith(frameworkWith([mcpPackage])), "@acme/mcp")).toBeUndefined();
+    expect(findSpecOwner(manifestWith(frameworkWith([mcpPackage])), "acme-mcp")?.name).toBe(
+      "@acme/mcp",
+    );
+  });
+
+  it("une spec portée par PLUSIEURS packages vaut le MOINS avancé d'entre eux", () => {
+    const owner = findSpecOwner(
+      manifestWith(
+        frameworkWith([
+          { ...mcpPackage, name: "@acme/core", path: "packages/acme-core" },
+          { ...mcpPackage, name: "@acme/cli", path: "packages/acme-cli", status: "in-progress" },
+        ]),
+      ),
+      "acme-mcp",
+    );
+    expect(owner?.status).toBe("in-progress");
+    expect(owner?.name).toBe("@acme/cli");
+  });
+
+  // The "a feature and a framework package claim the same spec" case is not
+  // tested here: the manifest schema refuses it upstream (see
+  // manifest.schema.test.ts), so it cannot reach this lookup.
+  it("un package du framework SANS spec ne possède rien", () => {
+    expect(
+      findSpecOwner(manifestWith(frameworkWith([{ ...mcpPackage, spec: null }])), "acme-mcp"),
+    ).toBeUndefined();
+  });
+
+});
+
+/**
+ * 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" },
+    ]);
+  });
+
+  it("un manifeste minimal rend une liste VIDE — jamais une exception", () => {
+    expect(declaredEntries(withApps({}))).toEqual([]);
+  });
+});