@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/feature-ast/extractors/round5.ts

@@ -0,0 +1,72 @@
+import type { CallExpression, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { ExposesApiPattern, ExtendsRegistrarPattern, UsesApiPattern } from "../patterns";
+import { sourceLocationFromNode } from "../source-location";
+import { type ExtractOutput, fail, ok } from "./shared";
+
+export function extractExtendsRegistrar(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ExtendsRegistrarPattern> {
+  const args = call.getArguments();
+  const nameArg = args[0]?.asKind(SyntaxKind.StringLiteral);
+  if (!nameArg) {
+    return fail(
+      "extendsRegistrar",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be a string literal extension name",
+    );
+  }
+  const defArg = args[1];
+  if (!defArg) {
+    return fail(
+      "extendsRegistrar",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a definition argument",
+    );
+  }
+  return ok({
+    kind: "extendsRegistrar",
+    source: sourceLocationFromNode(call, sourceFile),
+    extensionName: nameArg.getLiteralValue(),
+    defBody: sourceLocationFromNode(defArg, sourceFile),
+  });
+}
+
+export function extractUsesApi(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<UsesApiPattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
+  if (!arg) {
+    return fail(
+      "usesApi",
+      sourceLocationFromNode(call, sourceFile),
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+    );
+  }
+  return ok({
+    kind: "usesApi",
+    source: sourceLocationFromNode(call, sourceFile),
+    apiName: arg.getLiteralValue(),
+  });
+}
+
+export function extractExposesApi(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ExposesApiPattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
+  if (!arg) {
+    return fail(
+      "exposesApi",
+      sourceLocationFromNode(call, sourceFile),
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+    );
+  }
+  return ok({
+    kind: "exposesApi",
+    source: sourceLocationFromNode(call, sourceFile),
+    apiName: arg.getLiteralValue(),
+  });
+}

package/src/engine/feature-ast/extractors/round6.ts

@@ -0,0 +1,66 @@
+import type { CallExpression, SourceFile } from "ts-morph";
+import type { TreeActionDef } from "../../types/tree-node";
+import type { TreeActionsPattern, TreePattern } from "../patterns";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  findFunctionLiteral,
+  isPlainObject,
+  ok,
+  readDataLiteralNode,
+} from "./shared";
+
+export function extractTreeActions(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<TreeActionsPattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "treeActions",
+      sourceLocationFromNode(call, sourceFile),
+      "expected an action-map object literal as first argument",
+    );
+  }
+  const definitions = readDataLiteralNode(arg);
+  if (!isPlainObject(definitions)) {
+    return fail(
+      "treeActions",
+      sourceLocationFromNode(call, sourceFile),
+      "action-map could not be read as a plain object",
+    );
+  }
+  return ok({
+    kind: "treeActions",
+    source: sourceLocationFromNode(call, sourceFile),
+    definitions: definitions as Readonly<Record<string, TreeActionDef>>,
+  });
+}
+
+export function extractTree(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<TreePattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "tree",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a tree-provider function as first argument",
+    );
+  }
+  const fn = findFunctionLiteral(arg);
+  if (!fn) {
+    return fail(
+      "tree",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be an inline arrow function or function expression",
+    );
+  }
+  return ok({
+    kind: "tree",
+    source: sourceLocationFromNode(call, sourceFile),
+    providerBody: sourceLocationFromNode(fn, sourceFile),
+  });
+}

package/src/engine/feature-ast/extractors/shared.ts

@@ -0,0 +1,177 @@
+import type { CallExpression, Node } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { ParseError } from "../parse";
+
+export type ExtractOutput<TPattern> =
+  | { readonly kind: "pattern"; readonly pattern: TPattern }
+  | { readonly kind: "error"; readonly error: ParseError };
+
+export function ok<TPattern>(pattern: TPattern): ExtractOutput<TPattern> {
+  return { kind: "pattern", pattern };
+}
+
+export function fail(
+  methodName: string,
+  source: ParseError["source"],
+  reason: string,
+): { readonly kind: "error"; readonly error: ParseError } {
+  return { kind: "error", error: { methodName, source, reason } };
+}
+
+export function readStringLiteralArgs(call: CallExpression): readonly string[] | undefined {
+  const out: string[] = [];
+  for (const arg of call.getArguments()) {
+    const literal = arg.asKind(SyntaxKind.StringLiteral);
+    if (!literal) return undefined;
+    out.push(literal.getLiteralValue());
+  }
+  return out;
+}
+
+export function readBooleanProperty(
+  objectLiteral: Node,
+  propertyName: string,
+): boolean | undefined {
+  const obj = objectLiteral.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!obj) return undefined;
+  const prop = obj.getProperty(propertyName);
+  if (!prop) return undefined;
+  const assignment = prop.asKind(SyntaxKind.PropertyAssignment);
+  if (!assignment) return undefined;
+  const initializer = assignment.getInitializer();
+  if (!initializer) return undefined;
+  const kind = initializer.getKind();
+  if (kind === SyntaxKind.TrueKeyword) return true;
+  if (kind === SyntaxKind.FalseKeyword) return false;
+  return undefined;
+}
+
+export function readDataLiteralNode(node: Node): unknown {
+  const kind = node.getKind();
+  switch (kind) {
+    case SyntaxKind.StringLiteral:
+      return node.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue();
+    case SyntaxKind.NoSubstitutionTemplateLiteral:
+      return node.asKindOrThrow(SyntaxKind.NoSubstitutionTemplateLiteral).getLiteralValue();
+    case SyntaxKind.NumericLiteral:
+      return Number(node.asKindOrThrow(SyntaxKind.NumericLiteral).getText());
+    case SyntaxKind.TrueKeyword:
+      return true;
+    case SyntaxKind.FalseKeyword:
+      return false;
+    case SyntaxKind.NullKeyword:
+      return null;
+    case SyntaxKind.PrefixUnaryExpression: {
+      const expr = node.asKindOrThrow(SyntaxKind.PrefixUnaryExpression);
+      if (expr.getOperatorToken() !== SyntaxKind.MinusToken) return undefined;
+      const inner = readDataLiteralNode(expr.getOperand());
+      if (typeof inner !== "number") return undefined;
+      return -inner;
+    }
+    case SyntaxKind.ArrayLiteralExpression: {
+      const arr = node.asKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+      const out: unknown[] = [];
+      for (const el of arr.getElements()) {
+        const value = readDataLiteralNode(el);
+        if (value === undefined) return undefined;
+        out.push(value);
+      }
+      return out;
+    }
+    case SyntaxKind.ObjectLiteralExpression: {
+      const obj = node.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+      const out: Record<string, unknown> = {};
+      for (const prop of obj.getProperties()) {
+        const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+        if (!propAssign) return undefined;
+        const initializer = propAssign.getInitializer();
+        if (!initializer) return undefined;
+        const value = readDataLiteralNode(initializer);
+        if (value === undefined) return undefined;
+        out[readPropertyKey(propAssign)] = value;
+      }
+      return out;
+    }
+    case SyntaxKind.AsExpression:
+      return readDataLiteralNode(node.asKindOrThrow(SyntaxKind.AsExpression).getExpression());
+    case SyntaxKind.SatisfiesExpression:
+      return readDataLiteralNode(
+        node.asKindOrThrow(SyntaxKind.SatisfiesExpression).getExpression(),
+      );
+    case SyntaxKind.ParenthesizedExpression:
+      return readDataLiteralNode(
+        node.asKindOrThrow(SyntaxKind.ParenthesizedExpression).getExpression(),
+      );
+    default:
+      return undefined;
+  }
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignment): string {
+  const nameNode = propAssign.getNameNode();
+  const literal = nameNode.asKind(SyntaxKind.StringLiteral);
+  if (literal) return literal.getLiteralValue();
+  return propAssign.getName();
+}
+
+export function readNameOrRef(node: Node): string | undefined {
+  const literal = node.asKind(SyntaxKind.StringLiteral);
+  if (literal) return literal.getLiteralValue();
+  const obj = readDataLiteralNode(node);
+  if (isPlainObject(obj) && typeof obj["name"] === "string") return obj["name"];
+  return undefined;
+}
+
+export function findFunctionLiteral(node: Node): Node | undefined {
+  if (node.getKind() === SyntaxKind.ArrowFunction) return node;
+  if (node.getKind() === SyntaxKind.FunctionExpression) return node;
+  const paren = node.asKind(SyntaxKind.ParenthesizedExpression);
+  if (paren) return findFunctionLiteral(paren.getExpression());
+  return undefined;
+}
+
+export function readNameOrRefOrList(node: Node): string | readonly string[] | undefined {
+  const single = readNameOrRef(node);
+  if (single) return single;
+  const arr = node.asKind(SyntaxKind.ArrayLiteralExpression);
+  if (!arr) return undefined;
+  const out: string[] = [];
+  for (const el of arr.getElements()) {
+    const name = readNameOrRef(el);
+    if (!name) return undefined;
+    out.push(name);
+  }
+  return out;
+}
+
+export function readVarargsOrArrayProp(
+  call: CallExpression,
+  arrayPropName: "features" | "keys",
+): readonly string[] | undefined {
+  const args = call.getArguments();
+  if (args.length === 1) {
+    const obj = args[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (obj) {
+      const propInit = obj
+        .getProperty(arrayPropName)
+        ?.asKind(SyntaxKind.PropertyAssignment)
+        ?.getInitializer();
+      if (propInit) {
+        const arr = propInit.asKind(SyntaxKind.ArrayLiteralExpression);
+        if (!arr) return undefined;
+        const out: string[] = [];
+        for (const el of arr.getElements()) {
+          const lit = el.asKind(SyntaxKind.StringLiteral);
+          if (!lit) return undefined;
+          out.push(lit.getLiteralValue());
+        }
+        return out;
+      }
+    }
+  }
+  return readStringLiteralArgs(call);
+}

package/src/engine/feature-ast/parse.ts

@@ -33,6 +33,7 @@ import {
   extractEntity,
   extractEntityHook,
   extractEventMigration,
+  extractExposesApi,
   extractExtendsRegistrar,
   extractHook,
   extractHttpRoute,
@@ -53,7 +54,10 @@ import {
   extractSystemScope,
   extractToggleable,
   extractTranslations,
+  extractTree,
+  extractTreeActions,
   extractUseExtension,
+  extractUsesApi,
   extractWorkspace,
   extractWriteHandler,
 } from "./extractors";
@@ -346,6 +350,15 @@ function dispatchExtractor(
     // Round 5 — opaque patterns
     case "extendsRegistrar":
       return extractExtendsRegistrar(call, sourceFile);
+    case "usesApi":
+      return extractUsesApi(call, sourceFile);
+    case "exposesApi":
+      return extractExposesApi(call, sourceFile);
+    // Round 6 — Visual-Tree patterns
+    case "treeActions":
+      return extractTreeActions(call, sourceFile);
+    case "tree":
+      return extractTree(call, sourceFile);
     // Unknown method — UnknownPattern signal so Designer/AI surface it
     // as "custom call" without losing the source location.
     default:

package/src/engine/feature-ast/patch.ts

@@ -81,7 +81,9 @@ export type PatternId =
   | { readonly kind: "toggleable" }
   | { readonly kind: "config" }
   | { readonly kind: "translations" }
-  | { readonly kind: "authClaims" };
+  | { readonly kind: "authClaims" }
+  | { readonly kind: "treeActions" }
+  | { readonly kind: "tree" };
 
 // =============================================================================
 // Change ops — generic apply API
@@ -271,6 +273,10 @@ export const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]> = new Set([
   "config",
   "translations",
   "authClaims",
+  // Visual-Tree slots — at-most-one per feature, mirrors the registrar's
+  // only-once-guard in define-feature.ts.
+  "treeActions",
+  "tree",
 ]);
 
 /**
@@ -323,6 +329,8 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "config":
     case "translations":
     case "authClaims":
+    case "treeActions":
+    case "tree":
       return true;
 
     case "entity":

package/src/engine/feature-ast/patcher.ts

@@ -93,7 +93,7 @@ export type AddWriteHandlerArgs = {
   readonly handlerSource: string;
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
-  readonly skipTransitionGuard?: boolean;
+  readonly unsafeSkipTransitionGuard?: boolean;
 };
 
 export type AddQueryHandlerArgs = {
@@ -364,7 +364,14 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       add({ kind: "screen", source: SYNTHETIC_LOC, definition, opaqueProps });
     },
 
-    addWriteHandler({ name, schemaSource, handlerSource, access, rateLimit, skipTransitionGuard }) {
+    addWriteHandler({
+      name,
+      schemaSource,
+      handlerSource,
+      access,
+      rateLimit,
+      unsafeSkipTransitionGuard,
+    }) {
       add({
         kind: "writeHandler",
         source: SYNTHETIC_LOC,
@@ -373,7 +380,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         handlerBody: rawLoc(handlerSource),
         ...(access !== undefined && { access }),
         ...(rateLimit !== undefined && { rateLimit }),
-        ...(skipTransitionGuard === true && { skipTransitionGuard: true }),
+        ...(unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
       });
     },
 

package/src/engine/feature-ast/patterns.ts

@@ -26,6 +26,28 @@
 // **Naming convention.** Pattern `kind` matches the r.* method name
 // 1:1 (e.g. `r.writeHandler` → `kind: "writeHandler"`). No kebab/camel
 // translation layer.
+//
+// **Adding a new FeaturePattern kind — full consumer cascade.** The
+// extension-point is wider than just this file + the parser. Update
+// ALL of these when introducing a new r.* API, otherwise tests/checks
+// catch the drift but the call-site jumps across files:
+//   1. patterns.ts (this file): Pattern type + add to FeaturePattern
+//      union + getEditability switch
+//   2. feature-ast/extractors.ts: extract<Kind> function + import in
+//      patterns-import-block
+//   3. feature-ast/parse.ts: dispatcher case + import
+//   4. feature-ast/render.ts: render<Kind> function + import + switch
+//      case
+//   5. feature-ast/patch.ts: PatternId variant; if singleton-per-feature
+//      add to SINGLETON_KINDS; callMatchesId case
+//   6. pattern-library/library.ts: <kind>Schema + entry in
+//      PATTERN_LIBRARY map
+//   7. pattern-library/__tests__/library.test.ts: ALL_KINDS array +
+//      makePlaceholderPattern case
+// TS-exhaustiveness catches most omissions automatically (1, 3, 4, 5,
+// 7-via-makePlaceholderPattern), but the runtime-checked maps in 6 +
+// the ALL_KINDS array in 7 are silent if forgotten — pin them with the
+// library.test.ts coverage tests.
 
 import type { LifecycleHookType } from "../constants";
 import type {
@@ -45,6 +67,7 @@ import type { NavDefinition } from "../types/nav";
 import type { MspErrorMode } from "../types/projection";
 import type { RelationDefinition } from "../types/relations";
 import type { ScreenDefinition } from "../types/screen";
+import type { TreeActionDef } from "../types/tree-node";
 import type { WorkspaceDefinition } from "../types/workspace";
 import type { SourceLocation } from "./source-location";
 
@@ -158,6 +181,17 @@ export type UseExtensionPattern = {
   readonly options?: Readonly<Record<string, unknown>>;
 };
 
+// r.treeActions({ ... }) — Schema-Map für Visual-Tree-Action-Verben.
+// Static: Args sind Type-Samples (kein Runtime-Validator), Designer
+// rendert das als nested form pro Action. Compile-Time-Validation
+// passiert via setup-export-Handle (TreeActionsHandle), nicht über
+// dieses Pattern — das hier ist reine Runtime-Repräsentation.
+export type TreeActionsPattern = {
+  readonly kind: "treeActions";
+  readonly source: SourceLocation;
+  readonly definitions: Readonly<Record<string, TreeActionDef>>;
+};
+
 // =============================================================================
 // Mixed patterns — header (name/access/etc.) is declarative, body
 // (handler/hook/apply/transform fn) is opaque. Designer renders the
@@ -202,7 +236,7 @@ export type WriteHandlerPattern = {
   readonly handlerBody: SourceLocation;
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
-  readonly skipTransitionGuard?: boolean;
+  readonly unsafeSkipTransitionGuard?: boolean;
 };
 
 export type QueryHandlerPattern = {
@@ -262,6 +296,16 @@ export type AuthClaimsPattern = {
   readonly fnBody: SourceLocation;
 };
 
+// r.tree(provider) — Top-Level-Tree-Provider-Function. Closure-only,
+// kein Header-Form. Designer rendert als read-only Code-Block, AI-
+// Patcher überschreibt span verbatim. Konsistent mit r.authClaims —
+// auch da ist die Function-Body die einzige Information.
+export type TreePattern = {
+  readonly kind: "tree";
+  readonly source: SourceLocation;
+  readonly providerBody: SourceLocation;
+};
+
 export type HttpRoutePattern = {
   readonly kind: "httpRoute";
   readonly source: SourceLocation;
@@ -318,6 +362,24 @@ export type ExtendsRegistrarPattern = {
   readonly defBody: SourceLocation;
 };
 
+// r.usesApi("a.b") — declarative cross-feature handler-ID dependency.
+// Boot-validation throws if no other feature exposes the handler. Single
+// string argument; pattern is purely declarative.
+export type UsesApiPattern = {
+  readonly kind: "usesApi";
+  readonly source: SourceLocation;
+  readonly apiName: string;
+};
+
+// r.exposesApi("a.b") — declarative announcement that this feature
+// provides a handler matching the cross-feature contract `a.b`. Single
+// string argument; pattern is purely declarative.
+export type ExposesApiPattern = {
+  readonly kind: "exposesApi";
+  readonly source: SourceLocation;
+  readonly apiName: string;
+};
+
 // =============================================================================
 // Catch-all — r.* calls the visitor doesn't recognise. Designer renders
 // "unknown call (cannot edit)", AI patcher leaves them unchanged. When
@@ -354,6 +416,9 @@ export type FeaturePattern =
   | ReferenceDataPattern
   | ReadsConfigPattern
   | UseExtensionPattern
+  | UsesApiPattern
+  | ExposesApiPattern
+  | TreeActionsPattern
   // Mixed
   | ScreenPattern
   | WriteHandlerPattern
@@ -369,6 +434,7 @@ export type FeaturePattern =
   | DefineEventPattern
   | EventMigrationPattern
   | ExtendsRegistrarPattern
+  | TreePattern
   // Catch-all
   | UnknownPattern;
 
@@ -406,6 +472,9 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "referenceData":
     case "readsConfig":
     case "useExtension":
+    case "usesApi":
+    case "exposesApi":
+    case "treeActions":
       return "static";
     case "screen":
     case "writeHandler":
@@ -422,6 +491,7 @@ export function getEditability(pattern: FeaturePattern): Editability {
       return "mixed";
     case "authClaims":
     case "extendsRegistrar":
+    case "tree":
     case "unknown":
       return "opaque";
     default: {

package/src/engine/feature-ast/render.ts

@@ -24,6 +24,7 @@ import type {
   EntityHookPattern,
   EntityPattern,
   EventMigrationPattern,
+  ExposesApiPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
   HookPattern,
@@ -45,8 +46,11 @@ import type {
   SystemScopePattern,
   ToggleablePattern,
   TranslationsPattern,
+  TreeActionsPattern,
+  TreePattern,
   UnknownPattern,
   UseExtensionPattern,
+  UsesApiPattern,
   WorkspacePattern,
   WriteHandlerPattern,
 } from "./patterns";
@@ -122,6 +126,14 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderEventMigration(pattern);
     case "extendsRegistrar":
       return renderExtendsRegistrar(pattern);
+    case "usesApi":
+      return renderUsesApi(pattern);
+    case "exposesApi":
+      return renderExposesApi(pattern);
+    case "treeActions":
+      return renderTreeActions(pattern);
+    case "tree":
+      return renderTree(pattern);
     case "unknown":
       return renderUnknown(pattern);
     default: {
@@ -340,7 +352,7 @@ function renderWriteHandler(p: WriteHandlerPattern): string {
   lines.push(`  handler: ${reindentBody(p.handlerBody.raw, PATTERN_INDENT)},`);
   if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
-  if (p.skipTransitionGuard === true) lines.push("  skipTransitionGuard: true,");
+  if (p.unsafeSkipTransitionGuard === true) lines.push("  unsafeSkipTransitionGuard: true,");
   lines.push("});");
   return lines.join("\n");
 }
@@ -408,6 +420,16 @@ function renderAuthClaims(p: AuthClaimsPattern): string {
   return `r.authClaims(${p.fnBody.raw});`;
 }
 
+// Visual-Tree patterns. treeActions is a static object-literal (mirrors
+// renderWorkspace), tree is opaque-only (mirrors renderAuthClaims).
+function renderTreeActions(p: TreeActionsPattern): string {
+  return `r.treeActions(${renderValue(p.definitions)});`;
+}
+
+function renderTree(p: TreePattern): string {
+  return `r.tree(${p.providerBody.raw});`;
+}
+
 function renderHttpRoute(p: HttpRoutePattern): string {
   const lines: string[] = ["r.httpRoute({"];
   lines.push(`  method: ${JSON.stringify(p.method)},`);
@@ -473,6 +495,14 @@ function renderExtendsRegistrar(p: ExtendsRegistrarPattern): string {
   return `r.extendsRegistrar(${JSON.stringify(p.extensionName)}, ${p.defBody.raw});`;
 }
 
+function renderUsesApi(p: UsesApiPattern): string {
+  return `r.usesApi(${JSON.stringify(p.apiName)});`;
+}
+
+function renderExposesApi(p: ExposesApiPattern): string {
+  return `r.exposesApi(${JSON.stringify(p.apiName)});`;
+}
+
 function renderUnknown(p: UnknownPattern): string {
   // Round-trip preservation only: emit the raw call text from the
   // SourceLocation so the rendered file stays semantically identical