semantic-primitives 0.1.0

package/dist/primitives/void/void.d.ts

@@ -0,0 +1,172 @@
+/**
+ * SemanticVoid
+ * A void type with LLM-powered semantic understanding
+ *
+ * Provides static methods to analyze void-returning functions,
+ * understand their side effects, and validate proper usage patterns.
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { AppropriateResult } from '../../shared/types.ts';
+export type { AppropriateResult } from '../../shared/types.ts';
+/** Result of analyzing side effects */
+export interface AnalyzeSideEffectsResult {
+    hasSideEffects: boolean;
+    effects: string[];
+    pure: boolean;
+}
+/** Result of checking if function should return a value */
+export interface ShouldReturnValueResult {
+    shouldReturn: boolean;
+    reason: string;
+    suggestedType?: string;
+}
+/** Result of validating void function usage */
+export interface ValidateUsageResult {
+    appropriate: boolean;
+    reason: string;
+    suggestion?: string;
+}
+/** Result of checking error handling */
+export interface CheckErrorHandlingResult {
+    hasErrorHandling: boolean;
+    risks: string[];
+    recommendation: string;
+}
+/** Result of suggesting improved signature */
+export interface SuggestSignatureResult {
+    current: string;
+    suggested: string;
+    reason: string;
+}
+/** Type for void-returning functions */
+export type VoidFunction = (...args: any[]) => void;
+/**
+ * SemanticVoid - Void with LLM-powered semantic understanding
+ *
+ * Unlike plain void that only represents absence of return,
+ * SemanticVoid provides tools to analyze void functions,
+ * understand their side effects, and validate proper usage.
+ *
+ * All methods are static since void cannot be instantiated.
+ */
+export declare class SemanticVoid {
+    /**
+     * Analyze a void-returning function for its side effects.
+     *
+     * @param fn - Function to analyze
+     * @param client - Optional LLM client for dependency injection
+     * @returns Side effect analysis
+     *
+     * @example
+     * await SemanticVoid.analyzeSideEffects(saveToDatabase)
+     * // {
+     * //   hasSideEffects: true,
+     * //   effects: ["database write", "logging"],
+     * //   pure: false
+     * // }
+     */
+    static analyzeSideEffects(fn: VoidFunction, client?: LLMClient): Promise<AnalyzeSideEffectsResult>;
+    /**
+     * Check if a function should actually return a value.
+     *
+     * @param fn - Function to analyze
+     * @param context - Context about the function's purpose
+     * @param client - Optional LLM client for dependency injection
+     * @returns Analysis with recommendation
+     *
+     * @example
+     * await SemanticVoid.shouldReturnValue(processData, "data processing function")
+     * // {
+     * //   shouldReturn: true,
+     * //   reason: "Processing functions typically return the processed result",
+     * //   suggestedType: "ProcessedData"
+     * // }
+     */
+    static shouldReturnValue(fn: VoidFunction, context?: string, client?: LLMClient): Promise<ShouldReturnValueResult>;
+    /**
+     * Explain what a void function does.
+     *
+     * @param fn - Function to explain
+     * @param client - Optional LLM client for dependency injection
+     * @returns Human-readable explanation
+     *
+     * @example
+     * await SemanticVoid.explain(sendNotification)
+     * // "Sends a notification to the user without returning a result. Side effects: network request, logging."
+     */
+    static explain(fn: VoidFunction, client?: LLMClient): Promise<string>;
+    /**
+     * Validate that a void function is used appropriately.
+     *
+     * @param fn - Function to validate
+     * @param usage - How the function is being used
+     * @param client - Optional LLM client for dependency injection
+     * @returns Validation result
+     *
+     * @example
+     * await SemanticVoid.validateUsage(logError, "in array.map()")
+     * // {
+     * //   appropriate: false,
+     * //   reason: "Void functions in map() lose return value, use forEach() instead"
+     * // }
+     */
+    static validateUsage(fn: VoidFunction, usage: string, client?: LLMClient): Promise<ValidateUsageResult>;
+    /**
+     * Detect if a void function is missing error handling.
+     *
+     * @param fn - Function to analyze
+     * @param client - Optional LLM client for dependency injection
+     * @returns Error handling assessment
+     *
+     * @example
+     * await SemanticVoid.checkErrorHandling(saveData)
+     * // {
+     * //   hasErrorHandling: false,
+     * //   risks: ["Database errors will be silently ignored"],
+     * //   recommendation: "Add try-catch or return Promise to propagate errors"
+     * // }
+     */
+    static checkErrorHandling(fn: VoidFunction, client?: LLMClient): Promise<CheckErrorHandlingResult>;
+    /**
+     * Suggest a better signature for a void function.
+     *
+     * @param fn - Function to analyze
+     * @param client - Optional LLM client for dependency injection
+     * @returns Suggested improvements
+     *
+     * @example
+     * await SemanticVoid.suggestSignature(updateUser)
+     * // {
+     * //   current: "(user: User) => void",
+     * //   suggested: "(user: User) => Promise<void>",
+     * //   reason: "Async operations should return Promise for error handling"
+     * // }
+     */
+    static suggestSignature(fn: VoidFunction, client?: LLMClient): Promise<SuggestSignatureResult>;
+    /**
+     * List common patterns where void is appropriate.
+     *
+     * @returns List of appropriate void patterns
+     *
+     * @example
+     * SemanticVoid.appropriatePatterns()
+     * // ["event handlers", "cleanup functions", "logging", "side-effect-only callbacks"]
+     */
+    static appropriatePatterns(): string[];
+    /**
+     * Check if void is the correct return type for a function name.
+     *
+     * @param fnName - Function name to analyze
+     * @param client - Optional LLM client for dependency injection
+     * @returns Appropriateness assessment
+     *
+     * @example
+     * await SemanticVoid.isAppropriateFor("calculateTotal")
+     * // { appropriate: false, reason: "Functions starting with 'calculate' should return a value" }
+     *
+     * await SemanticVoid.isAppropriateFor("logMessage")
+     * // { appropriate: true, reason: "Logging functions are typically void" }
+     */
+    static isAppropriateFor(fnName: string, client?: LLMClient): Promise<AppropriateResult>;
+}
+//# sourceMappingURL=void.d.ts.map

package/dist/primitives/void/void.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"void.d.ts","sourceRoot":"","sources":["../../../src/primitives/void/void.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAY/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wCAAwC;AAExC,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AASpD;;;;;;;;GAQG;AAEH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;;OAcG;WACU,kBAAkB,CAC7B,EAAE,EAAE,YAAY,EAChB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,wBAAwB,CAAC;IAcpC;;;;;;;;;;;;;;;OAeG;WACU,iBAAiB,CAC5B,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,uBAAuB,CAAC;IAcnC;;;;;;;;;;OAUG;WACU,OAAO,CAClB,EAAE,EAAE,YAAY,EAChB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,MAAM,CAAC;IAelB;;;;;;;;;;;;;;OAcG;WACU,aAAa,CACxB,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,mBAAmB,CAAC;IAc/B;;;;;;;;;;;;;;OAcG;WACU,kBAAkB,CAC7B,EAAE,EAAE,YAAY,EAChB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,wBAAwB,CAAC;IAcpC;;;;;;;;;;;;;;OAcG;WACU,gBAAgB,CAC3B,EAAE,EAAE,YAAY,EAChB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,sBAAsB,CAAC;IAclC;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,IAAI,MAAM,EAAE;IAetC;;;;;;;;;;;;;OAaG;WACU,gBAAgB,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,iBAAiB,CAAC;CAY9B"}

package/dist/shared/base-classes.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Abstract base classes for semantic primitives
+ *
+ * These classes provide common implementation patterns and can be extended
+ * by concrete semantic type implementations.
+ */
+import type { LLMClientInterface, Semantic, Comparable, Explainable, Validatable, Summarizable, SemanticAccessible } from './interfaces.ts';
+import type { SemanticEqualsResult, ValidateResult, ConfidenceResult } from './types.ts';
+/**
+ * Abstract base class providing common functionality for all semantic wrappers.
+ *
+ * @template T - The underlying native type being wrapped
+ *
+ * Provides:
+ * - Value storage and retrieval via valueOf()
+ * - LLM client injection and access
+ * - JSON serialization support
+ *
+ * @example
+ * ```typescript
+ * class SemanticString extends SemanticBase<string> implements Comparable<string> {
+ *   constructor(value: string, client?: LLMClientInterface) {
+ *     super(value, client);
+ *   }
+ *
+ *   async semanticallyEquals(other: string): Promise<SemanticEqualsResult> {
+ *     // Implementation using this.llmClient
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class SemanticBase<T> implements Semantic<T> {
+    /** The wrapped native value */
+    protected readonly value: T;
+    /** The LLM client for AI-powered operations */
+    protected readonly llmClient?: LLMClientInterface;
+    /**
+     * Create a new semantic wrapper.
+     *
+     * @param value - The value to wrap
+     * @param client - Optional LLM client for AI operations
+     */
+    constructor(value: T, client?: LLMClientInterface);
+    /**
+     * Get the underlying native value.
+     * @returns The wrapped value
+     */
+    valueOf(): T;
+    /**
+     * Convert to JSON-serializable format.
+     * Override in subclasses for custom serialization.
+     */
+    toJSON(): unknown;
+    /**
+     * Get string representation.
+     */
+    toString(): string;
+    /**
+     * Ensure LLM client is available, throw if not.
+     * @throws Error if LLM client is not configured
+     */
+    protected requireLLMClient(): LLMClientInterface;
+    /**
+     * Check if LLM client is available.
+     */
+    protected hasLLMClient(): boolean;
+}
+/**
+ * Abstract base class for semantic types that support equality comparison.
+ *
+ * @template T - The underlying native type
+ */
+export declare abstract class ComparableSemanticBase<T> extends SemanticBase<T> implements Comparable<T> {
+    /**
+     * Compare this value with another for semantic equivalence.
+     * Must be implemented by subclasses.
+     *
+     * @param other - The value to compare with
+     * @param options - Optional comparison options
+     * @returns Equivalence result with confidence
+     */
+    abstract semanticallyEquals(other: unknown, options?: Record<string, unknown>): SemanticEqualsResult | Promise<SemanticEqualsResult>;
+}
+/**
+ * Abstract base class for semantic types that can explain themselves.
+ *
+ * @template T - The underlying native type
+ */
+export declare abstract class ExplainableSemanticBase<T> extends ComparableSemanticBase<T> implements Explainable {
+    /**
+     * Generate a human-readable explanation of this value.
+     * Must be implemented by subclasses.
+     *
+     * @param context - Optional context for more relevant explanation
+     * @returns Human-readable description
+     */
+    abstract explain(context?: string): string | Promise<string>;
+}
+/**
+ * Abstract base class for semantic types that support validation.
+ *
+ * @template T - The underlying native type
+ */
+export declare abstract class ValidatableSemanticBase<T> extends ExplainableSemanticBase<T> implements Validatable {
+    /**
+     * Validate the value against semantic rules.
+     * Must be implemented by subclasses.
+     *
+     * @param rules - Natural language validation rules
+     * @returns Validation result with issues
+     */
+    abstract validate(rules: string[]): ValidateResult | Promise<ValidateResult>;
+}
+/**
+ * Abstract base class for semantic collection types (Array, Set).
+ *
+ * @template T - The element type
+ * @template TSelf - The concrete collection type (for fluent returns)
+ */
+export declare abstract class SemanticCollectionBase<T, TSelf> extends SemanticBase<T[]> implements Summarizable {
+    /**
+     * Get the number of elements in the collection.
+     */
+    get length(): number;
+    /**
+     * Check if the collection is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Get an element at a specific index.
+     * @param index - The index of the element
+     * @returns The element at the index, or undefined if out of bounds
+     */
+    at(index: number): T | undefined;
+    /**
+     * Get all elements as an array.
+     * @returns Copy of the underlying array
+     */
+    toArray(): T[];
+    /**
+     * Check if the collection includes a specific element.
+     * @param element - The element to search for
+     * @returns true if the element is found
+     */
+    includes(element: T): boolean;
+    /**
+     * Generate a summary of the collection contents.
+     * Must be implemented by subclasses.
+     *
+     * @param options - Optional summarization options
+     * @returns Human-readable summary
+     */
+    abstract summarize(options?: {
+        maxLength?: number;
+        focus?: string;
+    }): string | Promise<string>;
+    /**
+     * Filter elements using natural language criteria.
+     * Must be implemented by subclasses.
+     *
+     * @param criteria - Natural language filter condition
+     * @returns Filtered collection
+     */
+    abstract semanticFilter(criteria: string): TSelf | Promise<TSelf>;
+    /**
+     * Group elements by semantic criteria.
+     * Must be implemented by subclasses.
+     *
+     * @param criteria - Grouping criteria
+     * @returns Map of groups
+     */
+    abstract semanticGroup(criteria: string): Map<string, TSelf> | Promise<Map<string, TSelf>>;
+}
+/**
+ * Abstract base class for semantic key-value collection types (Object, Map, Record).
+ *
+ * @template K - The key type
+ * @template V - The value type
+ * @template TSelf - The concrete collection type (for fluent returns)
+ */
+export declare abstract class SemanticKeyValueBase<K, V, TSelf> extends SemanticBase<Map<K, V> | Record<string, V>> implements SemanticAccessible<K, V>, Summarizable {
+    /**
+     * Get a value using semantic key matching.
+     * Must be implemented by subclasses.
+     *
+     * @param query - Key or semantic query
+     * @param context - Optional context
+     * @returns Value with match confidence
+     */
+    abstract semanticGet(query: string, context?: Record<string, unknown>): {
+        value: V | undefined;
+        matchedKey: K | undefined;
+        confidence: number;
+    } | Promise<{
+        value: V | undefined;
+        matchedKey: K | undefined;
+        confidence: number;
+    }>;
+    /**
+     * Generate a summary of the collection contents.
+     * Must be implemented by subclasses.
+     */
+    abstract summarize(options?: {
+        maxLength?: number;
+        focus?: string;
+    }): string | Promise<string>;
+    /**
+     * Merge with another collection using semantic key matching.
+     * Must be implemented by subclasses.
+     */
+    abstract semanticMerge(other: unknown, options?: {
+        conflictResolution?: 'prefer-this' | 'prefer-other' | 'combine';
+    }): TSelf | Promise<TSelf>;
+}
+/**
+ * Abstract base class for semantic callable types (Function, Callable).
+ *
+ * @template TFn - The function type
+ */
+export declare abstract class SemanticCallableBase<TFn extends (...args: unknown[]) => unknown> extends SemanticBase<TFn> implements Explainable {
+    /** Optional description of what the function does */
+    protected readonly description?: string;
+    /**
+     * Create a semantic callable wrapper.
+     *
+     * @param fn - The function to wrap
+     * @param description - Optional description
+     * @param client - Optional LLM client
+     */
+    constructor(fn: TFn, description?: string, client?: LLMClientInterface);
+    /**
+     * Call the underlying function.
+     *
+     * @param args - Arguments to pass to the function
+     * @returns The function's return value
+     */
+    call(...args: Parameters<TFn>): ReturnType<TFn>;
+    /**
+     * Generate a human-readable explanation of what the function does.
+     * Must be implemented by subclasses.
+     */
+    abstract explain(context?: string): string | Promise<string>;
+    /**
+     * Validate function arguments.
+     * Must be implemented by subclasses.
+     */
+    abstract validateArgs(args: unknown[], rules?: string[]): ValidateResult | Promise<ValidateResult>;
+}
+/**
+ * Abstract base class for semantic absence types (Null, Undefined).
+ *
+ * @template T - The absence type (null or undefined)
+ */
+export declare abstract class SemanticAbsenceBase<T extends null | undefined> extends SemanticBase<T> {
+    /** The reason for the absence, if provided */
+    protected readonly reason?: string;
+    /**
+     * Create a semantic absence wrapper.
+     *
+     * @param value - The absence value (null or undefined)
+     * @param reason - Optional reason for the absence
+     * @param client - Optional LLM client
+     */
+    constructor(value: T, reason?: string, client?: LLMClientInterface);
+    /**
+     * Get the reason for absence, if provided.
+     */
+    getReason(): string | undefined;
+    /**
+     * Check if a reason was provided.
+     */
+    hasReason(): boolean;
+    /**
+     * Classify the type of absence.
+     * Must be implemented by subclasses.
+     */
+    abstract classify(): {
+        type: 'not-set' | 'not-applicable' | 'unknown';
+        canBeProvided: boolean;
+    } | Promise<{
+        type: 'not-set' | 'not-applicable' | 'unknown';
+        canBeProvided: boolean;
+    }>;
+    /**
+     * Generate a human-readable explanation.
+     * Must be implemented by subclasses.
+     */
+    abstract explain(fieldName: string): string | Promise<string>;
+}
+/**
+ * Builder for creating consistent result objects.
+ * Useful for constructing SemanticEqualsResult and similar types.
+ *
+ * @template T - The result type being built
+ */
+export declare class ResultBuilder<T extends ConfidenceResult> {
+    private result;
+    /**
+     * Set the confidence score.
+     */
+    withConfidence(confidence: number): this;
+    /**
+     * Add a property to the result.
+     */
+    with<K extends keyof T>(key: K, value: T[K]): this;
+    /**
+     * Build the final result object.
+     */
+    build(): T;
+    /**
+     * Create a new builder instance.
+     */
+    static create<T extends ConfidenceResult>(): ResultBuilder<T>;
+}
+/**
+ * Type guard to check if a value is a Semantic wrapper.
+ */
+export declare function isSemantic<T>(value: unknown): value is Semantic<T>;
+/**
+ * Type guard to check if a value is Comparable.
+ */
+export declare function isComparable<T>(value: unknown): value is Comparable<T>;
+/**
+ * Type guard to check if a value is Explainable.
+ */
+export declare function isExplainable(value: unknown): value is Explainable;
+/**
+ * Type guard to check if a value is Validatable.
+ */
+export declare function isValidatable(value: unknown): value is Validatable;
+//# sourceMappingURL=base-classes.d.ts.map

package/dist/shared/base-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-classes.d.ts","sourceRoot":"","sources":["../../src/shared/base-classes.ts"],"names":[],"mappings":"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"}

package/dist/shared/eval-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Type definitions for evaluation data files
+ *
+ * These types are used by evaluation datasets in src/primitives/<type>/evals/
+ * and src/types/<type>/evals/ directories.
+ */
+/**
+ * Numeric range for flexible matching of expected values
+ */
+export interface NumericRange {
+    min?: number;
+    max?: number;
+    exact?: number;
+}
+/**
+ * Expected value can be exact, a range, or nested structures
+ */
+export type ExpectedValue = string | number | boolean | null | undefined | NumericRange | ExpectedValue[] | {
+    [key: string]: ExpectedValue;
+};
+/**
+ * Difficulty levels for test cases
+ */
+export type Difficulty = 'easy' | 'medium' | 'hard';
+/**
+ * Input configuration for a test case
+ */
+export interface EvalInput {
+    /** Primary value to instantiate the semantic type */
+    value: unknown;
+    /** Arguments to pass to the method being tested */
+    args?: unknown[];
+    /** Options/context to pass to the method */
+    options?: Record<string, unknown>;
+}
+/**
+ * A single test case in an evaluation dataset
+ */
+export interface EvalCase {
+    /** Unique identifier for the test case */
+    id: string;
+    /** Human-readable description of what's being tested */
+    description: string;
+    /** Input configuration */
+    input: EvalInput;
+    /** Expected output - can be exact values or ranges */
+    expected: Record<string, ExpectedValue>;
+    /** Criteria for LLM judge evaluation */
+    criteria: string[];
+    /** Tags for filtering and grouping */
+    tags?: string[];
+    /** Difficulty level (affects scoring weight) */
+    difficulty?: Difficulty;
+    /** Skip this case (for WIP or known issues) */
+    skip?: boolean;
+    /** Reason for skipping */
+    skipReason?: string;
+}
+/**
+ * Complete evaluation dataset for a semantic operation
+ */
+export interface EvalDataset {
+    /** Dataset name (e.g., 'SemanticString.semanticallyEquals') */
+    name: string;
+    /** Description of what's being tested */
+    description: string;
+    /** Version for tracking changes */
+    version: string;
+    /** Target class name (e.g., 'SemanticString') */
+    targetClass: string;
+    /** Target method name (e.g., 'semanticallyEquals') */
+    targetMethod: string;
+    /** Whether the method is static (e.g., 'from') */
+    isStaticMethod?: boolean;
+    /** Factory method to create instance (defaults to 'from') */
+    factoryMethod?: string;
+    /** Whether factory method is async */
+    factoryAsync?: boolean;
+    /** All test cases */
+    cases: EvalCase[];
+}
+//# sourceMappingURL=eval-types.d.ts.map

package/dist/shared/eval-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-types.d.ts","sourceRoot":"","sources":["../../src/shared/eval-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,YAAY,GACZ,aAAa,EAAE,GACf;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,wCAAwC;IACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,gDAAgD;IAChD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qBAAqB;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB"}

package/dist/shared/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared utilities and types
+ */
+export { type ConfidenceResult, type SemanticEqualsResult, type SemanticEqualsResultWithReason, type SemanticEqualsResultWithMappings, } from './types.ts';
+export { type ClassifyResult, type InferTypeResult, type InferPurposeResult, } from './types.ts';
+export { type ValidateResult, type ValidateResultWithWarnings, type ReasonableResult, type AppropriateResult, } from './types.ts';
+export { type Suggestion, type MissingSuggestion, type RelatedSuggestion, type ImprovementSuggestion, type Correction, } from './types.ts';
+export { type SemanticGetResult, type SearchResult, } from './types.ts';
+export { type SeverityLevel, type ExtendedSeverityLevel, type ErrorSeverityLevel, type SafetyResult, type SensitiveResult, } from './types.ts';
+export { type DetectIntentResult, type DetectLanguageResult, type DetectPatternResult, type InferUnitResult, type InferDomainResult, type InferMeaningResult, type InferReasonResult, type InferSchemaResult, } from './types.ts';
+export { type ExplanationResult, type DurationResult, } from './types.ts';
+export { type DetectedIssue, type RootCauseResult, type SuggestedFix, type RecoveryStrategy, } from './types.ts';
+export { type GeneratedTestCase, type RegExpTestCases, } from './types.ts';
+export { type LLMClientInterface, type LLMCompletionOptions, } from './interfaces.ts';
+export { type Semantic, type SemanticFactory, } from './interfaces.ts';
+export { type Comparable, type Explainable, type Describable, type Validatable, type ContextValidatable, type PurposeValidatable, type TypeInferable, type PurposeInferable, type SchemaInferable, type Classifiable, type PatternDetectable, type Suggestible, type Summarizable, type SafetyAssessable, type SensitivityDetectable, } from './interfaces.ts';
+export { type SemanticFilterable, type SemanticSortable, type SemanticGroupable, type SemanticSearchable, type SemanticAccessible, type SemanticSetOperations, type SemanticMergeable, } from './interfaces.ts';
+export { type SemanticAbsence, type SemanticAbsenceFactory, type SemanticCollection, type SemanticKeyValueCollection, type SemanticCallableType, } from './interfaces.ts';
+export { type KeyTransformable, type UnitConvertible, } from './interfaces.ts';
+export { type TestGeneratable, type RegExpTestGeneratable, } from './interfaces.ts';
+export { type SemanticErrorType } from './interfaces.ts';
+export { type SemanticPrimitiveCapabilities, type SemanticPrimitiveExtended, type SemanticReferenceCapabilities, } from './interfaces.ts';
+export { SemanticBase, ComparableSemanticBase, ExplainableSemanticBase, ValidatableSemanticBase, SemanticCollectionBase, SemanticKeyValueBase, SemanticCallableBase, SemanticAbsenceBase, ResultBuilder, } from './base-classes.ts';
+export { isSemantic, isComparable, isExplainable, isValidatable, } from './base-classes.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"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"}