@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

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

@@ -0,0 +1,302 @@
+import type { LifecycleHookType } from "../constants.js";
+import type { ConfigKeyDefinition, ConfigKeyType, JobDefinition, ReferenceDataDef, RunIn, TranslationKeys } from "../types/config.js";
+import type { MetricOptions, SecretOptions } from "../types/feature.js";
+import type { EntityDefinition } from "../types/fields.js";
+import type { AccessRule, AgentHandlerHints, ClaimKeyType, EscapeHatchDeclaration, RateLimitDeclaration } from "../types/handlers.js";
+import type { HookPhase } from "../types/hooks.js";
+import type { HttpRouteMethod } from "../types/http-route.js";
+import type { NavDefinition } from "../types/nav.js";
+import type { MspErrorMode } from "../types/projection.js";
+import type { RelationDefinition } from "../types/relations.js";
+import type { ScreenDefinition } from "../types/screen.js";
+import type { TreeActionDef } from "../types/tree-node.js";
+import type { WorkspaceDefinition } from "../types/workspace.js";
+import type { RawRefSentinel } from "./extractors/shared.js";
+import type { SourceLocation } from "./source-location.js";
+export type EntityPattern = {
+    readonly kind: "entity";
+    readonly source: SourceLocation;
+    readonly entityName: string;
+    readonly definition: EntityDefinition;
+};
+export type RelationPattern = {
+    readonly kind: "relation";
+    readonly source: SourceLocation;
+    readonly entityName: string;
+    readonly relationName: string;
+    readonly definition: RelationDefinition;
+};
+export type NavPattern = {
+    readonly kind: "nav";
+    readonly source: SourceLocation;
+    readonly definition: NavDefinition;
+};
+export type WorkspacePattern = {
+    readonly kind: "workspace";
+    readonly source: SourceLocation;
+    readonly definition: WorkspaceDefinition;
+};
+export type ConfigPattern = {
+    readonly kind: "config";
+    readonly source: SourceLocation;
+    readonly keys: Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>;
+};
+export type TranslationsPattern = {
+    readonly kind: "translations";
+    readonly source: SourceLocation;
+    readonly keys: TranslationKeys;
+};
+export type RequiresPattern = {
+    readonly kind: "requires";
+    readonly source: SourceLocation;
+    readonly featureNames: readonly string[];
+};
+export type OptionalRequiresPattern = {
+    readonly kind: "optionalRequires";
+    readonly source: SourceLocation;
+    readonly featureNames: readonly string[];
+};
+export type SystemScopePattern = {
+    readonly kind: "systemScope";
+    readonly source: SourceLocation;
+};
+export type ToggleablePattern = {
+    readonly kind: "toggleable";
+    readonly source: SourceLocation;
+    readonly default: boolean;
+};
+export type DescribePattern = {
+    readonly kind: "describe";
+    readonly source: SourceLocation;
+    readonly text: string;
+};
+export type UiHintsPattern = {
+    readonly kind: "uiHints";
+    readonly source: SourceLocation;
+};
+export type MetricPattern = {
+    readonly kind: "metric";
+    readonly source: SourceLocation;
+    readonly shortName: string;
+    readonly options: MetricOptions;
+};
+export type SecretPattern = {
+    readonly kind: "secret";
+    readonly source: SourceLocation;
+    readonly shortName: string;
+    readonly options: SecretOptions;
+};
+export type ClaimKeyPattern = {
+    readonly kind: "claimKey";
+    readonly source: SourceLocation;
+    readonly shortName: string;
+    readonly claimType: ClaimKeyType;
+};
+export type ReferenceDataPattern = {
+    readonly kind: "referenceData";
+    readonly source: SourceLocation;
+    readonly entityName: string;
+    readonly data: ReferenceDataDef["data"];
+    readonly upsertKey?: string;
+};
+export type ReadsConfigPattern = {
+    readonly kind: "readsConfig";
+    readonly source: SourceLocation;
+    readonly qualifiedKeys: readonly string[];
+};
+export type UseExtensionPattern = {
+    readonly kind: "useExtension";
+    readonly source: SourceLocation;
+    readonly extensionName: string;
+    readonly extensionNameRaw?: string;
+    readonly entityName: string;
+    readonly options?: Readonly<Record<string, unknown>>;
+};
+export type TreeActionsPattern = {
+    readonly kind: "treeActions";
+    readonly source: SourceLocation;
+    readonly definitions: Readonly<Record<string, TreeActionDef>>;
+};
+export type OpaquePropMap = Readonly<Record<string, SourceLocation>>;
+export declare const SCREEN_OPAQUE_MARKER: "$opaque";
+export type ScreenOpaqueMarker = typeof SCREEN_OPAQUE_MARKER;
+export type ScreenPattern = {
+    readonly kind: "screen";
+    readonly source: SourceLocation;
+    readonly definition: ScreenDefinition;
+    readonly opaqueProps: OpaquePropMap;
+};
+export type WriteHandlerPattern = {
+    readonly kind: "writeHandler";
+    readonly source: SourceLocation;
+    readonly handlerName?: string;
+    readonly schemaSource?: SourceLocation;
+    readonly handlerBody?: SourceLocation;
+    readonly access?: AccessRule | RawRefSentinel;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints | RawRefSentinel;
+    readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+    readonly unsafeSkipTransitionGuard?: boolean;
+    readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
+};
+export type QueryHandlerPattern = {
+    readonly kind: "queryHandler";
+    readonly source: SourceLocation;
+    readonly handlerName?: string;
+    readonly schemaSource?: SourceLocation;
+    readonly handlerBody?: SourceLocation;
+    readonly access?: AccessRule | RawRefSentinel;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints | RawRefSentinel;
+    readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+    readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
+};
+export type StreamHandlerPattern = {
+    readonly kind: "streamHandler";
+    readonly source: SourceLocation;
+    readonly handlerName?: string;
+    readonly schemaSource?: SourceLocation;
+    readonly handlerBody?: SourceLocation;
+    readonly access?: AccessRule | RawRefSentinel;
+    readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+    readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
+};
+export type HookPattern = {
+    readonly kind: "hook";
+    readonly source: SourceLocation;
+    readonly hookType: LifecycleHookType | "validation";
+    readonly target: string | readonly string[] | {
+        readonly allOf: string;
+    };
+    readonly fnBody: SourceLocation;
+    readonly phase?: HookPhase;
+    readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
+};
+export type JobPattern = {
+    readonly kind: "job";
+    readonly source: SourceLocation;
+    readonly jobName: string;
+    readonly options: Omit<JobDefinition, "name" | "handler">;
+    readonly handlerBody: SourceLocation;
+};
+export type NotificationPattern = {
+    readonly kind: "notification";
+    readonly source: SourceLocation;
+    readonly notificationName: string;
+    readonly trigger: {
+        readonly on: string;
+    };
+    readonly recipientBody: SourceLocation;
+    readonly dataBody: SourceLocation;
+    readonly templates?: Readonly<Record<string, SourceLocation>>;
+};
+export type AuthClaimsPattern = {
+    readonly kind: "authClaims";
+    readonly source: SourceLocation;
+    readonly fnBody: SourceLocation;
+};
+export type HttpRoutePattern = {
+    readonly kind: "httpRoute";
+    readonly source: SourceLocation;
+    readonly method: HttpRouteMethod;
+    readonly path: string;
+    readonly anonymous: boolean;
+    readonly handlerBody: SourceLocation;
+};
+export type ProjectionPattern = {
+    readonly kind: "projection";
+    readonly source: SourceLocation;
+    readonly name: string;
+    readonly sourceEntity: string | readonly string[];
+    readonly applyBodies: Readonly<Record<string, SourceLocation>>;
+};
+export type MultiStreamProjectionPattern = {
+    readonly kind: "multiStreamProjection";
+    readonly source: SourceLocation;
+    readonly name: string;
+    readonly applyBodies: Readonly<Record<string, SourceLocation>>;
+    readonly errorMode?: MspErrorMode;
+    readonly runIn?: RunIn;
+    readonly delivery?: "shared" | "per-instance";
+};
+export type DefineEventPattern = {
+    readonly kind: "defineEvent";
+    readonly source: SourceLocation;
+    readonly eventName: string;
+    readonly eventNameRaw?: string;
+    readonly schemaSource: SourceLocation;
+    readonly version?: number;
+    readonly piiFields: SourceLocation;
+    readonly migrations?: Readonly<Record<string, SourceLocation>>;
+};
+export type ExtendsRegistrarPattern = {
+    readonly kind: "extendsRegistrar";
+    readonly source: SourceLocation;
+    readonly extensionName: string;
+    readonly extensionNameRaw?: string;
+    readonly defBody: SourceLocation;
+};
+export type UsesApiPattern = {
+    readonly kind: "usesApi";
+    readonly source: SourceLocation;
+    readonly apiName: string;
+};
+export type ExposesApiPattern = {
+    readonly kind: "exposesApi";
+    readonly source: SourceLocation;
+    readonly apiName: string;
+};
+export type EnvSchemaPattern = {
+    readonly kind: "envSchema";
+    readonly source: SourceLocation;
+    readonly schemaBody: SourceLocation;
+};
+/** Live-editable policy defaults for an AI pipeline step instance (#256). */
+export type AiStepPolicy = {
+    readonly enabled: boolean;
+    readonly providerId?: string;
+    readonly model?: string;
+    readonly params: Record<string, unknown>;
+};
+/** Preserves an unresolvable argument reference across parse → render (#998). */
+export type AiStepOpaqueArgs = {
+    readonly __raw: string;
+};
+type AiStepCommonPatternFields = {
+    readonly source: SourceLocation;
+    /** Whole-args reference when the spec is not an inline/same-file object. */
+    readonly argsSource?: AiStepOpaqueArgs;
+    readonly stepKey?: string | AiStepOpaqueArgs;
+    readonly promptKey?: string | AiStepOpaqueArgs;
+    readonly promptFallback?: string | AiStepOpaqueArgs;
+    readonly defaults?: AiStepPolicy | AiStepOpaqueArgs;
+    readonly paramsSchemaSource?: SourceLocation;
+};
+export type AiGeneratePattern = AiStepCommonPatternFields & {
+    readonly kind: "ai.generate";
+    readonly inputBody?: SourceLocation;
+};
+export type AiExtractPattern = AiStepCommonPatternFields & {
+    readonly kind: "ai.extract";
+    readonly outputSchemaSource?: SourceLocation;
+    readonly instructionsBody?: SourceLocation;
+    readonly documentBody?: SourceLocation;
+};
+export type AiClassifyPattern = AiStepCommonPatternFields & {
+    readonly kind: "ai.classify";
+    readonly actions?: readonly {
+        readonly type: string;
+        readonly description: string;
+    }[];
+    readonly inputBody?: SourceLocation;
+};
+export type UnknownPattern = {
+    readonly kind: "unknown";
+    readonly source: SourceLocation;
+    readonly methodName: string;
+};
+export type FeaturePattern = EntityPattern | RelationPattern | NavPattern | WorkspacePattern | ConfigPattern | TranslationsPattern | RequiresPattern | OptionalRequiresPattern | SystemScopePattern | ToggleablePattern | DescribePattern | UiHintsPattern | MetricPattern | SecretPattern | ClaimKeyPattern | ReferenceDataPattern | ReadsConfigPattern | UseExtensionPattern | UsesApiPattern | ExposesApiPattern | TreeActionsPattern | ScreenPattern | WriteHandlerPattern | QueryHandlerPattern | StreamHandlerPattern | HookPattern | JobPattern | NotificationPattern | AuthClaimsPattern | HttpRoutePattern | ProjectionPattern | MultiStreamProjectionPattern | DefineEventPattern | ExtendsRegistrarPattern | EnvSchemaPattern | AiGeneratePattern | AiExtractPattern | AiClassifyPattern | UnknownPattern;
+export type FeaturePatternKind = FeaturePattern["kind"];
+export type Editability = "static" | "mixed" | "opaque";
+export declare function getEditability(pattern: FeaturePattern): Editability;
+export {};

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

@@ -0,0 +1,113 @@
+// FeaturePattern — typed representation of an `r.*` call inside a
+// feature file. The AST visitor (parse.ts) walks the
+// `defineFeature(name, (r) => { ... })` setup callback and yields one
+// FeaturePattern per recognised call.
+//
+// **Doc single-source:** THIS file is the canonical pattern reference
+// (mirrored into docs/corpus). The FeatureRegistrar JSDoc in
+// types/feature.ts stays a short pointer — duplicating semantics there
+// has already drifted once; verify any "checks at boot" claim against
+// engine/boot-validator/* before writing it down.
+//
+// **Design principle:**
+//
+//   - Whatever the Designer/AI can edit declaratively → typed static
+//     fields, reusing the existing engine/types definitions so the
+//     pattern shape never drifts from the runtime contract.
+//   - Whatever carries closures/code → SourceLocation pointing at the
+//     opaque region. The Designer renders that as a read-only code
+//     block; the AI patcher overwrites the span verbatim.
+//
+// **Coverage = 100%.** Calls we don't recognise become UnknownPattern
+// (the Designer shows "custom call", AI leaves them alone). Custom
+// TypeScript code BETWEEN `r.*` calls (helpers, local consts, imports)
+// is not extracted — it stays in the file buffer and survives every
+// patch unchanged.
+//
+// **Extension point.** Adding a new r.* API → new pattern type here +
+// new extractor in parse.ts. The discriminated union forces every
+// consumer (Designer, AI patcher, MCP server) to handle the new kind
+// at compile time.
+//
+// **Naming convention.** Pattern `kind` matches the r.* method name
+// 1:1 (e.g. `r.writeHandler` → `kind: "writeHandler"`). No kebab/camel
+// translation layer.
+//
+// **Adding a new FeaturePattern kind — full consumer cascade.** The
+// extension-point is wider than just this file + the parser. Update
+// ALL of these when introducing a new r.* API, otherwise tests/checks
+// catch the drift but the call-site jumps across files:
+//   1. patterns.ts (this file): Pattern type + add to FeaturePattern
+//      union + getEditability switch
+//   2. feature-ast/extractors.ts: extract<Kind> function + import in
+//      patterns-import-block
+//   3. feature-ast/parse.ts: dispatcher case + import
+//   4. feature-ast/render.ts: render<Kind> function + import + switch
+//      case
+//   5. feature-ast/patch.ts: PatternId variant; if singleton-per-feature
+//      add to SINGLETON_KINDS; callMatchesId case
+//   6. pattern-library/library.ts: <kind>Schema + entry in
+//      PATTERN_LIBRARY map
+//   7. pattern-library/__tests__/library.test.ts: ALL_KINDS array +
+//      makePlaceholderPattern case
+// TS-exhaustiveness catches most omissions automatically (1, 3, 4, 5,
+// 7-via-makePlaceholderPattern), but the runtime-checked maps in 6 +
+// the ALL_KINDS array in 7 are silent if forgotten — pin them with the
+// library.test.ts coverage tests.
+// Marker emitted in `ScreenPattern.definition` wherever a closure or
+// unresolvable identifier sat in the source. Designer renderers compare
+// against this constant to decide "form vs read-only span" — the actual
+// SourceLocation lives at the matching path in `opaqueProps`.
+export const SCREEN_OPAQUE_MARKER = "$opaque";
+export function getEditability(pattern) {
+    switch (pattern.kind) {
+        case "entity":
+        case "relation":
+        case "nav":
+        case "workspace":
+        case "config":
+        case "translations":
+        case "requires":
+        case "optionalRequires":
+        case "systemScope":
+        case "toggleable":
+        case "describe":
+        case "metric":
+        case "secret":
+        case "claimKey":
+        case "referenceData":
+        case "readsConfig":
+        case "useExtension":
+        case "usesApi":
+        case "exposesApi":
+        case "treeActions":
+            return "static";
+        case "screen":
+        case "writeHandler":
+        case "queryHandler":
+        case "streamHandler":
+        case "hook":
+        case "job":
+        case "notification":
+        case "httpRoute":
+        case "projection":
+        case "multiStreamProjection":
+        case "defineEvent":
+        case "ai.generate":
+        case "ai.extract":
+        case "ai.classify":
+            return "mixed";
+        case "authClaims":
+        case "extendsRegistrar":
+        case "envSchema":
+        case "uiHints":
+        case "unknown":
+            return "opaque";
+        default: {
+            // Exhaustiveness guard — adding a new pattern kind without
+            // updating this switch produces a compile error here.
+            const _exhaustive = pattern;
+            return _exhaustive;
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+import type { FeaturePattern } from "./patterns.js";
+export declare const FEATURE_FILE_VERSION: 1;
+export declare const VERSION_HEADER: string;
+/**
+ * Render a single FeaturePattern back to TypeScript source — a `r.<kind>(...)`
+ * call in canonical Object-Form. The result is a single statement WITHOUT a
+ * trailing newline; callers compose statements with their own joiner.
+ */
+export declare function renderPattern(pattern: FeaturePattern): string;
+/**
+ * Render a JSON-compatible value as TypeScript source. Matches what
+ * `readDataLiteralNode` accepts on the parser side: strings, numbers,
+ * booleans, null, arrays, plain objects. Unsupported values (functions,
+ * undefined) throw — they should never reach here for a static pattern.
+ *
+ * Keys are quoted only when they are not valid JS identifiers. The
+ * renderer prefers single-line output for short arrays/objects (≤80
+ * chars including indent and no nested newlines) and falls back to
+ * multi-line otherwise — biome-stable in both branches.
+ */
+export declare function renderValue(value: unknown, indent?: number): string;
+export type RenderFeatureFileInput = {
+    readonly featureName: string;
+    readonly patterns: readonly FeaturePattern[];
+    /** Extra import lines emitted between the version header and defineFeature.
+     *  Defaults to the minimum: defineFeature + zod. */
+    readonly imports?: readonly string[];
+};
+/**
+ * Render a complete feature-file: schema-version header, imports, the
+ * defineFeature call wrapping every pattern in source order. The output
+ * is biome-format-stable so callers can persist it directly.
+ */
+export declare function renderFeatureFile(input: RenderFeatureFileInput): string;
+/**
+ * Prefix every non-empty line of `text` with `prefix`. Re-used from the
+ * patcher (patch.ts imports this) so indent helpers stay in one place
+ * — when canonical-form indentation conventions ever change, only this
+ * function needs to follow.
+ */
+export declare function indent(text: string, prefix: string): string;
+/**
+ * Indentation prefix used inside `defineFeature((r) => { ... })` for
+ * every top-level r.* statement. Two-space convention matches biome's
+ * default and the parse-happy-path test fixture.
+ */
+export declare const PATTERN_INDENT = "  ";