@cosmicdrift/kumiko-framework 0.389.0 → 0.390.1

package/dist/engine/feature-ast/parse.js

@@ -1,485 +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:** interface fixed, extractors are TODO.
-// Per-pattern extractors fill in iteratively — each iteration adds
-// one extractor + a focused test.
-import { Project, SyntaxKind } from "ts-morph";
-import { extractAdoptsBundledLists, extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractSecretNamespace, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
-import { sourceLocationFromNode } from "./source-location.js";
-/**
- * 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) {
-    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) {
-    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 = [];
-    const errors = [];
-    walkSetupCallback(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-    walkAiStepCalls(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-    // Tie-break on the path relative to the entry file's directory so cross-file
-    // registrar wrappers don't interleave by foreign line numbers alone, without
-    // the order depending on where the repo is checked out (worktrees).
-    const parseRoot = sourceFile.getDirectoryPath();
-    patterns.sort((a, b) => {
-        const fileCmp = relativePosixPath(parseRoot, a.source.file).localeCompare(relativePosixPath(parseRoot, b.source.file));
-        if (fileCmp !== 0)
-            return fileCmp;
-        return a.source.start.line - b.source.start.line;
-    });
-    return { featureName, patterns, errors };
-}
-// node:path is avoided: the Designer runs this against an in-memory file
-// system outside Node. ts-morph paths are always posix-style.
-export function relativePosixPath(fromDirectory, filePath) {
-    const fromSegments = fromDirectory.split("/").filter(Boolean);
-    const fileSegments = filePath.split("/").filter(Boolean);
-    let common = 0;
-    while (common < fromSegments.length &&
-        common < fileSegments.length - 1 &&
-        fromSegments[common] === fileSegments[common]) {
-        common += 1;
-    }
-    return [...fromSegments.slice(common).map(() => ".."), ...fileSegments.slice(common)].join("/");
-}
-// =============================================================================
-// 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) {
-    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) {
-    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) {
-    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) {
-    const param = 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, registrarParamName, sourceFile, patterns, errors, visitedWrapperDecls = new Set()) {
-    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) 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, registrarParamName) {
-    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, name, argIndex) {
-    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, registrarParamName) {
-    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) {
-    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) {
-    const roots = [];
-    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, sourceFile, patterns, errors) {
-    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, registrarParamName, sourceFile, patterns, errors, visitedWrapperDecls = new Set()) {
-    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
-// =============================================================================
-/**
- * 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. Extractors replace the cases with concrete
- * implementations one at a time.
- */
-function dispatchExtractor(methodName, call, sourceFile) {
-    switch (methodName) {
-        // 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);
-        case "adoptsBundledLists":
-            return extractAdoptsBundledLists(call, sourceFile);
-        // 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);
-        // 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 "secretNamespace":
-            return extractSecretNamespace(call, sourceFile);
-        case "claimKey":
-            return extractClaimKey(call, sourceFile);
-        case "referenceData":
-            return extractReferenceData(call, sourceFile);
-        case "useExtension":
-            return extractUseExtension(call, sourceFile);
-        // 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);
-        // 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);
-        case "bootCheck":
-            return extractBootCheck(call, sourceFile);
-        // Tree-Actions pattern
-        case "treeActions":
-            return extractTreeActions(call, sourceFile);
-        // 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, call, sourceFile) {
-    return {
-        kind: "unknown",
-        methodName,
-        source: sourceLocationFromNode(call, sourceFile),
-    };
-}