@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/engine/build-app-schema.ts

@@ -115,7 +115,7 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (isLiteral(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];
-  return out as FieldDefinition;
+  return out as FieldDefinition; // @cast-boundary schema-walk
 }
 
 function isLiteral(value: unknown): boolean {

package/src/engine/build-target.ts

@@ -0,0 +1,99 @@
+// buildTarget — typed Builder für TargetRef.
+//
+// **Was er macht.** Erzeugt einen TargetRef, dessen action + args
+// compile-time gegen die treeActions-Map des Ziel-Features validiert
+// sind. Magic-String-URIs werden nirgends hand-getippt; das ist die
+// Single-Source-of-Truth für Cross-Feature-Linking im Visual-Tree.
+//
+// **Wie er typed.** Function-Overloads splitten Actions ohne args
+// (NoArgsAction) und Actions mit args (WithArgsAction). TS validiert:
+//   - action ist string-literal aus den Keys von treeActions
+//   - bei WithArgsAction sind args required und matchen
+//     treeActions[action]["args"]
+//   - bei NoArgsAction ist args nicht erlaubt
+//
+// **Phase 0.** Das Feature-Handle ist hier eine generische Constraint
+// (FeatureWithTreeActions). In Schicht 2 wird treeActions ein
+// Pattern-Type im Feature-AST und defineFeature exposed eine
+// treeActions-Slot mit gleichem Shape — dann passen real Features
+// drauf, ohne Builder-Änderung.
+//
+// Siehe docs/plans/architecture/visual-tree.md A5.
+
+import type { TargetRef } from "./types/target-ref";
+import type { TreeActionDef } from "./types/tree-node";
+
+// FeatureWithTreeActions — internal Generic-Constraint für den Builder.
+// **Bewusst nicht exportiert** — Phase-0-Stub, wird in V.1.1 durch echte
+// FeatureDefinition mit treeActions-Slot ersetzt. Caller brauchen den Type
+// nicht direkt; TS leitet ihn aus dem `target`-Argument von buildTarget ab.
+type FeatureWithTreeActions<TActions extends Record<string, TreeActionDef>> = {
+  readonly id: string;
+  readonly treeActions: TActions;
+};
+
+// NoArgsAction<T> — Union der Action-Namen die KEINE args-Definition
+// haben. Mapped-Type emittiert pro Key entweder K (kein args) oder never
+// (args vorhanden); Index-Lookup `[keyof T]` reduziert auf die K-Keys.
+// `& string` schneidet number/symbol-keys raus die TS via keyof
+// theoretisch zulassen würde — Action-Namen sind ausschließlich Strings.
+type NoArgsAction<T extends Record<string, TreeActionDef>> = {
+  [K in keyof T]: T[K] extends { args: unknown } ? never : K;
+}[keyof T] &
+  string;
+
+// WithArgsAction<T> — Komplement zu NoArgsAction: Union der Action-
+// Namen die `args` deklariert haben. Selbe Mechanik mit invertiertem
+// conditional. Trennung in zwei Unions ist nötig damit die Function-
+// Overloads (NoArgs vs. WithArgs) sauber typed werden können.
+type WithArgsAction<T extends Record<string, TreeActionDef>> = {
+  [K in keyof T]: T[K] extends { args: unknown } ? K : never;
+}[keyof T] &
+  string;
+
+// TypeGuard für args: Overloads garantieren ein Plain-Object, aber die
+// Implementation-Signature sieht args als unknown (TArgs ist erased zur
+// Laufzeit). Der Guard validiert die Plain-Object-Convention runtime
+// statt einen `as`-Cast zu setzen — siehe coding-standards.md.
+function isArgsObject(v: unknown): v is Readonly<Record<string, unknown>> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// Overload 1: action ohne args
+export function buildTarget<
+  TActions extends Record<string, TreeActionDef>,
+  TActionName extends NoArgsAction<TActions>,
+>(spec: {
+  readonly target: FeatureWithTreeActions<TActions>;
+  readonly action: TActionName;
+}): TargetRef;
+
+// Overload 2: action mit args (required + typed)
+export function buildTarget<
+  TActions extends Record<string, TreeActionDef>,
+  TActionName extends WithArgsAction<TActions>,
+>(spec: {
+  readonly target: FeatureWithTreeActions<TActions>;
+  readonly action: TActionName;
+  readonly args: TActions[TActionName] extends { args: infer TArgs } ? TArgs : never;
+}): TargetRef;
+
+// Implementation — args ist `unknown` weil die Overloads-Generic-TArgs
+// zur Laufzeit erased ist. Plain-Object-Convention via TypeGuard.
+export function buildTarget(spec: {
+  readonly target: { readonly id: string };
+  readonly action: string;
+  readonly args?: unknown;
+}): TargetRef {
+  if (!isArgsObject(spec.args)) {
+    return Object.freeze({
+      featureId: spec.target.id,
+      action: spec.action,
+    });
+  }
+  return Object.freeze({
+    featureId: spec.target.id,
+    action: spec.action,
+    args: Object.freeze({ ...spec.args }),
+  });
+}

package/src/engine/codemod/index.ts

@@ -0,0 +1,15 @@
+export type {
+  CodemodOptions,
+  CodemodReport,
+  CodemodResult,
+  FileAnalysis,
+  ParsedHandlerInfo,
+} from "./pipeline-codemod";
+export {
+  analyzeFile,
+  analyzeHandlerArrow,
+  convertFile,
+  generatePerformBlock,
+  runCodemod,
+  scanForCandidates,
+} from "./pipeline-codemod";