@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

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

@@ -0,0 +1,464 @@
+// 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 { Project, SyntaxKind } from "ts-morph";
+import { 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/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 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) {
+    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 — #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, 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 (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, call, sourceFile) {
+    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, call, sourceFile) {
+    return {
+        kind: "unknown",
+        methodName,
+        source: sourceLocationFromNode(call, sourceFile),
+    };
+}

package/dist/engine/feature-ast/patch.d.ts

@@ -0,0 +1,207 @@
+import { type SourceFile } from "ts-morph";
+import type { FeaturePattern, QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "./patterns.js";
+/**
+ * Identifier used by replace/remove. Discriminated union: each pattern
+ * kind names the property the patcher must match against. Adding a new
+ * pattern kind requires a new entry here so the type system forces the
+ * call-site to think about identity (or fall through to "first call of
+ * this kind" via the singleton helpers below).
+ */
+export type PatternId = {
+    readonly kind: "entity";
+    readonly entityName: string;
+} | {
+    readonly kind: "relation";
+    readonly entityName: string;
+    readonly relationName: string;
+} | {
+    readonly kind: "nav";
+    readonly id: string;
+} | {
+    readonly kind: "workspace";
+    readonly id: string;
+} | {
+    readonly kind: "screen";
+    readonly id: string;
+} | {
+    readonly kind: "writeHandler";
+    readonly handlerName: string;
+} | {
+    readonly kind: "queryHandler";
+    readonly handlerName: string;
+} | {
+    readonly kind: "streamHandler";
+    readonly handlerName: string;
+} | {
+    readonly kind: "hook";
+    readonly hookType: string;
+    readonly target: string | {
+        readonly allOf: string;
+    };
+} | {
+    readonly kind: "metric";
+    readonly shortName: string;
+} | {
+    readonly kind: "secret";
+    readonly shortName: string;
+} | {
+    readonly kind: "claimKey";
+    readonly shortName: string;
+} | {
+    readonly kind: "referenceData";
+    readonly entityName: string;
+} | {
+    readonly kind: "useExtension";
+    readonly extensionName: string;
+    readonly entityName: string;
+} | {
+    readonly kind: "job";
+    readonly jobName: string;
+} | {
+    readonly kind: "notification";
+    readonly notificationName: string;
+} | {
+    readonly kind: "httpRoute";
+    readonly method: string;
+    readonly path: string;
+} | {
+    readonly kind: "projection";
+    readonly name: string;
+} | {
+    readonly kind: "multiStreamProjection";
+    readonly name: string;
+} | {
+    readonly kind: "defineEvent";
+    readonly eventName: string;
+} | {
+    readonly kind: "extendsRegistrar";
+    readonly extensionName: string;
+} | {
+    readonly kind: "ai.generate";
+    readonly stepKey: string;
+} | {
+    readonly kind: "ai.extract";
+    readonly stepKey: string;
+} | {
+    readonly kind: "ai.classify";
+    readonly stepKey: string;
+} | {
+    readonly kind: "requires";
+} | {
+    readonly kind: "optionalRequires";
+} | {
+    readonly kind: "readsConfig";
+} | {
+    readonly kind: "systemScope";
+} | {
+    readonly kind: "toggleable";
+} | {
+    readonly kind: "describe";
+} | {
+    readonly kind: "uiHints";
+} | {
+    readonly kind: "config";
+} | {
+    readonly kind: "translations";
+} | {
+    readonly kind: "authClaims";
+} | {
+    readonly kind: "treeActions";
+};
+export type WriteHandlerHeaderKey = Exclude<keyof WriteHandlerPattern, "kind" | "source" | "handlerName" | "schemaSource" | "handlerBody">;
+export type QueryHandlerHeaderKey = Exclude<keyof QueryHandlerPattern, "kind" | "source" | "handlerName" | "schemaSource" | "handlerBody">;
+export type StreamHandlerHeaderKey = Exclude<keyof StreamHandlerPattern, "kind" | "source" | "handlerName" | "schemaSource" | "handlerBody">;
+export type HandlerHeaderUpdate = {
+    readonly op: "update";
+    readonly id: Extract<PatternId, {
+        readonly kind: "writeHandler";
+    }>;
+    readonly set: Partial<Pick<WriteHandlerPattern, WriteHandlerHeaderKey>>;
+    readonly unset?: readonly Exclude<WriteHandlerHeaderKey, "access">[];
+} | {
+    readonly op: "update";
+    readonly id: Extract<PatternId, {
+        readonly kind: "queryHandler";
+    }>;
+    readonly set: Partial<Pick<QueryHandlerPattern, QueryHandlerHeaderKey>>;
+    readonly unset?: readonly Exclude<QueryHandlerHeaderKey, "access">[];
+} | {
+    readonly op: "update";
+    readonly id: Extract<PatternId, {
+        readonly kind: "streamHandler";
+    }>;
+    readonly set: Partial<Pick<StreamHandlerPattern, StreamHandlerHeaderKey>>;
+    readonly unset?: readonly Exclude<StreamHandlerHeaderKey, "access">[];
+};
+export type PatternChange = {
+    readonly op: "add";
+    readonly pattern: FeaturePattern;
+} | {
+    readonly op: "replace";
+    readonly id: PatternId;
+    readonly pattern: FeaturePattern;
+} | {
+    readonly op: "remove";
+    readonly id: PatternId;
+} | HandlerHeaderUpdate;
+/**
+ * Apply a sequence of changes to the source file in-place. The list is
+ * processed in order; replace/remove failures (id not found) throw so
+ * callers can react explicitly — silent no-ops would mask design bugs
+ * in the Designer/AI generator. Adds always succeed.
+ *
+ * The function does NOT save the file — `sourceFile.saveSync()` (or the
+ * caller's persistence layer) is expected to follow.
+ */
+export declare function applyChanges(sourceFile: SourceFile, changes: readonly PatternChange[]): void;
+/**
+ * Low-level escape hatch: append a hand-built FeaturePattern at the end
+ * of the setup callback's body. **Prefer the typed `add{Kind}` methods
+ * on `createFeaturePatcher(sf)`** — they take natural args, build the
+ * FeaturePattern internally, and avoid SourceLocation boilerplate.
+ *
+ * Use this directly when:
+ *   - Migrating a parsed pattern from another file (already-built
+ *     FeaturePattern object on hand)
+ *   - The pattern kind isn't yet covered by a typed `add{Kind}`
+ *
+ * The pattern is rendered (canonical Object-Form) and inserted as the
+ * last statement, separated from the previous one by a blank line —
+ * biome-stable formatting that matches the renderFeatureFile output.
+ */
+export declare function addPattern(sourceFile: SourceFile, pattern: FeaturePattern): void;
+/**
+ * Find the call matching `id` and replace the entire CallExpression text
+ * with the rendered version of `pattern`. The replacement is reindented
+ * to match the original call's column so existing helpers/comments
+ * around it stay aligned. Throws when no call matches — callers must
+ * handle that case explicitly.
+ */
+export declare function replacePattern(sourceFile: SourceFile, id: PatternId, pattern: FeaturePattern): void;
+/**
+ * Find the call matching `id` and remove it together with its trailing
+ * newline. Comments belonging to the pattern are unaffected only when
+ * they live BEFORE the call as line-leading trivia — those leading
+ * comments are kept (they may belong to surrounding code, the patcher
+ * can't disambiguate without semantic markers). Inline comments on the
+ * same line as the call are removed with the call.
+ */
+export declare function removePattern(sourceFile: SourceFile, id: PatternId): void;
+/**
+ * Apply a `HandlerHeaderUpdate` to the header fields named in `set`/`unset`
+ * only, via targeted text edits — `schemaSource`, `handlerBody`, comments,
+ * and every unnamed field stay byte-identical (narrower than replacePattern).
+ */
+export declare function updatePattern(sourceFile: SourceFile, change: HandlerHeaderUpdate): void;
+/**
+ * Singleton kinds: a feature has at most one of each. The Boot-Validator
+ * rejects features that declare two `r.requires(...)` etc. — the patcher
+ * asserts the same invariant so a corrupt source file produces an
+ * explicit error here, not a silent first-match win.
+ *
+ * Exported so the pattern-library tests + downstream consumers
+ * (Designer, AI-Builder) share one source-of-truth — duplicating this
+ * set would let the library's `singleton: true` flags drift silently
+ * from the patcher's enforcement.
+ */
+export declare const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]>;