@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/__tests__/visual-tree-patterns.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "vitest";
+import { buildTarget, createRegistry, defineFeature } from "../index";
+import type { TreeChildrenSubscribe, TreeNode } from "../types/tree-node";
+
+// Stub-Provider für Tests. Form: (ctx) => (emit) => unsubscribe.
+// Emittet einmal initial, kein Cleanup nötig (no-op unsubscribe).
+function makeStubProvider(nodes: readonly TreeNode[]): TreeChildrenSubscribe {
+  return () => (emit) => {
+    emit(nodes);
+    return () => {};
+  };
+}
+
+describe("r.treeActions — registrar slot", () => {
+  test("feature without r.treeActions leaves the slot undefined", () => {
+    const feature = defineFeature("empty", () => {});
+    expect(feature.treeActions).toBeUndefined();
+  });
+
+  test("single r.treeActions call stores the map on the FeatureDefinition", () => {
+    const feature = defineFeature("text-content", (r) => {
+      r.treeActions({
+        edit: { args: { slug: "" as string } },
+        list: {},
+      });
+    });
+    expect(feature.treeActions).toEqual({
+      edit: { args: { slug: "" } },
+      list: {},
+    });
+  });
+
+  test("returns a typed handle carrying id + literal-typed treeActions", () => {
+    const feature = defineFeature("text-content", (r) => {
+      const handle = r.treeActions({
+        edit: { args: { slug: "" as string } },
+        list: {},
+      });
+      return { handle };
+    });
+    expect(feature.exports.handle.id).toBe("text-content");
+    expect(feature.exports.handle.treeActions).toEqual({
+      edit: { args: { slug: "" } },
+      list: {},
+    });
+  });
+
+  test("second r.treeActions call throws — only-once-guard", () => {
+    expect(() =>
+      defineFeature("dupe", (r) => {
+        r.treeActions({ edit: { args: { slug: "" as string } } });
+        r.treeActions({ list: {} });
+      }),
+    ).toThrow(/r\.treeActions\(\) already called/);
+  });
+
+  test("returned handle is frozen — cannot mutate id or actions after creation", () => {
+    const feature = defineFeature("text-content", (r) => {
+      const handle = r.treeActions({ list: {} });
+      return { handle };
+    });
+    expect(Object.isFrozen(feature.exports.handle)).toBe(true);
+  });
+});
+
+describe("r.tree — registrar slot", () => {
+  test("feature without r.tree leaves the slot undefined", () => {
+    const feature = defineFeature("empty", () => {});
+    expect(feature.treeProvider).toBeUndefined();
+  });
+
+  test("single r.tree call stores the provider function on the FeatureDefinition", () => {
+    const provider = makeStubProvider([{ label: "Marketing" }]);
+    const feature = defineFeature("text-content", (r) => {
+      r.tree(provider);
+    });
+    expect(feature.treeProvider).toBe(provider);
+  });
+
+  test("second r.tree call throws — only-once-guard", () => {
+    expect(() =>
+      defineFeature("dupe", (r) => {
+        r.tree(makeStubProvider([]));
+        r.tree(makeStubProvider([]));
+      }),
+    ).toThrow(/r\.tree\(\) already called/);
+  });
+
+  test("treeActions and tree are independent slots — can declare one without the other", () => {
+    const onlyActions = defineFeature("a", (r) => {
+      r.treeActions({ list: {} });
+    });
+    expect(onlyActions.treeActions).toBeDefined();
+    expect(onlyActions.treeProvider).toBeUndefined();
+
+    const onlyProvider = defineFeature("b", (r) => {
+      r.tree(makeStubProvider([]));
+    });
+    expect(onlyProvider.treeActions).toBeUndefined();
+    expect(onlyProvider.treeProvider).toBeDefined();
+  });
+});
+
+describe("Registry.getTreeProviders + getTreeActions", () => {
+  test("empty registry returns empty providers map and undefined actions", () => {
+    const reg = createRegistry([]);
+    expect(reg.getTreeProviders().size).toBe(0);
+    expect(reg.getTreeActions("nonexistent")).toBeUndefined();
+  });
+
+  test("aggregates providers from multiple features keyed by feature name", () => {
+    const providerA = makeStubProvider([{ label: "A-root" }]);
+    const providerB = makeStubProvider([{ label: "B-root" }]);
+    const featureA = defineFeature("text-content", (r) => {
+      r.tree(providerA);
+    });
+    const featureB = defineFeature("legal-pages", (r) => {
+      r.tree(providerB);
+    });
+    const reg = createRegistry([featureA, featureB]);
+
+    const providers = reg.getTreeProviders();
+    expect(providers.size).toBe(2);
+    expect(providers.get("text-content")).toBe(providerA);
+    expect(providers.get("legal-pages")).toBe(providerB);
+  });
+
+  test("features without r.tree are absent from the providers map (Zero-Whitelist-Filter)", () => {
+    const featureWithProvider = defineFeature("text-content", (r) => {
+      r.tree(makeStubProvider([]));
+    });
+    const featureWithoutProvider = defineFeature("schema-editor", () => {});
+    const reg = createRegistry([featureWithProvider, featureWithoutProvider]);
+
+    const providers = reg.getTreeProviders();
+    expect(providers.has("text-content")).toBe(true);
+    expect(providers.has("schema-editor")).toBe(false);
+  });
+
+  test("getTreeActions returns the erased map for a feature that declared r.treeActions", () => {
+    const feature = defineFeature("text-content", (r) => {
+      r.treeActions({
+        edit: { args: { slug: "" as string } },
+        list: {},
+      });
+    });
+    const reg = createRegistry([feature]);
+
+    expect(reg.getTreeActions("text-content")).toEqual({
+      edit: { args: { slug: "" } },
+      list: {},
+    });
+  });
+
+  test("getTreeActions returns undefined for a feature without r.treeActions", () => {
+    const feature = defineFeature("no-actions", (r) => {
+      r.tree(makeStubProvider([]));
+    });
+    const reg = createRegistry([feature]);
+
+    expect(reg.getTreeActions("no-actions")).toBeUndefined();
+  });
+});
+
+// =============================================================================
+// Schicht-1↔Schicht-2-Bridge: typed handle survives module-boundary.
+//
+// Diese Tests sind die kritische Architektur-Verification: r.treeActions
+// returnt einen typed Handle, der via setup-export durch FeatureDefinition
+// fließt und compile-time-typisiert vom Schicht-1-buildTarget konsumiert
+// wird. Ohne diese Tests würde ein Type-Drift in einer der zwei Schichten
+// erst in V.1.1 sichtbar — siehe advisor-Verdict + Memory `[EventDef-
+// Exports-Pattern]`.
+// =============================================================================
+
+describe("Schicht-1↔Schicht-2 Bridge — buildTarget against real defineFeature handle", () => {
+  test("buildTarget compiles + runs against handle from feature.exports", () => {
+    const textContent = defineFeature("text-content", (r) => {
+      const handle = r.treeActions({
+        edit: { args: { slug: "" as string } },
+        list: {},
+      });
+      return { handle };
+    });
+
+    // Der Beweis: dieser Call typecheckt OHNE Casts/unknowns.
+    const ref = buildTarget({
+      target: textContent.exports.handle,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref.featureId).toBe("text-content");
+    expect(ref.action).toBe("edit");
+    expect(ref.args).toEqual({ slug: "imprint" });
+  });
+
+  test("NoArgs-Action durch den Bridge — list ohne args", () => {
+    const textContent = defineFeature("text-content", (r) => {
+      const handle = r.treeActions({
+        edit: { args: { slug: "" as string } },
+        list: {},
+      });
+      return { handle };
+    });
+    const ref = buildTarget({ target: textContent.exports.handle, action: "list" });
+    expect(ref).toEqual({ featureId: "text-content", action: "list" });
+  });
+
+  test("Compile-Time-Pinning — typed handle rejects falsche Calls (@ts-expect-error)", () => {
+    const textContent = defineFeature("text-content", (r) => {
+      const handle = r.treeActions({
+        edit: { args: { slug: "" as string } },
+        list: {},
+      });
+      return { handle };
+    });
+
+    // @ts-expect-error — "delet" ist keine Action im Handle
+    buildTarget({ target: textContent.exports.handle, action: "delet", args: { slug: "x" } });
+
+    // @ts-expect-error — slug muss string sein, nicht number
+    buildTarget({
+      target: textContent.exports.handle,
+      action: "edit",
+      args: { slug: 42 },
+    });
+
+    buildTarget({
+      target: textContent.exports.handle,
+      action: "list",
+      // @ts-expect-error — list hat keine args, args-Feld nicht erlaubt
+      args: { x: 1 },
+    });
+
+    // @ts-expect-error — edit braucht args, fehlt
+    buildTarget({ target: textContent.exports.handle, action: "edit" });
+
+    // Runtime-Coverage (Memory `[Keine Fake-Tests]`): der korrespondierende
+    // Happy-Path über denselben typed Handle liefert valid TargetRef.
+    // Beweist dass die Bridge nicht nur compile-time funktioniert sondern
+    // runtime den richtigen TargetRef konstruiert.
+    const validRef = buildTarget({
+      target: textContent.exports.handle,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(validRef.featureId).toBe("text-content");
+    expect(validRef.action).toBe("edit");
+    expect(validRef.args).toEqual({ slug: "imprint" });
+  });
+});

package/src/engine/boot-validator/api-ext.ts

@@ -0,0 +1,77 @@
+import type { FeatureDefinition } from "../types";
+
+// --- Cross-feature API exposure / usage matching ---
+//
+// `r.exposesApi(name, impl)` registers a callable; `r.usesApi(name)`
+// declares a caller. Boot-Validator prüft drei Invarianten:
+//   1. Jeder usesApi(name) findet einen exposesApi(name) in irgendeinem
+//      Feature.
+//   2. Das exposing-Feature ist in requires/optionalRequires des callers
+//      gelisted (sonst klappt die Cross-Feature-Aufruf-Reihenfolge nicht).
+//   3. Self-exposure ist erlaubt (Feature ruft eigene API), wird aber
+//      mit Warning markiert weil es typisch ein Refactor-Restbestand ist.
+//
+// Globale Eindeutigkeit der apiNames (kein Dublicate über Features)
+// wird in validateBoot() vor dem Per-Feature-Walk geprüft.
+export function validateApiExposureMatching(
+  feature: FeatureDefinition,
+  allExposedApis: ReadonlyMap<string, string>,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  for (const apiName of feature.usedApis) {
+    const providerFeature = allExposedApis.get(apiName);
+    if (!providerFeature) {
+      const known = [...allExposedApis.keys()].sort().join(", ") || "(none)";
+      throw new Error(
+        `[Feature ${feature.name}] r.usesApi("${apiName}") but no feature exposes that API. Known exposed APIs: ${known}`,
+      );
+    }
+
+    if (providerFeature === feature.name) {
+      // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+      console.warn(
+        `[kumiko:boot] [Feature ${feature.name}] r.usesApi("${apiName}") on its own r.exposesApi — typically a refactor leftover. Call the impl directly instead.`,
+      );
+      continue;
+    }
+
+    const allDeps = [...feature.requires, ...feature.optionalRequires];
+    if (!allDeps.includes(providerFeature)) {
+      throw new Error(
+        `[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires("${providerFeature}").`,
+      );
+    }
+
+    // Sanity: provider feature actually exists in this app's feature set.
+    // Should always be true if allExposedApis was built from `features`,
+    // aber defensiv für unklare Constructor-Pfade.
+    if (!featureMap.has(providerFeature)) {
+      throw new Error(
+        `[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map`,
+      );
+    }
+  }
+}
+
+// --- Extension usage validation ---
+
+export function validateExtensionUsages(
+  feature: FeatureDefinition,
+  extensionProviders: ReadonlyMap<string, string>,
+): void {
+  for (const usage of feature.extensionUsages) {
+    const providerFeature = extensionProviders.get(usage.extensionName);
+    if (!providerFeature) {
+      throw new Error(
+        `Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension`,
+      );
+    }
+
+    const allDeps = [...feature.requires, ...feature.optionalRequires];
+    if (!allDeps.includes(providerFeature)) {
+      throw new Error(
+        `Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}")`,
+      );
+    }
+  }
+}

package/src/engine/boot-validator/config-deps.ts

@@ -0,0 +1,163 @@
+import type { FeatureDefinition } from "../types";
+
+// --- Toggleable-dependency warnings ---
+//
+// When feature A declares r.requires("B") and B is toggleable with
+// default=false, A is effectively disabled out-of-the-box until someone
+// flips B on globally. That's usually an oversight — the dev either meant
+// optionalRequires, or forgot to ship B with default=true. We warn (not
+// fail) because the combination is legal: an app might intentionally
+// require an opt-in feature to make it explicit that B must be activated.
+export function warnOnToggleableDependencies(
+  features: readonly FeatureDefinition[],
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  for (const f of features) {
+    for (const dep of f.requires) {
+      const depFeature = featureMap.get(dep);
+      if (!depFeature) continue; // requires-target-missing is handled elsewhere
+      if (depFeature.toggleableDefault === false) {
+        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+        console.warn(
+          `[kumiko:boot] Feature "${f.name}" requires "${dep}", which is toggleable(default=false). ` +
+            `"${f.name}" will be effectively disabled until "${dep}" is enabled globally via the feature-toggles feature. ` +
+            `If this is intentional, ignore this warning; otherwise consider r.optionalRequires() or default=true.`,
+        );
+      }
+    }
+  }
+}
+
+// --- Config key bounds consistency ---
+
+export function validateConfigKeyBounds(feature: FeatureDefinition): void {
+  for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+    const bounds = keyDef.bounds;
+    // skip: no bounds declared, nothing to validate
+    if (!bounds) continue;
+
+    // Bounds on non-number keys are nonsensical — the call-site type-guard
+    // already rejects this, but catch it at boot as defence in depth (e.g.
+    // a hand-rolled key definition that bypasses createTenantConfig).
+    if (keyDef.type !== "number") {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has bounds but type is "${keyDef.type}" — bounds are only valid for type="number"`,
+      );
+    }
+
+    const { min, max } = bounds;
+
+    if (min !== undefined && max !== undefined && min > max) {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has bounds.min (${min}) > bounds.max (${max})`,
+      );
+    }
+
+    if (keyDef.default !== undefined) {
+      const defaultNum = keyDef.default as number; // @cast-boundary engine-payload
+      if (min !== undefined && defaultNum < min) {
+        throw new Error(
+          `[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is below bounds.min (${min})`,
+        );
+      }
+      if (max !== undefined && defaultNum > max) {
+        throw new Error(
+          `[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is above bounds.max (${max})`,
+        );
+      }
+    }
+  }
+}
+
+// --- Config key computed + encrypted exclusivity ---
+
+export function validateConfigKeyComputed(feature: FeatureDefinition): void {
+  for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+    if (!keyDef.computed) continue;
+
+    // computed + encrypted mix two paradigms that shouldn't meet: computed
+    // returns a plain value, encrypted expects cipher-text in the row. The
+    // cascade doesn't know which one to prefer on write. Rejecting at boot
+    // is cheaper than surprising behaviour at runtime.
+    if (keyDef.encrypted) {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has both encrypted=true and a computed resolver — these are mutually exclusive paradigms`,
+      );
+    }
+  }
+}
+
+// --- Config key allowPerRequest compatibility ---
+
+export function validateConfigKeyAllowPerRequest(feature: FeatureDefinition): void {
+  for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+    if (!keyDef.allowPerRequest) continue;
+
+    // text is hard-locked against per-request — the helper refuses
+    // anyway, but declaring allowPerRequest on a text key is a
+    // misconfiguration that should fail loudly at boot.
+    if (keyDef.type === "text") {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but type="text" — text keys are permanently ineligible for per-request overrides (XSS/injection risk)`,
+      );
+    }
+
+    // encrypted + per-request would expose a cipher-text interpretation
+    // to query-strings. The secret-value shouldn't be transported this
+    // way — reject as a paradigm-mismatch.
+    if (keyDef.encrypted) {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but encrypted=true — secret values may not be set via query-params`,
+      );
+    }
+  }
+}
+
+// --- Config key cross-feature reference validation ---
+
+export function validateConfigReads(
+  features: readonly FeatureDefinition[],
+  allConfigKeys: ReadonlySet<string>,
+): void {
+  for (const feature of features) {
+    for (const key of feature.configReads) {
+      if (!allConfigKeys.has(key)) {
+        throw new Error(
+          `Feature "${feature.name}" reads config "${key}" but no feature defines that key`,
+        );
+      }
+    }
+  }
+}
+
+// --- Circular dependency detection ---
+
+export function validateCircularDeps(
+  featureName: string,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  const visited = new Set<string>();
+  const stack = new Set<string>();
+
+  function visit(name: string, path: string[]): void {
+    if (stack.has(name)) {
+      throw new Error(`Circular dependency: ${[...path, name].join(" → ")}`);
+    }
+    // skip: node already visited in DFS traversal
+    if (visited.has(name)) return;
+
+    visited.add(name);
+    stack.add(name);
+
+    const feature = featureMap.get(name);
+    if (feature) {
+      for (const dep of feature.requires) {
+        visit(dep, [...path, name]);
+      }
+    }
+
+    stack.delete(name);
+  }
+
+  visit(featureName, []);
+}