@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

package/src/engine/feature-ast/__tests__/visual-tree-parse.test.ts

@@ -0,0 +1,184 @@
+// AST round-trip tests for the Visual-Tree patterns. Each test feeds
+// a minimal inline-feature into parseSourceFile and asserts the
+// extracted Pattern shape + the editability classification.
+//
+// Why split from visual-tree-patterns.test.ts (engine-level): that suite
+// covers the registrar+registry runtime path. This suite covers the
+// AST extractor + the Designer/AI consumers (renderPattern,
+// getEditability, PATTERN_LIBRARY). Both halves must agree on shape.
+
+import { Project } from "ts-morph";
+import { describe, expect, test } from "vitest";
+import { parseSourceFile } from "../parse";
+import { getEditability } from "../patterns";
+import { renderPattern } from "../render";
+
+function parseInline(source: string) {
+  const project = new Project({ skipAddingFilesFromTsConfig: true, useInMemoryFileSystem: true });
+  const sourceFile = project.createSourceFile("feature.ts", source);
+  return parseSourceFile(sourceFile);
+}
+
+describe("parseSourceFile — r.treeActions extraction", () => {
+  test("extracts a static treeActions pattern from an inline action-map", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("text-content", (r) => {
+        r.treeActions({
+          edit: { args: { slug: "" as string } },
+          list: {},
+        });
+      });
+    `);
+
+    expect(result.errors).toEqual([]);
+    const treeActions = result.patterns.find((p) => p.kind === "treeActions");
+    expect(treeActions).toBeDefined();
+    expect(treeActions?.kind).toBe("treeActions");
+    if (treeActions?.kind === "treeActions") {
+      expect(treeActions.definitions).toEqual({
+        edit: { args: { slug: "" } },
+        list: {},
+      });
+    }
+  });
+
+  test("treeActions pattern is classified as static (Designer renders form)", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("x", (r) => { r.treeActions({ list: {} }); });
+    `);
+    const treeActions = result.patterns.find((p) => p.kind === "treeActions");
+    expect(treeActions).toBeDefined();
+    if (treeActions !== undefined) {
+      expect(getEditability(treeActions)).toBe("static");
+    }
+  });
+
+  test("missing first argument produces a parse-error, not a pattern", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("x", (r) => { r.treeActions(); });
+    `);
+    expect(result.patterns.find((p) => p.kind === "treeActions")).toBeUndefined();
+    expect(result.errors.some((e) => e.methodName === "treeActions")).toBe(true);
+  });
+
+  test("non-object first argument (identifier ref) produces a parse-error", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      const actions = { list: {} };
+      defineFeature("x", (r) => { r.treeActions(actions); });
+    `);
+    expect(result.patterns.find((p) => p.kind === "treeActions")).toBeUndefined();
+    expect(result.errors.some((e) => e.methodName === "treeActions")).toBe(true);
+  });
+
+  test("renderPattern round-trips back to a valid r.treeActions(...) call", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("x", (r) => {
+        r.treeActions({ edit: { args: { slug: "" } }, list: {} });
+      });
+    `);
+    const treeActions = result.patterns.find((p) => p.kind === "treeActions");
+    expect(treeActions).toBeDefined();
+    if (treeActions !== undefined) {
+      const rendered = renderPattern(treeActions);
+      expect(rendered).toMatch(/^r\.treeActions\(/);
+      // renderValue darf identifier-safe Keys unquoted ausgeben — beide
+      // Schreibweisen sind valide TypeScript-Source.
+      expect(rendered).toMatch(/(["])edit\1|edit\s*:/);
+      expect(rendered).toMatch(/(["])slug\1|slug\s*:/);
+    }
+  });
+});
+
+describe("parseSourceFile — r.tree extraction", () => {
+  test("extracts an opaque tree pattern with the provider body as SourceLocation", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("text-content", (r) => {
+        r.tree((ctx) => (emit) => {
+          emit([{ label: "Marketing" }]);
+          return () => {};
+        });
+      });
+    `);
+
+    expect(result.errors).toEqual([]);
+    const tree = result.patterns.find((p) => p.kind === "tree");
+    expect(tree).toBeDefined();
+    if (tree?.kind === "tree") {
+      expect(tree.providerBody.raw).toContain("emit");
+      expect(tree.providerBody.raw).toContain("Marketing");
+    }
+  });
+
+  test("tree pattern is classified as opaque (Designer renders read-only code-block)", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("x", (r) => { r.tree((ctx) => (emit) => () => {}); });
+    `);
+    const tree = result.patterns.find((p) => p.kind === "tree");
+    expect(tree).toBeDefined();
+    if (tree !== undefined) {
+      expect(getEditability(tree)).toBe("opaque");
+    }
+  });
+
+  test("missing first argument produces a parse-error, not a pattern", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("x", (r) => { r.tree(); });
+    `);
+    expect(result.patterns.find((p) => p.kind === "tree")).toBeUndefined();
+    expect(result.errors.some((e) => e.methodName === "tree")).toBe(true);
+  });
+
+  test("non-function first argument (identifier ref) produces a parse-error", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      const provider = (ctx: unknown) => (emit: unknown) => () => {};
+      defineFeature("x", (r) => { r.tree(provider); });
+    `);
+    expect(result.patterns.find((p) => p.kind === "tree")).toBeUndefined();
+    expect(result.errors.some((e) => e.methodName === "tree")).toBe(true);
+  });
+
+  test("renderPattern round-trips back to a valid r.tree(...) call with the body verbatim", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("x", (r) => {
+        r.tree((ctx) => (emit) => { emit([]); return () => {}; });
+      });
+    `);
+    const tree = result.patterns.find((p) => p.kind === "tree");
+    expect(tree).toBeDefined();
+    if (tree !== undefined) {
+      const rendered = renderPattern(tree);
+      expect(rendered).toMatch(/^r\.tree\(/);
+      expect(rendered).toContain("emit");
+    }
+  });
+});
+
+describe("Combined — feature with both r.treeActions and r.tree", () => {
+  test("both patterns coexist in the parse output, source-order preserved", () => {
+    const result = parseInline(`
+      import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+      defineFeature("text-content", (r) => {
+        r.treeActions({ edit: { args: { slug: "" } } });
+        r.tree((ctx) => (emit) => { emit([{ label: "Marketing" }]); return () => {}; });
+      });
+    `);
+
+    expect(result.errors).toEqual([]);
+    const kinds = result.patterns.map((p) => p.kind);
+    const idxActions = kinds.indexOf("treeActions");
+    const idxTree = kinds.indexOf("tree");
+    expect(idxActions).toBeGreaterThanOrEqual(0);
+    expect(idxTree).toBeGreaterThanOrEqual(0);
+    expect(idxActions).toBeLessThan(idxTree);
+  });
+});

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

@@ -0,0 +1,74 @@
+export {
+  extractOptionalRequires,
+  extractReadsConfig,
+  extractRequires,
+  extractSystemScope,
+  extractToggleable,
+} from "./round1";
+export {
+  extractEntity,
+  extractNav,
+  extractRelation,
+  extractWorkspace,
+} from "./round2";
+export {
+  extractClaimKey,
+  extractConfig,
+  extractMetric,
+  extractReferenceData,
+  extractSecret,
+  extractTranslations,
+  extractUseExtension,
+  isClaimKeyType,
+  type NamedOptionsResult,
+  readNamedOptions,
+} from "./round3";
+export {
+  collectScreenOpaqueProps,
+  extractAuthClaims,
+  extractDefineEvent,
+  extractEntityHook,
+  extractEventMigration,
+  extractHook,
+  extractHttpRoute,
+  extractJob,
+  extractMultiStreamProjection,
+  extractNotification,
+  extractProjection,
+  extractQueryHandler,
+  extractScreen,
+  extractWriteHandler,
+  isEntityHookType,
+  isHookType,
+  isHttpRouteMethod,
+  type ParsedHandlerCall,
+  parseHandlerCall,
+  readApplyBodies,
+  readOptionalAccessRule,
+  readOptionalPhase,
+  readOptionalRateLimit,
+  readScreenStatic,
+} from "./round4";
+export {
+  extractExposesApi,
+  extractExtendsRegistrar,
+  extractUsesApi,
+} from "./round5";
+export {
+  extractTree,
+  extractTreeActions,
+} from "./round6";
+export type { ExtractOutput } from "./shared";
+export {
+  fail,
+  findFunctionLiteral,
+  isPlainObject,
+  ok,
+  readBooleanProperty,
+  readDataLiteralNode,
+  readNameOrRef,
+  readNameOrRefOrList,
+  readPropertyKey,
+  readStringLiteralArgs,
+  readVarargsOrArrayProp,
+} from "./shared";

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

@@ -0,0 +1,110 @@
+import type { CallExpression, SourceFile } from "ts-morph";
+import type {
+  OptionalRequiresPattern,
+  ReadsConfigPattern,
+  RequiresPattern,
+  SystemScopePattern,
+  ToggleablePattern,
+} from "../patterns";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  ok,
+  readBooleanProperty,
+  readVarargsOrArrayProp,
+} from "./shared";
+
+export function extractRequires(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<RequiresPattern> {
+  const names = readVarargsOrArrayProp(call, "features");
+  if (!names) {
+    return fail(
+      "requires",
+      sourceLocationFromNode(call, sourceFile),
+      "expected positional string literals or { features: string[] }",
+    );
+  }
+  return ok({
+    kind: "requires",
+    source: sourceLocationFromNode(call, sourceFile),
+    featureNames: names,
+  });
+}
+
+export function extractOptionalRequires(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<OptionalRequiresPattern> {
+  const names = readVarargsOrArrayProp(call, "features");
+  if (!names) {
+    return fail(
+      "optionalRequires",
+      sourceLocationFromNode(call, sourceFile),
+      "expected positional string literals or { features: string[] }",
+    );
+  }
+  return ok({
+    kind: "optionalRequires",
+    source: sourceLocationFromNode(call, sourceFile),
+    featureNames: names,
+  });
+}
+
+export function extractReadsConfig(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ReadsConfigPattern> {
+  const keys = readVarargsOrArrayProp(call, "keys");
+  if (!keys) {
+    return fail(
+      "readsConfig",
+      sourceLocationFromNode(call, sourceFile),
+      "expected positional string literals or { keys: string[] }",
+    );
+  }
+  return ok({
+    kind: "readsConfig",
+    source: sourceLocationFromNode(call, sourceFile),
+    qualifiedKeys: keys,
+  });
+}
+
+export function extractSystemScope(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<SystemScopePattern> {
+  return ok({
+    kind: "systemScope",
+    source: sourceLocationFromNode(call, sourceFile),
+  });
+}
+
+export function extractToggleable(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ToggleablePattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "toggleable",
+      sourceLocationFromNode(call, sourceFile),
+      "expected an object argument with a `default` boolean",
+    );
+  }
+  const defaultValue = readBooleanProperty(arg, "default");
+  if (defaultValue === undefined) {
+    return fail(
+      "toggleable",
+      sourceLocationFromNode(call, sourceFile),
+      "argument must be `{ default: true | false }`",
+    );
+  }
+  return ok({
+    kind: "toggleable",
+    source: sourceLocationFromNode(call, sourceFile),
+    default: defaultValue,
+  });
+}

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

@@ -0,0 +1,253 @@
+import type { CallExpression, SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import type { EntityDefinition } from "../../types/fields";
+import type { NavDefinition } from "../../types/nav";
+import type { RelationDefinition } from "../../types/relations";
+import type { WorkspaceDefinition } from "../../types/workspace";
+import type { EntityPattern, NavPattern, RelationPattern, WorkspacePattern } from "../patterns";
+import { sourceLocationFromNode } from "../source-location";
+import {
+  type ExtractOutput,
+  fail,
+  isPlainObject,
+  ok,
+  readDataLiteralNode,
+  readNameOrRef,
+} from "./shared";
+
+export function extractEntity(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<EntityPattern> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail(
+      "entity",
+      sourceLocationFromNode(call, sourceFile),
+      "expected at least one argument",
+    );
+  }
+
+  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (obj && args.length === 1) {
+    const nameInit = obj
+      .getProperty("name")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
+    if (!nameInit) {
+      return fail(
+        "entity",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `name` property",
+      );
+    }
+    const definition = readDataLiteralNode(obj);
+    if (!isPlainObject(definition)) {
+      return fail(
+        "entity",
+        sourceLocationFromNode(call, sourceFile),
+        "definition could not be read as a plain object (contains functions or identifiers)",
+      );
+    }
+    const { name: _name, ...defWithoutName } = definition;
+    return ok({
+      kind: "entity",
+      source: sourceLocationFromNode(call, sourceFile),
+      entityName: nameInit.getLiteralValue(),
+      definition: defWithoutName as EntityDefinition,
+    });
+  }
+
+  const nameArg = first.asKind(SyntaxKind.StringLiteral);
+  if (!nameArg) {
+    return fail(
+      "entity",
+      sourceLocationFromNode(call, sourceFile),
+      "first argument must be a string literal name (or use the object form)",
+    );
+  }
+  const defArg = args[1];
+  if (!defArg) {
+    return fail(
+      "entity",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a definition object as second argument",
+    );
+  }
+  const definition = readDataLiteralNode(defArg);
+  if (!isPlainObject(definition)) {
+    return fail(
+      "entity",
+      sourceLocationFromNode(call, sourceFile),
+      "definition could not be read as a plain object (contains functions or identifiers)",
+    );
+  }
+  return ok({
+    kind: "entity",
+    source: sourceLocationFromNode(call, sourceFile),
+    entityName: nameArg.getLiteralValue(),
+    definition: definition as EntityDefinition,
+  });
+}
+
+export function extractRelation(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<RelationPattern> {
+  const args = call.getArguments();
+  const first = args[0];
+  if (!first) {
+    return fail(
+      "relation",
+      sourceLocationFromNode(call, sourceFile),
+      "expected at least one argument",
+    );
+  }
+
+  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (obj && args.length === 1) {
+    const entityInit = obj
+      .getProperty("entity")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!entityInit) {
+      return fail(
+        "relation",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires an `entity` property",
+      );
+    }
+    const entityName = readNameOrRef(entityInit);
+    if (!entityName) {
+      return fail(
+        "relation",
+        sourceLocationFromNode(call, sourceFile),
+        '`entity` must be a string literal or `{ name: "..." }` ref',
+      );
+    }
+    const nameInit = obj
+      .getProperty("name")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
+    if (!nameInit) {
+      return fail(
+        "relation",
+        sourceLocationFromNode(call, sourceFile),
+        "object form requires a string-literal `name` property",
+      );
+    }
+    const definition = readDataLiteralNode(obj);
+    if (!isPlainObject(definition)) {
+      return fail(
+        "relation",
+        sourceLocationFromNode(call, sourceFile),
+        "definition could not be read as a plain object",
+      );
+    }
+    const { entity: _e, name: _n, ...defWithoutCarriers } = definition;
+    return ok({
+      kind: "relation",
+      source: sourceLocationFromNode(call, sourceFile),
+      entityName,
+      relationName: nameInit.getLiteralValue(),
+      definition: defWithoutCarriers as RelationDefinition,
+    });
+  }
+
+  const entityName = readNameOrRef(first);
+  if (!entityName) {
+    return fail(
+      "relation",
+      sourceLocationFromNode(call, sourceFile),
+      'first argument must be a string literal or an inline { name: "..." } object (or use the object form)',
+    );
+  }
+  const nameArg = args[1]?.asKind(SyntaxKind.StringLiteral);
+  if (!nameArg) {
+    return fail(
+      "relation",
+      sourceLocationFromNode(call, sourceFile),
+      "second argument must be a string literal relation name",
+    );
+  }
+  const defArg = args[2];
+  if (!defArg) {
+    return fail(
+      "relation",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a definition object as third argument",
+    );
+  }
+  const definition = readDataLiteralNode(defArg);
+  if (!isPlainObject(definition)) {
+    return fail(
+      "relation",
+      sourceLocationFromNode(call, sourceFile),
+      "definition could not be read as a plain object",
+    );
+  }
+  return ok({
+    kind: "relation",
+    source: sourceLocationFromNode(call, sourceFile),
+    entityName,
+    relationName: nameArg.getLiteralValue(),
+    definition: definition as RelationDefinition,
+  });
+}
+
+export function extractNav(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<NavPattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "nav",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a NavDefinition object as first argument",
+    );
+  }
+  const definition = readDataLiteralNode(arg);
+  if (!isPlainObject(definition)) {
+    return fail(
+      "nav",
+      sourceLocationFromNode(call, sourceFile),
+      "definition could not be read as a plain object",
+    );
+  }
+  return ok({
+    kind: "nav",
+    source: sourceLocationFromNode(call, sourceFile),
+    definition: definition as NavDefinition,
+  });
+}
+
+export function extractWorkspace(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<WorkspacePattern> {
+  const arg = call.getArguments()[0];
+  if (!arg) {
+    return fail(
+      "workspace",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a WorkspaceDefinition object as first argument",
+    );
+  }
+  const definition = readDataLiteralNode(arg);
+  if (!isPlainObject(definition)) {
+    return fail(
+      "workspace",
+      sourceLocationFromNode(call, sourceFile),
+      "definition could not be read as a plain object",
+    );
+  }
+  return ok({
+    kind: "workspace",
+    source: sourceLocationFromNode(call, sourceFile),
+    definition: definition as WorkspaceDefinition,
+  });
+}