@cosmicdrift/kumiko-framework 0.389.0 → 0.390.1

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

@@ -1,322 +0,0 @@
-import type { LifecycleHookType } from "../constants.ts";
-import type { ConfigKeyDefinition, ConfigKeyType, JobDefinition, ReferenceDataDef, RunIn, TranslationKeys } from "../types/config.ts";
-import type { MetricOptions, SecretNamespaceOptions, SecretOptions } from "../types/feature.ts";
-import type { EntityDefinition } from "../types/fields.ts";
-import type { AccessRule, AgentHandlerHints, ClaimKeyType, EscapeHatchDeclaration, PayloadRateLimitOption, RateLimitDeclaration } from "../types/handlers.ts";
-import type { HookPhase } from "../types/hooks.ts";
-import type { HttpRouteMethod } from "../types/http-route.ts";
-import type { NavDefinition } from "../types/nav.ts";
-import type { MspErrorMode } from "../types/projection.ts";
-import type { RelationDefinition } from "../types/relations.ts";
-import type { ScreenDefinition } from "../types/screen.ts";
-import type { TreeActionDef } from "../types/tree-node.ts";
-import type { WorkspaceDefinition } from "../types/workspace.ts";
-import type { RawRefSentinel } from "./extractors/shared.ts";
-import type { SourceLocation } from "./source-location.ts";
-export type EntityPattern = {
-    readonly kind: "entity";
-    readonly source: SourceLocation;
-    readonly entityName: string;
-    readonly definition: EntityDefinition;
-    readonly backingTable?: RawRefSentinel;
-};
-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 AdoptsBundledListsPattern = {
-    readonly kind: "adoptsBundledLists";
-    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 SecretNamespacePattern = {
-    readonly kind: "secretNamespace";
-    readonly source: SourceLocation;
-    readonly shortName: string;
-    readonly options: SecretNamespaceOptions;
-};
-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 additionalRateLimits?: readonly PayloadRateLimitOption[] | 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. */
-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. */
-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 | AdoptsBundledListsPattern | ToggleablePattern | DescribePattern | UiHintsPattern | MetricPattern | SecretPattern | SecretNamespacePattern | 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 MembersByKind<U extends {
-    readonly kind: string;
-}> = {
-    readonly [K in U["kind"]]: Extract<U, {
-        readonly kind: K;
-    }>;
-};
-export type FeaturePatternOfKind = MembersByKind<FeaturePattern>;
-export type Editability = "static" | "mixed" | "opaque";
-export declare function getEditability(pattern: FeaturePattern): Editability;
-export {};

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

@@ -1,107 +0,0 @@
-// 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";
-const EDITABILITY_BY_KIND = {
-    entity: "static",
-    relation: "static",
-    nav: "static",
-    workspace: "static",
-    config: "static",
-    translations: "static",
-    requires: "static",
-    optionalRequires: "static",
-    systemScope: "static",
-    toggleable: "static",
-    describe: "static",
-    metric: "static",
-    secret: "static",
-    secretNamespace: "static",
-    claimKey: "static",
-    referenceData: "static",
-    readsConfig: "static",
-    useExtension: "static",
-    usesApi: "static",
-    exposesApi: "static",
-    treeActions: "static",
-    screen: "mixed",
-    writeHandler: "mixed",
-    queryHandler: "mixed",
-    streamHandler: "mixed",
-    hook: "mixed",
-    job: "mixed",
-    notification: "mixed",
-    httpRoute: "mixed",
-    projection: "mixed",
-    multiStreamProjection: "mixed",
-    defineEvent: "mixed",
-    "ai.generate": "mixed",
-    "ai.extract": "mixed",
-    "ai.classify": "mixed",
-    authClaims: "opaque",
-    extendsRegistrar: "opaque",
-    envSchema: "opaque",
-    uiHints: "opaque",
-    adoptsBundledLists: "opaque",
-    unknown: "opaque",
-};
-export function getEditability(pattern) {
-    return EDITABILITY_BY_KIND[pattern.kind];
-}

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

@@ -1,47 +0,0 @@
-import type { FeaturePattern } from "./patterns.ts";
-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 = "  ";