@hyperfixi/core 2.0.0

package/dist/types/command-types.d.ts

@@ -0,0 +1,272 @@
+import type { RuntimeValidator } from '../validation/lightweight-validators';
+import type { ValidationResult, ValidationError, HyperScriptValueType, EvaluationResult, TypedExecutionContext } from './base-types';
+export type { ExecutionContext, TypedExecutionContext, TypedExecutionContext as TypedExpressionContext, ValidationResult, TypedResult, LLMDocumentation, } from './base-types';
+export type HyperScriptValue = unknown;
+export type { EvaluationResult, EvaluationType, HyperScriptValueType } from './base-types';
+export declare const HyperScriptValueSchema: RuntimeValidator<unknown>;
+export interface ExecutionMeta {
+    readonly startTime: number;
+    readonly commandStack: string[];
+    readonly sourceLocation?: SourceLocation;
+    readonly debugMode: boolean;
+}
+export interface SourceLocation {
+    readonly line: number;
+    readonly column: number;
+    readonly source: string;
+}
+export interface TypedCommandImplementation<TInput extends readonly HyperScriptValue[] = readonly HyperScriptValue[], TOutput extends HyperScriptValue = HyperScriptValue, TContext extends TypedExecutionContext = TypedExecutionContext> {
+    readonly name: string;
+    readonly syntax: string;
+    readonly description: string;
+    readonly inputSchema: RuntimeValidator<TInput>;
+    readonly outputType: HyperScriptValueType;
+    execute(context: TContext, ...args: TInput): Promise<EvaluationResult<TOutput>>;
+    validate(args: unknown[]): ValidationResult;
+    readonly metadata: CommandMetadata;
+}
+export interface CommandMetadata {
+    readonly category: CommandCategory;
+    readonly complexity: 'simple' | 'medium' | 'complex';
+    readonly sideEffects: SideEffect[];
+    readonly examples: CommandExample[];
+    readonly relatedCommands: string[];
+}
+export type CommandCategory = 'DOM' | 'Event' | 'Control' | 'Data' | 'Communication' | 'Style';
+export type SideEffect = string;
+export interface CommandExample {
+    readonly code: string;
+    readonly description: string;
+    readonly expectedOutput: HyperScriptValue;
+}
+export interface TypedExpressionImplementation<TOutput extends HyperScriptValue = HyperScriptValue, TContext extends TypedExecutionContext = TypedExecutionContext> {
+    readonly name: string;
+    readonly category: ExpressionCategory;
+    readonly precedence: number;
+    readonly associativity: 'left' | 'right' | 'none';
+    readonly outputType: string;
+    evaluate(context: TContext, ...args: HyperScriptValue[]): Promise<EvaluationResult<TOutput>>;
+    readonly analysisInfo: ExpressionAnalysisInfo;
+}
+export interface ExpressionAnalysisInfo {
+    readonly isPure: boolean;
+    readonly canThrow: boolean;
+    readonly complexity: 'O(1)' | 'O(n)' | 'O(n²)' | 'O(log n)';
+    readonly dependencies: string[];
+}
+export type ExpressionCategory = 'reference' | 'logical' | 'comparison' | 'arithmetic' | 'string' | 'array' | 'object' | 'conversion' | 'special';
+export interface EnhancedValidationError extends ValidationError {
+    readonly position?: SourceLocation;
+    readonly suggestion?: string;
+}
+export interface HyperScriptError {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly source?: SourceLocation;
+    readonly cause?: Error;
+    readonly suggestions: string[];
+}
+export declare class TypeChecker {
+    static getType(value: unknown): string;
+    static validateType(value: unknown, expectedType: string): ValidationResult;
+    private static getTypeSuggestion;
+}
+export interface ParameterDoc {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+    readonly optional: boolean;
+    readonly defaultValue?: HyperScriptValue;
+    readonly examples: string[];
+}
+export interface ReturnDoc {
+    readonly type: string;
+    readonly description: string;
+    readonly examples: HyperScriptValue[];
+}
+export interface DocumentationExample {
+    readonly title: string;
+    readonly code: string;
+    readonly explanation: string;
+    readonly output: HyperScriptValue;
+}
+export interface HyperScriptProgram {
+    readonly source: string;
+    readonly features: HyperScriptFeature[];
+    readonly metadata: ProgramMetadata;
+    readonly sourceInfo?: ProgramSourceInfo;
+    readonly state: ProgramState;
+}
+export interface HyperScriptFeature {
+    readonly type: HyperScriptFeatureType;
+    readonly id: string;
+    readonly trigger?: EventTrigger;
+    readonly commands: ParsedCommand[];
+    readonly config: FeatureConfig;
+    readonly sourceRange: SourceRange;
+    readonly metadata: FeatureMetadata;
+}
+export interface ParsedCommand {
+    readonly type: ParsedCommandType;
+    readonly name: string;
+    readonly implementation?: unknown | TypedExpressionImplementation<unknown, TypedExecutionContext>;
+    readonly args: ParsedArgument[];
+    readonly options: CommandOptions;
+    readonly sourceRange: SourceRange;
+    readonly analysis?: CommandAnalysis;
+}
+export interface ParsedArgument {
+    readonly value: HyperScriptValue;
+    readonly type: string;
+    readonly kind: 'literal' | 'expression' | 'reference';
+    readonly sourceRange?: SourceRange;
+    readonly analysis?: ArgumentAnalysis;
+}
+export type HyperScriptFeatureType = 'event' | 'behavior' | 'definition' | 'init' | 'worker' | 'socket' | 'eventsource' | 'set' | 'js' | 'custom';
+export type ParsedCommandType = 'dom-manipulation' | 'content' | 'navigation' | 'event' | 'async' | 'control-flow' | 'data' | 'expression' | 'custom';
+export interface EventTrigger {
+    readonly event: string;
+    readonly target?: string | HTMLElement;
+    readonly options: EventListenerOptions & {
+        readonly once?: boolean;
+        readonly debounce?: number;
+        readonly throttle?: number;
+    };
+    readonly filter?: EventFilter;
+}
+export interface EventFilter {
+    readonly selector?: string;
+    readonly keys?: string[];
+    readonly condition?: string;
+}
+export interface FeatureConfig {
+    readonly enabled: boolean;
+    readonly priority: number;
+    readonly options: Record<string, HyperScriptValue>;
+    readonly dependencies: string[];
+    readonly capabilities: FeatureCapabilities;
+}
+export interface FeatureCapabilities {
+    readonly requiresDOM: boolean;
+    readonly isAsync: boolean;
+    readonly modifiesGlobalState: boolean;
+    readonly requiredAPIs: string[];
+    readonly performance: PerformanceCharacteristics;
+}
+export interface PerformanceCharacteristics {
+    readonly complexity: 'low' | 'medium' | 'high';
+    readonly memoryUsage: 'minimal' | 'moderate' | 'heavy';
+    readonly cpuIntensive: boolean;
+    readonly executionTime: {
+        readonly min: number;
+        readonly max: number;
+        readonly typical: number;
+    };
+}
+export interface ProgramMetadata {
+    readonly compilation: {
+        readonly compiled: boolean;
+        readonly compiledAt?: Date;
+        readonly compiler: string;
+        readonly version: string;
+    };
+    readonly analysis: {
+        readonly complexity: number;
+        readonly estimatedExecutionTime: number;
+        readonly memoryRequirements: number;
+        readonly warnings: AnalysisWarning[];
+        readonly optimizations: string[];
+    };
+    readonly performance?: {
+        readonly lastExecutionTime: number;
+        readonly averageExecutionTime: number;
+        readonly executionCount: number;
+        readonly errorCount: number;
+    };
+}
+export interface FeatureMetadata {
+    readonly compiledAt: Date;
+    readonly stats: {
+        readonly executionCount: number;
+        readonly totalExecutionTime: number;
+        readonly averageExecutionTime: number;
+        readonly errorCount: number;
+        readonly lastExecuted?: Date;
+    };
+    readonly resolvedDependencies: string[];
+    readonly warnings: AnalysisWarning[];
+}
+export interface CommandOptions {
+    readonly validateInputs: boolean;
+    readonly trackPerformance: boolean;
+    readonly errorHandling: 'throw' | 'return' | 'ignore';
+    readonly timeout?: number;
+    readonly retry?: {
+        readonly attempts: number;
+        readonly delay: number;
+        readonly backoff: 'linear' | 'exponential';
+    };
+}
+export interface CommandAnalysis {
+    readonly complexity: number;
+    readonly requirements: string[];
+    readonly sideEffects: string[];
+    readonly typeInference: {
+        readonly inputTypes: string[];
+        readonly outputType: string;
+        readonly confidence: number;
+    };
+    readonly optimizations: string[];
+}
+export interface ArgumentAnalysis {
+    readonly isUsed: boolean;
+    readonly typeCompatibility: number;
+    readonly suggestions: string[];
+}
+export interface ProgramSourceInfo {
+    readonly element?: HTMLElement;
+    readonly attribute?: string;
+    readonly file?: string;
+    readonly position?: {
+        readonly line: number;
+        readonly column: number;
+    };
+}
+export interface SourceRange {
+    readonly start: number;
+    readonly end: number;
+    readonly lines?: {
+        readonly start: {
+            line: number;
+            column: number;
+        };
+        readonly end: {
+            line: number;
+            column: number;
+        };
+    };
+}
+export interface ProgramState {
+    readonly status: 'ready' | 'running' | 'completed' | 'error' | 'suspended';
+    readonly currentFeature?: string;
+    readonly context: {
+        readonly element: HTMLElement | null;
+        readonly variables: Map<string, HyperScriptValue>;
+        readonly callStack: string[];
+    };
+    readonly error?: HyperScriptError;
+    readonly startedAt?: Date;
+    readonly completedAt?: Date;
+}
+export interface AnalysisWarning {
+    readonly level: 'info' | 'warning' | 'error';
+    readonly message: string;
+    readonly location: SourceRange;
+    readonly suggestion?: string;
+    readonly category: 'performance' | 'compatibility' | 'security' | 'style' | 'type-safety';
+}
+export declare const HyperScriptProgramSchema: RuntimeValidator<{
+    [x: string]: unknown;
+}>;
+//# sourceMappingURL=command-types.d.ts.map

package/dist/types/context-types.d.ts

@@ -0,0 +1,106 @@
+import type { RuntimeValidator } from '../validation/lightweight-validators';
+import type { TypedExpressionContext, EvaluationType, ExpressionMetadata, ValidationResult } from './expression-types';
+import type { LLMDocumentation } from './command-types';
+import type { EvaluationResult } from './base-types';
+export type { EvaluationResult } from './base-types';
+export type ContextCategory = 'Frontend' | 'Backend' | 'Universal' | 'SSR' | 'Testing';
+export interface ContextMetadata extends Omit<ExpressionMetadata, 'category'> {
+    category: ContextCategory;
+    relatedContexts?: string[];
+    frameworkDependencies?: string[];
+    environmentRequirements?: {
+        browser?: boolean;
+        server?: boolean;
+        nodejs?: boolean;
+        python?: boolean;
+    };
+}
+export interface TypedContextImplementation<TInput, TOutput> {
+    readonly name: string;
+    readonly category: ContextCategory;
+    readonly description: string;
+    readonly inputSchema: RuntimeValidator<TInput>;
+    readonly outputType: EvaluationType;
+    readonly metadata: ContextMetadata;
+    readonly documentation?: LLMDocumentation;
+    initialize(input: TInput): Promise<EvaluationResult<TOutput>>;
+    validate(input: unknown): ValidationResult;
+    trackPerformance?(startTime: number, success: boolean, output?: any): void;
+}
+export declare abstract class ContextBase<TInput, TOutput> implements TypedContextImplementation<TInput, TOutput> {
+    abstract readonly name: string;
+    abstract readonly category: ContextCategory;
+    abstract readonly description: string;
+    abstract readonly inputSchema: RuntimeValidator<TInput>;
+    abstract readonly outputType: EvaluationType;
+    abstract readonly metadata: ContextMetadata;
+    abstract readonly documentation?: LLMDocumentation;
+    protected evaluationHistory: Array<{
+        contextName: string;
+        category: ContextCategory;
+        input: string;
+        output: any;
+        timestamp: number;
+        duration: number;
+        success: boolean;
+    }>;
+    abstract initialize(input: TInput): Promise<EvaluationResult<TOutput>>;
+    validate(input: unknown): ValidationResult;
+    protected validateContextSpecific(_data: TInput): ValidationResult;
+    protected generateValidationSuggestions(error: any): string[];
+    trackPerformance(startTime: number, success: boolean, output?: any): void;
+    getPerformanceMetrics(): {
+        totalInitializations: number;
+        successRate: number;
+        averageDuration: number;
+        recentPerformance: {
+            contextName: string;
+            category: ContextCategory;
+            input: string;
+            output: any;
+            timestamp: number;
+            duration: number;
+            success: boolean;
+        }[];
+    };
+}
+export declare const BaseContextInputSchema: RuntimeValidator<{
+    [x: string]: unknown;
+}>;
+export declare const BaseContextOutputSchema: RuntimeValidator<{
+    [x: string]: unknown;
+}>;
+export type BaseContextInput = any;
+export type BaseContextOutput = any;
+export interface ExtendedTypedExpressionContext extends TypedExpressionContext {
+    contextCategory?: ContextCategory;
+    framework?: {
+        name: 'django' | 'flask' | 'express' | 'fastapi' | 'vanilla';
+        version?: string;
+        capabilities?: string[];
+    };
+    performanceTracking?: {
+        enabled: boolean;
+        includeMemoryUsage: boolean;
+        includeNetworkMetrics: boolean;
+    };
+    services?: {
+        logger?: any;
+        cache?: any;
+        database?: any;
+        queue?: any;
+    };
+}
+export interface ContextRegistry {
+    register<T extends TypedContextImplementation<any, any>>(context: T): void;
+    get<_T>(name: string): TypedContextImplementation<any, any> | null;
+    listByCategory(category: ContextCategory): TypedContextImplementation<any, any>[];
+    validate<T extends TypedContextImplementation<any, any>>(context: T): ValidationResult;
+}
+export interface ContextFilter {
+    category?: ContextCategory;
+    environment?: 'frontend' | 'backend' | 'universal';
+    framework?: string;
+    capabilities?: string[];
+}
+//# sourceMappingURL=context-types.d.ts.map

package/dist/types/core-context.d.ts

@@ -0,0 +1,21 @@
+export interface CoreExecutionContext {
+    me: Element | null;
+    you: Element | null;
+    it: unknown;
+    readonly event?: Event | null;
+    readonly locals: Map<string, unknown>;
+    readonly globals: Map<string, unknown>;
+}
+export interface CoreContextOptions {
+    me?: Element | null;
+    you?: Element | null;
+    it?: unknown;
+    event?: Event | null;
+    locals?: Map<string, unknown>;
+    globals?: Map<string, unknown>;
+}
+export declare function createCoreContext(options?: CoreContextOptions): CoreExecutionContext;
+export declare function isCoreExecutionContext(value: unknown): value is CoreExecutionContext;
+export declare function assertHTMLElement(element: Element | null, name?: string): HTMLElement;
+export declare function asHTMLElement(element: Element | null): HTMLElement | null;
+//# sourceMappingURL=core-context.d.ts.map

package/dist/types/core.d.ts

@@ -0,0 +1,203 @@
+export type { ExecutionContext, TypedExecutionContext, EvaluationType, HyperScriptValueType, ValidationResult, ValidationError, TypedResult, EnhancedError, PerformanceCharacteristics, ASTNode, ParseError, ExpressionNode, CommandNode as BaseCommandNode, EventHandlerNode, BehaviorNode, DefNode, } from './base-types';
+import type { ExecutionContext, ASTNode, ExpressionNode, EvaluationType, ParseError } from './base-types';
+export type ElementType = 'command' | 'expression' | 'feature' | 'keyword' | 'special_symbol';
+export type ElementStatus = 'Draft' | 'Review' | 'Approved' | 'Deprecated';
+export type ExpressionCategory = 'Arithmetic' | 'Logical' | 'Comparison' | 'Reference' | 'Conversion' | 'Special';
+export type Associativity = 'Left' | 'Right' | 'None';
+export interface ExtendedExecutionContext extends ExecutionContext {
+    variables?: Map<string, unknown>;
+    events?: Map<string, {
+        target: HTMLElement;
+        event: string;
+        handler: Function;
+    }>;
+    parent?: ExtendedExecutionContext;
+    meta?: Record<string, unknown>;
+    flags?: {
+        halted: boolean;
+        breaking: boolean;
+        continuing: boolean;
+        returning: boolean;
+        async: boolean;
+    };
+}
+export interface CommandNode extends ASTNode {
+    type: 'command';
+    name: string;
+    args: ExpressionNode[];
+    body?: StatementNode[];
+    implicitTarget?: ExpressionNode;
+    isBlocking: boolean;
+    modifiers?: Record<string, ExpressionNode>;
+    originalCommand?: string;
+}
+export interface FeatureNode extends ASTNode {
+    type: 'feature';
+    name: string;
+    trigger?: string;
+    body: StatementNode[];
+    scope: 'global' | 'local' | 'behavior';
+}
+export interface StatementNode extends ASTNode {
+    type: 'statement';
+    command: CommandNode;
+    conditions?: ExpressionNode[];
+}
+export interface Runtime {
+    executeCommand(command: CommandNode, context: ExecutionContext): Promise<unknown>;
+    evaluateExpression(expression: ExpressionNode, context: ExecutionContext): Promise<unknown>;
+    createContext(parent?: ExecutionContext): ExecutionContext;
+    registerCommand(name: string, implementation: BaseCommandImplementation): void;
+    registerExpression(name: string, implementation: ExpressionImplementation): void;
+    registerFeature(name: string, implementation: FeatureImplementation): void;
+}
+export interface BaseCommandImplementation {
+    name: string;
+    syntax: string;
+    execute: (context: ExecutionContext, ...args: unknown[]) => Promise<unknown>;
+    isBlocking: boolean;
+    hasBody: boolean;
+    implicitTarget?: string;
+    implicitResult?: 'it' | 'result' | 'none';
+    validate?: (args: unknown[]) => string | null;
+}
+export interface LegacyValidationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: import('./base-types').ValidationError;
+}
+export interface CommandImplementation<TInput = unknown, TOutput = unknown, TContext = import('./base-types').ExecutionContext> {
+    metadata: {
+        name: string;
+        description: string;
+        examples: string[];
+        syntax: string;
+        category: string;
+        version: string;
+    };
+    validation: {
+        validate(input: unknown): import('./base-types').ValidationResult<TInput>;
+    };
+    execute(input: TInput, context: TContext): Promise<TOutput>;
+}
+export interface ExpressionImplementation {
+    name: string;
+    category: ExpressionCategory;
+    evaluatesTo: EvaluationType;
+    evaluate: (context: ExecutionContext, ...args: unknown[]) => Promise<unknown>;
+    precedence?: number;
+    associativity?: Associativity;
+    operators?: string[];
+    validate?: (args: unknown[]) => string | null;
+}
+export interface FeatureImplementation {
+    name: string;
+    trigger?: string;
+    install: (runtime: Runtime) => void;
+    uninstall?: (runtime: Runtime) => void;
+    scope: 'global' | 'local' | 'behavior';
+}
+export interface Token {
+    kind: string;
+    value: string;
+    start: number;
+    end: number;
+    line: number;
+    column: number;
+}
+export interface ParseWarning {
+    type: string;
+    message: string;
+    suggestions: string[];
+    severity: 'info' | 'warning' | 'error';
+    code?: string;
+    line?: number;
+    column?: number;
+}
+export interface ParseResult<T = ASTNode> {
+    success: boolean;
+    node?: T;
+    ast?: T;
+    error?: ParseError;
+    warnings?: ParseWarning[];
+    tokens: Token[];
+}
+export interface Parser {
+    parse(input: string): ParseResult<FeatureNode[]>;
+    parseExpression(input: string): ParseResult<ExpressionNode>;
+    parseCommand(input: string): ParseResult<CommandNode>;
+    tokenize(input: string): Token[];
+}
+export interface LSPElement {
+    id: number;
+    name: string;
+    description: string;
+    syntax_canonical: string;
+    status: ElementStatus;
+    tags: string[];
+    examples: LSPExample[];
+}
+export interface LSPCommand extends LSPElement {
+    purpose: string;
+    has_body: boolean;
+    is_blocking: boolean;
+    implicit_target?: string;
+    implicit_result_target?: string;
+    arguments?: LSPArgument[];
+}
+export interface LSPExpression extends LSPElement {
+    category: ExpressionCategory;
+    evaluates_to_type: EvaluationType;
+    precedence?: number;
+    associativity?: Associativity;
+    operators?: string[];
+}
+export interface LSPFeature extends LSPElement {
+    trigger?: string;
+    structure_description?: string;
+    scope_impact?: string;
+}
+export interface LSPExample {
+    id: number;
+    element_id: number;
+    element_type: ElementType;
+    example: string;
+    description?: string;
+    difficulty?: 'Beginner' | 'Intermediate' | 'Advanced';
+    html_context?: string;
+}
+export interface LSPArgument {
+    name: string;
+    type: string;
+    description: string;
+    optional: boolean;
+    default_value?: unknown;
+}
+export interface HyperscriptEvent extends CustomEvent {
+    detail: {
+        element: HTMLElement;
+        context: ExecutionContext;
+        command?: string;
+        result?: unknown;
+        error?: Error;
+    };
+}
+export interface HyperscriptConfig {
+    strict?: boolean;
+    debug?: boolean;
+    commands?: Record<string, BaseCommandImplementation>;
+    expressions?: Record<string, ExpressionImplementation>;
+    features?: Record<string, FeatureImplementation>;
+    globals?: Record<string, unknown>;
+    events?: {
+        bubbling?: boolean;
+        delegation?: boolean;
+        passive?: boolean;
+    };
+    performance?: {
+        cacheParsing?: boolean;
+        lazyLoading?: boolean;
+        bundleOptimization?: boolean;
+    };
+}
+//# sourceMappingURL=core.d.ts.map