@panproto/core 0.7.0 → 0.9.0

package/dist/coverage.d.ts

@@ -0,0 +1,58 @@
+import { CoverageReport, OpticKind } from './types.js';
+import { BuiltSchema } from './schema.js';
+import { CompiledMigration } from './migration.js';
+import { ProtolensChainHandle } from './lens.js';
+import { Panproto } from './panproto.js';
+/**
+ * Migration analysis utilities for dry-run testing and optic classification.
+ *
+ * Wraps a `Panproto` instance and provides coverage analysis for migrations
+ * and optic kind classification for protolens chains.
+ *
+ * @example
+ * ```typescript
+ * const panproto = await Panproto.init();
+ * const analysis = new MigrationAnalysis(panproto);
+ *
+ * const report = analysis.dryRun(compiled, records, srcSchema, tgtSchema);
+ * console.log(`Coverage: ${(report.coverageRatio * 100).toFixed(1)}%`);
+ *
+ * const chain = panproto.protolensChain(srcSchema, tgtSchema);
+ * const kind = analysis.opticKind(chain, srcSchema);
+ * ```
+ */
+export declare class MigrationAnalysis {
+    #private;
+    /**
+     * Create a new migration analysis instance.
+     *
+     * @param panproto - The Panproto instance providing WASM access
+     */
+    constructor(panproto: Panproto);
+    /**
+     * Run a dry-run migration and return a coverage report.
+     *
+     * Tests each instance record against the compiled migration without
+     * persisting results, producing detailed failure information for
+     * records that cannot be migrated.
+     *
+     * @param compiled - The compiled migration to test
+     * @param instances - Array of instance records (plain objects)
+     * @param srcSchema - The source schema the instances conform to
+     * @param tgtSchema - The target schema
+     * @returns A coverage report with per-record success/failure data
+     */
+    dryRun(compiled: CompiledMigration, instances: unknown[], srcSchema: BuiltSchema, tgtSchema: BuiltSchema): CoverageReport;
+    /**
+     * Classify the optic kind of a protolens chain.
+     *
+     * Determines whether the chain represents an isomorphism, lens, prism,
+     * affine transformation, or traversal based on its complement structure.
+     *
+     * @param chain - The protolens chain to classify
+     * @param schema - The schema to check the chain against
+     * @returns The optic kind classification
+     */
+    opticKind(chain: ProtolensChainHandle, schema: BuiltSchema): OpticKind;
+}
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEV,cAAc,EAGd,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAuJ9C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;;IAG5B;;;;OAIG;gBACS,QAAQ,EAAE,QAAQ;IAI9B;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,OAAO,EAAE,EACpB,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,WAAW,GACrB,cAAc;IAIjB;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS;CAGvE"}

package/dist/enrichment.d.ts

@@ -0,0 +1,146 @@
+import { Expr, ConflictStrategy, EnrichmentSummary } from './types.js';
+import { BuiltSchema } from './schema.js';
+/**
+ * An individual default enrichment entry.
+ *
+ * Binds a default expression to a vertex, used when forward migration
+ * encounters a missing value.
+ */
+interface DefaultEntry {
+    readonly vertex: string;
+    readonly expr: Expr;
+}
+/**
+ * An individual coercion enrichment entry.
+ *
+ * Defines how to convert values from one kind to another.
+ */
+interface CoercionEntry {
+    readonly from: string;
+    readonly to: string;
+    readonly expr: Expr;
+}
+/**
+ * An individual merger enrichment entry.
+ *
+ * Defines how to merge two values at a given vertex during conflict resolution.
+ */
+interface MergerEntry {
+    readonly vertex: string;
+    readonly expr: Expr;
+}
+/**
+ * An individual conflict policy enrichment entry.
+ *
+ * Determines the strategy for resolving conflicts at a vertex.
+ */
+interface PolicyEntry {
+    readonly vertex: string;
+    readonly strategy: ConflictStrategy;
+}
+/**
+ * Immutable fluent builder for enriching a schema with default expressions,
+ * coercion functions, merge strategies, and conflict policies.
+ *
+ * Each mutation method returns a new `SchemaEnrichment` instance,
+ * leaving the original unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { SchemaEnrichment } from '@panproto/core';
+ * import { ExprBuilder } from '@panproto/core';
+ *
+ * const enriched = new SchemaEnrichment(schema)
+ *   .addDefault('post:title', ExprBuilder.lit({ type: 'str', value: 'Untitled' }))
+ *   .addCoercion('int', 'float', ExprBuilder.builtin('IntToFloat', ExprBuilder.var_('x')))
+ *   .addPolicy('post:body', { type: 'keep_left' })
+ *   .build();
+ * ```
+ */
+export declare class SchemaEnrichment {
+    #private;
+    constructor(schema: BuiltSchema, defaults?: readonly DefaultEntry[], coercions?: readonly CoercionEntry[], mergers?: readonly MergerEntry[], policies?: readonly PolicyEntry[]);
+    /**
+     * Add a default expression for a vertex.
+     *
+     * The expression is evaluated when forward migration encounters a
+     * missing value at the given vertex.
+     *
+     * @param vertex - The vertex identifier to attach the default to
+     * @param expr - The default expression
+     * @returns A new enrichment with the default added
+     * @throws {@link PanprotoError} if the vertex is not in the schema
+     */
+    addDefault(vertex: string, expr: Expr): SchemaEnrichment;
+    /**
+     * Add a coercion function between two value kinds.
+     *
+     * The expression defines how to convert values from `fromKind` to
+     * `toKind`. It receives a single argument (the source value) and
+     * must produce a value of the target kind.
+     *
+     * @param fromKind - Source value kind (e.g., 'int')
+     * @param toKind - Target value kind (e.g., 'float')
+     * @param expr - The coercion expression
+     * @returns A new enrichment with the coercion added
+     * @throws {@link PanprotoError} if a coercion for this pair already exists
+     */
+    addCoercion(fromKind: string, toKind: string, expr: Expr): SchemaEnrichment;
+    /**
+     * Add a merger expression for a vertex.
+     *
+     * The expression defines how to merge two conflicting values at the
+     * given vertex. It receives two arguments (left and right values)
+     * and must produce a single merged value.
+     *
+     * @param vertex - The vertex identifier to attach the merger to
+     * @param expr - The merger expression
+     * @returns A new enrichment with the merger added
+     * @throws {@link PanprotoError} if the vertex is not in the schema
+     */
+    addMerger(vertex: string, expr: Expr): SchemaEnrichment;
+    /**
+     * Add a conflict resolution policy for a vertex.
+     *
+     * @param vertex - The vertex identifier
+     * @param strategy - The conflict resolution strategy
+     * @returns A new enrichment with the policy added
+     * @throws {@link PanprotoError} if the vertex is not in the schema
+     */
+    addPolicy(vertex: string, strategy: ConflictStrategy): SchemaEnrichment;
+    /**
+     * Remove the default expression for a vertex.
+     *
+     * @param vertex - The vertex identifier
+     * @returns A new enrichment with the default removed
+     * @throws {@link PanprotoError} if no default exists for the vertex
+     */
+    removeDefault(vertex: string): SchemaEnrichment;
+    /**
+     * Remove the coercion function for a value kind pair.
+     *
+     * @param fromKind - Source value kind
+     * @param toKind - Target value kind
+     * @returns A new enrichment with the coercion removed
+     * @throws {@link PanprotoError} if no coercion exists for the pair
+     */
+    removeCoercion(fromKind: string, toKind: string): SchemaEnrichment;
+    /**
+     * List all enrichments currently attached.
+     *
+     * @returns An enrichment summary with defaults, coercions, mergers, and policies
+     */
+    listEnrichments(): EnrichmentSummary;
+    /**
+     * Build the enriched schema.
+     *
+     * Returns a new `BuiltSchema` with the enrichments recorded in the
+     * schema data. The underlying WASM handle is shared with the original
+     * schema (enrichments are metadata that the SDK tracks client-side).
+     *
+     * @returns A new BuiltSchema with enrichment metadata
+     */
+    build(): BuiltSchema;
+}
+export {};
+//# sourceMappingURL=enrichment.d.ts.map

package/dist/enrichment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment.d.ts","sourceRoot":"","sources":["../src/enrichment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,UAAU,YAAY;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;;gBAQzB,MAAM,EAAE,WAAW,EACnB,QAAQ,GAAE,SAAS,YAAY,EAAO,EACtC,SAAS,GAAE,SAAS,aAAa,EAAO,EACxC,OAAO,GAAE,SAAS,WAAW,EAAO,EACpC,QAAQ,GAAE,SAAS,WAAW,EAAO;IASvC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB;IAkBxD;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB;IAgB3E;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB;IAkBvD;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB;IAkBvE;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAiB/C;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAmBlE;;;;OAIG;IACH,eAAe,IAAI,iBAAiB;IASpC;;;;;;;;OAQG;IACH,KAAK,IAAI,WAAW;CAyErB"}

package/dist/expr.d.ts

@@ -0,0 +1,145 @@
+import { Expr, Literal, Pattern, BuiltinOp } from './types.js';
+/**
+ * Static factory for constructing expression AST nodes.
+ *
+ * All methods return immutable {@link Expr} values suitable for use in
+ * schema enrichments, directed equations, and conflict policies.
+ *
+ * @example
+ * ```typescript
+ * import { ExprBuilder as E } from '@panproto/core';
+ *
+ * // Lambda that adds 1 to its argument
+ * const addOne = E.lam('x', E.add(E.var_('x'), E.lit({ type: 'int', value: 1 })));
+ *
+ * // Record literal
+ * const record = E.record({ name: E.lit({ type: 'str', value: 'default' }) });
+ * ```
+ */
+export declare class ExprBuilder {
+    /** This class is not instantiable; all methods are static. */
+    private constructor();
+    /**
+     * Create a variable reference expression.
+     *
+     * @param name - The variable name to reference
+     * @returns A variable expression node
+     */
+    static var_(name: string): Expr;
+    /**
+     * Create a literal expression.
+     *
+     * @param value - The literal value
+     * @returns A literal expression node
+     */
+    static lit(value: Literal): Expr;
+    /**
+     * Create a lambda (anonymous function) expression.
+     *
+     * @param param - The parameter name
+     * @param body - The function body expression
+     * @returns A lambda expression node
+     */
+    static lam(param: string, body: Expr): Expr;
+    /**
+     * Create a function application expression.
+     *
+     * When multiple arguments are provided, they are applied left-to-right
+     * via currying: `app(f, a, b)` becomes `app(app(f, a), b)`.
+     *
+     * @param func - The function expression
+     * @param args - One or more argument expressions
+     * @returns An application expression node (possibly nested)
+     */
+    static app(func: Expr, ...args: Expr[]): Expr;
+    /**
+     * Create a let-binding expression.
+     *
+     * Binds `value` to `name` in the scope of `body`.
+     *
+     * @param name - The variable name to bind
+     * @param value - The value expression to bind
+     * @param body - The body expression where the binding is in scope
+     * @returns A let expression node
+     */
+    static let_(name: string, value: Expr, body: Expr): Expr;
+    /**
+     * Create a field access expression.
+     *
+     * @param expr - The record expression to access
+     * @param name - The field name
+     * @returns A field access expression node
+     */
+    static field(expr: Expr, name: string): Expr;
+    /**
+     * Create a record literal expression.
+     *
+     * @param fields - A mapping of field names to expressions
+     * @returns A record expression node
+     */
+    static record(fields: Record<string, Expr>): Expr;
+    /**
+     * Create a list literal expression.
+     *
+     * @param items - The list element expressions
+     * @returns A list expression node
+     */
+    static list(...items: Expr[]): Expr;
+    /**
+     * Create a pattern-match expression.
+     *
+     * @param scrutinee - The expression to match against
+     * @param arms - Pattern-expression pairs tried in order
+     * @returns A match expression node
+     */
+    static match_(scrutinee: Expr, arms: [Pattern, Expr][]): Expr;
+    /**
+     * Create a builtin operation expression.
+     *
+     * @param op - The builtin operation name
+     * @param args - Argument expressions for the operation
+     * @returns A builtin expression node
+     */
+    static builtin(op: BuiltinOp, ...args: Expr[]): Expr;
+    /**
+     * Create an index expression for list or record access.
+     *
+     * @param expr - The collection expression
+     * @param index - The index expression
+     * @returns An index expression node
+     */
+    static index(expr: Expr, index: Expr): Expr;
+    /**
+     * Add two expressions.
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Add' expression
+     */
+    static add(a: Expr, b: Expr): Expr;
+    /**
+     * Subtract two expressions.
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Sub' expression
+     */
+    static sub(a: Expr, b: Expr): Expr;
+    /**
+     * Multiply two expressions.
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Mul' expression
+     */
+    static mul(a: Expr, b: Expr): Expr;
+    /**
+     * Concatenate two expressions (strings or lists).
+     *
+     * @param a - Left operand
+     * @param b - Right operand
+     * @returns A builtin 'Concat' expression
+     */
+    static concat(a: Expr, b: Expr): Expr;
+}
+//# sourceMappingURL=expr.d.ts.map

package/dist/expr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr.d.ts","sourceRoot":"","sources":["../src/expr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,8DAA8D;IAC9D,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAIhC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAI3C;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI;IAQ7C;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAIxD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI;IAKjD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAInC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI;IAI7D;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI;IAIpD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,IAAI;IAQ3C;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;CAGtC"}