@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

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

@@ -1,615 +0,0 @@
-// parseFeatureFile — entry-point for AST pattern detection. Reads a
-// `defineFeature.ts` file, walks the `setup(r => { ... })` callback,
-// and emits one FeaturePattern per recognised `r.*` call.
-//
-// **Pipeline position:**
-//
-//   ┌──────────────────┐    parseFeatureFile      ┌─────────────────────┐
-//   │ feature-file.ts  │  ──────────────────────► │ ParseResult         │
-//   │ (defineFeature   │                          │  - featureName      │
-//   │  with r.* calls) │                          │  - patterns: FP[]   │
-//   └──────────────────┘                          │  - errors: PE[]     │
-//                                                 └─────────────────────┘
-//
-// **What is NOT extracted:**
-//   - Imports, helper functions, local consts between the `r.*` calls.
-//     Those stay in the file buffer and survive every patch unchanged.
-//   - Top-level code outside `defineFeature(...)`. Designer/AI treat
-//     such files as "not a feature file".
-//
-// **Skeleton status (C1.3):** interface fixed, extractors are TODO.
-// Per-pattern extractors fill in iteratively (C1.5) — each round adds
-// one extractor + a focused test.
-
-import type {
-  ArrowFunction,
-  CallExpression,
-  Expression,
-  Node,
-  ParameterDeclaration,
-  SourceFile,
-} from "ts-morph";
-import { Project, SyntaxKind } from "ts-morph";
-
-import {
-  type ExtractOutput,
-  extractAiClassify,
-  extractAiExtract,
-  extractAiGenerate,
-  extractAuthClaims,
-  extractClaimKey,
-  extractConfig,
-  extractDefineEvent,
-  extractDescribe,
-  extractEntity,
-  extractEnvSchema,
-  extractExposesApi,
-  extractExtendsRegistrar,
-  extractHook,
-  extractHttpRoute,
-  extractJob,
-  extractMetric,
-  extractMultiStreamProjection,
-  extractNav,
-  extractNotification,
-  extractOptionalRequires,
-  extractProjection,
-  extractQueryHandler,
-  extractReadsConfig,
-  extractReferenceData,
-  extractRelation,
-  extractRequires,
-  extractScreen,
-  extractSecret,
-  extractStoreTable,
-  extractStreamHandler,
-  extractSystemScope,
-  extractToggleable,
-  extractTranslations,
-  extractTreeActions,
-  extractUiHints,
-  extractUseExtension,
-  extractUsesApi,
-  extractWorkspace,
-  extractWriteHandler,
-  findFunctionLiteral,
-  findImportBindingForLocalName,
-  readObjectPropertyInitializer,
-  resolveModuleFile,
-  resolveSameFileObjectLiteral,
-} from "./extractors";
-import type { FeaturePattern, UnknownPattern } from "./patterns";
-import { type SourceLocation, sourceLocationFromNode } from "./source-location";
-
-// =============================================================================
-// Public API
-// =============================================================================
-
-export type ParseError = {
-  // Which r.* call could not be parsed (only the method name —
-  // a call without a method name isn't an r.* call and never lands
-  // here).
-  readonly methodName: string;
-  // Where in the file. The Designer can highlight the spot
-  // ("call not understood here").
-  readonly source: SourceLocation;
-  // Free-form description (e.g. "argument 0 is not an object literal,
-  // cannot read EntityDefinition statically").
-  readonly reason: string;
-};
-
-export type ParseResult = {
-  // Extracted from `defineFeature("name", ...)`. Undefined when the
-  // file has no `defineFeature` call (then `patterns` is empty too).
-  readonly featureName: string | undefined;
-  // Recognised r.* calls in source order.
-  readonly patterns: readonly FeaturePattern[];
-  // Calls whose arguments we could not statically read. The method
-  // name is known; only the payload was unreachable. Designer renders
-  // them as "cannot edit", AI patcher leaves them alone. Distinct from
-  // UnknownPattern (where the method name itself is unknown).
-  readonly errors: readonly ParseError[];
-};
-
-/**
- * Parse the given feature file and return all recognised r.* calls
- * as a FeaturePattern list.
- *
- * Does NOT throw on TypeScript errors — the visitor works on the syntax
- * tree, not on the type checker. Files with type errors can still be
- * parsed structurally (Designer keeps showing them, AI can suggest fixes).
- *
- * Throws on filesystem / parse errors that ts-morph cannot recover from.
- */
-export function parseFeatureFile(filePath: string): ParseResult {
-  const project = new Project({
-    // Skip tsconfig file discovery: we only ever load this single file.
-    // Without these flags ts-morph would resolve the whole tsconfig
-    // tree, which is expensive on large repos and unnecessary for
-    // structural analysis.
-    skipAddingFilesFromTsConfig: true,
-    skipFileDependencyResolution: true,
-  });
-  const sourceFile = project.addSourceFileAtPath(filePath);
-  return parseSourceFile(sourceFile);
-}
-
-/**
- * Same as parseFeatureFile, but for SourceFiles already loaded by the
- * caller. Useful for tests + the Designer (which keeps its own Project
- * instance and avoids re-IO per parse).
- */
-export function parseSourceFile(sourceFile: SourceFile): ParseResult {
-  const setupCall = findDefineFeatureCall(sourceFile);
-  if (!setupCall) {
-    return { featureName: undefined, patterns: [], errors: [] };
-  }
-
-  const featureName = extractFeatureName(setupCall);
-  const setupCallback = extractSetupCallback(setupCall);
-  if (!setupCallback) {
-    return { featureName, patterns: [], errors: [] };
-  }
-
-  const registrarParamName = extractRegistrarParamName(setupCallback);
-  if (!registrarParamName) {
-    return { featureName, patterns: [], errors: [] };
-  }
-
-  const patterns: FeaturePattern[] = [];
-  const errors: ParseError[] = [];
-
-  walkSetupCallback(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-  walkAiStepCalls(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-  // Tie-break on filePath so cross-file registrar wrappers don't interleave by
-  // foreign line numbers alone.
-  patterns.sort((a, b) => {
-    const fileCmp = a.source.file.localeCompare(b.source.file);
-    if (fileCmp !== 0) return fileCmp;
-    return a.source.start.line - b.source.start.line;
-  });
-
-  return { featureName, patterns, errors };
-}
-
-// =============================================================================
-// Internal — locate defineFeature + setup callback
-// =============================================================================
-
-/**
- * Find the `defineFeature(name, setup)` call in the source file.
- * Convention: each feature file invokes `defineFeature` exactly once
- * at top level. If multiple calls exist (unusual outside of test
- * helpers) we take the first.
- */
-function findDefineFeatureCall(sourceFile: SourceFile): CallExpression | undefined {
-  for (const stmt of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const expr = stmt.getExpression();
-    if (expr.getText() === "defineFeature") {
-      return stmt;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Read the feature name from the first argument of `defineFeature(...)`.
- * Returns undefined when the argument is not a string literal (e.g.
- * dynamic name from a const). Designer can still load the file but the
- * AI generator will never produce such a setup.
- */
-function extractFeatureName(call: CallExpression): string | undefined {
-  const arg = call.getArguments()[0];
-  if (!arg) return undefined;
-  const literal = arg.asKind(SyntaxKind.StringLiteral);
-  if (!literal) return undefined;
-  return literal.getLiteralValue();
-}
-
-/**
- * Read the `setup` callback (second argument) from `defineFeature(...)`.
- * We only support the arrow-function form here — function expressions
- * have not turned up in any sample so far. If a future feature needs
- * them, this is the single hook to extend.
- */
-function extractSetupCallback(call: CallExpression): ArrowFunction | undefined {
-  const arg = call.getArguments()[1];
-  if (!arg) return undefined;
-  return arg.asKind(SyntaxKind.ArrowFunction);
-}
-
-/**
- * Read the parameter name of the setup callback's first parameter.
- * Idiomatic feature files call it `r`, but `(registrar) => { ... }` or
- * `(reg) => { ... }` are equally legal — the visitor must follow the
- * author's choice or it would silently miss every call.
- *
- * Returns undefined when the callback takes no parameter at all (a
- * feature that does nothing — empty patterns list, no error).
- */
-function extractRegistrarParamName(setup: ArrowFunction): string | undefined {
-  const param: ParameterDeclaration | undefined = setup.getParameters()[0];
-  if (!param) return undefined;
-  return param.getName();
-}
-
-// =============================================================================
-// Internal — walk + dispatch
-// =============================================================================
-
-/**
- * Walk the body of the setup callback and route every `<param>.<method>(...)`
- * call to the matching extractor. Helper functions / local variables /
- * imports are ignored.
- *
- * We rely on `getDescendantsOfKind` rather than walking only direct
- * children: the `r.*` API is always called on the registrar variable,
- * which the closure rules keep scoped to the setup callback. Nested
- * calls inside a writeHandler closure would not see `r` and therefore
- * cannot pose as feature-level patterns — collisions are
- * structurally impossible.
- */
-function walkSetupCallback(
-  body: Node,
-  registrarParamName: string,
-  sourceFile: SourceFile,
-  patterns: FeaturePattern[],
-  errors: ParseError[],
-  visitedWrapperDecls: Set<Node> = new Set(),
-): void {
-  for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const methodName = extractRegistrarMethodName(call, registrarParamName);
-    if (methodName) {
-      const result = dispatchExtractor(methodName, call, sourceFile);
-      if (result.kind === "pattern") {
-        patterns.push(result.pattern);
-      } else {
-        errors.push(result.error);
-      }
-      continue;
-    }
-
-    // Not a direct `<registrarParam>.<method>(...)` call. Check whether it's
-    // a registrar-wrapper call — a function that receives the registrar as
-    // a bare argument, e.g. `registerShowPonyScreens(r)`. Such wrappers are
-    // invisible to a receiver-shape match, so we resolve the callee (same
-    // file, or the declaring file of a named import — #1008) and recurse
-    // into its body with its own parameter name for the registrar slot.
-    const wrapper = resolveRegistrarWrapperCall(call, registrarParamName);
-    if (!wrapper) continue; // Free function call unrelated to the registrar — ignore.
-    if (visitedWrapperDecls.has(wrapper.declNode)) continue; // Cycle guard.
-    visitedWrapperDecls.add(wrapper.declNode);
-    // wrapper.sourceFile, not the outer `sourceFile` param: a cross-file
-    // wrapper's body lives in a different file, and sourceLocationFromNode
-    // uses whichever SourceFile it's given for both the `file` path and
-    // the line/column table — passing the wrong one silently corrupts
-    // both for every pattern found inside the wrapper.
-    walkSetupCallback(
-      wrapper.body,
-      wrapper.paramName,
-      wrapper.sourceFile,
-      patterns,
-      errors,
-      visitedWrapperDecls,
-    );
-  }
-}
-
-/**
- * Resolves a bare call like `registerShowPonyScreens(r)` to the callee's
- * body + its own parameter name for the registrar slot. The callee may be
- * declared in the same file, or imported by name from another file —
- * resolved syntactically via resolveModuleFile, which only works against a
- * real-filesystem Project; the in-memory Designer Project has no files to
- * resolve against and returns undefined there, same as any other
- * unresolvable reference. Does not follow re-exports in the target file — a
- * wrapper function is expected to be declared directly in the module it's
- * imported from.
- */
-function resolveRegistrarWrapperCall(
-  call: CallExpression,
-  registrarParamName: string,
-):
-  | {
-      readonly body: Node;
-      readonly paramName: string;
-      readonly declNode: Node;
-      readonly sourceFile: SourceFile;
-    }
-  | undefined {
-  const callee = call.getExpression().asKind(SyntaxKind.Identifier);
-  if (!callee) return undefined;
-
-  const args = call.getArguments();
-  const argIndex = args.findIndex((arg) => arg.getText() === registrarParamName);
-  if (argIndex === -1) return undefined; // Registrar not passed to this call.
-
-  const callSourceFile = call.getSourceFile();
-  const name = callee.getText();
-
-  const local = resolveWrapperDeclarationInFile(callSourceFile, name, argIndex);
-  if (local) return { ...local, sourceFile: callSourceFile };
-
-  const binding = findImportBindingForLocalName(callSourceFile, name);
-  if (!binding) return undefined;
-  const targetFile = resolveModuleFile(callSourceFile, binding.moduleSpecifier);
-  if (!targetFile) return undefined; // Unresolvable: in-memory project, external package, or missing file.
-
-  const imported = resolveWrapperDeclarationInFile(targetFile, binding.importedName, argIndex);
-  return imported ? { ...imported, sourceFile: targetFile } : undefined;
-}
-
-function resolveWrapperDeclarationInFile(
-  sourceFile: SourceFile,
-  name: string,
-  argIndex: number,
-): { readonly body: Node; readonly paramName: string; readonly declNode: Node } | undefined {
-  const fnDecl = sourceFile.getFunction(name);
-  if (fnDecl) {
-    const param = fnDecl.getParameters()[argIndex];
-    const body = fnDecl.getBody();
-    if (!param || !body) return undefined;
-    return { body, paramName: param.getName(), declNode: fnDecl };
-  }
-
-  const varDecl = sourceFile.getVariableDeclaration(name);
-  const init = varDecl?.getInitializer();
-  const literal = init ? findFunctionLiteral(init) : undefined;
-  const fnLiteral =
-    literal?.asKind(SyntaxKind.ArrowFunction) ?? literal?.asKind(SyntaxKind.FunctionExpression);
-  if (fnLiteral) {
-    const param = fnLiteral.getParameters()[argIndex];
-    if (!param) return undefined;
-    return { body: fnLiteral.getBody(), paramName: param.getName(), declNode: fnLiteral };
-  }
-
-  return undefined;
-}
-
-/**
- * Returns the method name when the call has the form
- * `<registrarParamName>.<method>(...)`, otherwise undefined.
- *
- * Reads the property-access expression on the call's left-hand side
- * and matches the receiver against the captured parameter name. Any
- * other shape (free function call, method call on something else)
- * returns undefined and is skipped by the walker.
- */
-function extractRegistrarMethodName(
-  call: CallExpression,
-  registrarParamName: string,
-): string | undefined {
-  const expr = call.getExpression();
-  const propAccess = expr.asKind(SyntaxKind.PropertyAccessExpression);
-  if (!propAccess) return undefined;
-  const receiver = propAccess.getExpression();
-  if (receiver.getText() !== registrarParamName) return undefined;
-  return propAccess.getName();
-}
-
-function resolveStepsArrayRoot(stepsInit: Expression): Node | undefined {
-  const directArray = stepsInit.asKind(SyntaxKind.ArrayLiteralExpression);
-  if (directArray) return directArray;
-
-  const pipelineCall = stepsInit.asKind(SyntaxKind.CallExpression);
-  if (pipelineCall?.getExpression().getText() !== "stepsPipeline") {
-    return undefined;
-  }
-
-  const closureArg = pipelineCall.getArguments()[0];
-  if (!closureArg) return undefined;
-  const fn = findFunctionLiteral(closureArg);
-  if (!fn) return undefined;
-
-  const fnBody =
-    fn.asKind(SyntaxKind.ArrowFunction)?.getBody() ??
-    fn.asKind(SyntaxKind.FunctionExpression)?.getBody();
-  const exprBody = fnBody?.asKind(SyntaxKind.ArrayLiteralExpression);
-  if (exprBody) return exprBody;
-
-  if (fnBody?.isKind(SyntaxKind.Block)) {
-    for (const stmt of fnBody.getStatements()) {
-      const ret = stmt.asKind(SyntaxKind.ReturnStatement);
-      const retArray = ret?.getExpression()?.asKind(SyntaxKind.ArrayLiteralExpression);
-      if (retArray) return retArray;
-    }
-  }
-
-  return undefined;
-}
-
-function collectWorkflowStepArrayRoots(body: Node): Node[] {
-  const roots: Node[] = [];
-  for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    if (call.getExpression().getText() !== "defineWorkflow") continue;
-    const obj = resolveSameFileObjectLiteral(call.getArguments()[0] ?? call);
-    if (!obj) continue;
-    const stepsInit = readObjectPropertyInitializer(obj, "steps");
-    if (!stepsInit) continue;
-    const arrayRoot = resolveStepsArrayRoot(stepsInit);
-    if (arrayRoot) roots.push(arrayRoot);
-  }
-  return roots;
-}
-
-function walkAiStepCallsInNode(
-  node: Node,
-  sourceFile: SourceFile,
-  patterns: FeaturePattern[],
-  errors: ParseError[],
-): void {
-  for (const call of node.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const callee = call.getExpression().getText();
-    switch (callee) {
-      case "aiGenerateStep": {
-        const result = extractAiGenerate(call, sourceFile);
-        if (result.kind === "pattern") patterns.push(result.pattern);
-        else errors.push(result.error);
-        break;
-      }
-      case "aiExtractStep": {
-        const result = extractAiExtract(call, sourceFile);
-        if (result.kind === "pattern") patterns.push(result.pattern);
-        else errors.push(result.error);
-        break;
-      }
-      case "aiClassifyStep": {
-        const result = extractAiClassify(call, sourceFile);
-        if (result.kind === "pattern") patterns.push(result.pattern);
-        else errors.push(result.error);
-        break;
-      }
-      default:
-        break;
-    }
-  }
-}
-
-function walkAiStepCalls(
-  body: Node,
-  registrarParamName: string,
-  sourceFile: SourceFile,
-  patterns: FeaturePattern[],
-  errors: ParseError[],
-  visitedWrapperDecls: Set<Node> = new Set(),
-): void {
-  for (const arrayRoot of collectWorkflowStepArrayRoots(body)) {
-    walkAiStepCallsInNode(arrayRoot, sourceFile, patterns, errors);
-  }
-
-  for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const wrapper = resolveRegistrarWrapperCall(call, registrarParamName);
-    if (!wrapper) continue;
-    if (visitedWrapperDecls.has(wrapper.declNode)) continue;
-    visitedWrapperDecls.add(wrapper.declNode);
-    walkAiStepCalls(
-      wrapper.body,
-      wrapper.paramName,
-      wrapper.sourceFile,
-      patterns,
-      errors,
-      visitedWrapperDecls,
-    );
-  }
-}
-
-// =============================================================================
-// Internal — pattern extractors (skeleton, implementation in C1.5)
-// =============================================================================
-
-/**
- * Route an `<r>.<method>(...)` call to its concrete extractor. New
- * r.* APIs → new case + new extractor + new pattern type in patterns.ts.
- * The discriminated union forces consumers (Designer, AI patcher) to
- * commit to the new kind via compile errors.
- *
- * Skeleton: every recognised method currently returns an UnknownPattern
- * with the right method name. C1.5 replaces the cases with concrete
- * extractors one at a time.
- */
-function dispatchExtractor(
-  methodName: string,
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<FeaturePattern> {
-  switch (methodName) {
-    // Round 1 — simplest static patterns
-    case "requires":
-      return extractRequires(call, sourceFile);
-    case "optionalRequires":
-      return extractOptionalRequires(call, sourceFile);
-    case "readsConfig":
-      return extractReadsConfig(call, sourceFile);
-    case "systemScope":
-      return extractSystemScope(call, sourceFile);
-    case "toggleable":
-      return extractToggleable(call, sourceFile);
-    case "describe":
-      return extractDescribe(call, sourceFile);
-    case "uiHints":
-      return extractUiHints(call, sourceFile);
-    // Round 2 — object-literal-based static patterns
-    case "entity":
-      return extractEntity(call, sourceFile);
-    case "relation":
-      return extractRelation(call, sourceFile);
-    case "nav":
-      return extractNav(call, sourceFile);
-    case "workspace":
-      return extractWorkspace(call, sourceFile);
-    // Round 3 — complex static patterns
-    case "config":
-      return extractConfig(call, sourceFile);
-    case "translations":
-      return extractTranslations(call, sourceFile);
-    case "metric":
-      return extractMetric(call, sourceFile);
-    case "secret":
-      return extractSecret(call, sourceFile);
-    case "claimKey":
-      return extractClaimKey(call, sourceFile);
-    case "referenceData":
-      return extractReferenceData(call, sourceFile);
-    case "useExtension":
-      return extractUseExtension(call, sourceFile);
-    // Round 4 — mixed (header + body) patterns
-    case "hook":
-      return extractHook(call, sourceFile);
-    case "authClaims":
-      return extractAuthClaims(call, sourceFile);
-    case "writeHandler":
-      return extractWriteHandler(call, sourceFile);
-    case "queryHandler":
-      return extractQueryHandler(call, sourceFile);
-    case "streamHandler":
-      return extractStreamHandler(call, sourceFile);
-    case "job":
-      return extractJob(call, sourceFile);
-    case "httpRoute":
-      return extractHttpRoute(call, sourceFile);
-    case "defineEvent":
-      return extractDefineEvent(call, sourceFile);
-    case "notification":
-      return extractNotification(call, sourceFile);
-    case "projection":
-      return extractProjection(call, sourceFile);
-    case "multiStreamProjection":
-      return extractMultiStreamProjection(call, sourceFile);
-    case "screen":
-      return extractScreen(call, sourceFile);
-    // Round 5 — opaque patterns
-    case "extendsRegistrar":
-      return extractExtendsRegistrar(call, sourceFile);
-    case "usesApi":
-      return extractUsesApi(call, sourceFile);
-    case "exposesApi":
-      return extractExposesApi(call, sourceFile);
-    case "storeTable":
-      return extractStoreTable(call, sourceFile);
-    // Round 6 — Tree-Actions pattern
-    case "treeActions":
-      return extractTreeActions(call, sourceFile);
-    // Round 7 — env-schema contract (opaque, Zod-expression argument)
-    case "envSchema":
-      return extractEnvSchema(call, sourceFile);
-    // Unknown method — UnknownPattern signal so Designer/AI surface it
-    // as "custom call" without losing the source location.
-    default:
-      return {
-        kind: "pattern",
-        pattern: makeUnknownPattern(methodName, call, sourceFile),
-      };
-  }
-}
-
-function makeUnknownPattern(
-  methodName: string,
-  call: CallExpression,
-  sourceFile: SourceFile,
-): UnknownPattern {
-  return {
-    kind: "unknown",
-    methodName,
-    source: sourceLocationFromNode(call, sourceFile),
-  };
-}