@claudetools/tools 0.8.11 → 0.9.0

package/dist/codedna/kappa-validator.js

@@ -0,0 +1,638 @@
+// =============================================================================
+// Kappa v2.5 Semantic Validator
+// =============================================================================
+//
+// Validates Kappa AST for semantic correctness:
+// - Entity references point to defined entities
+// - Field types are valid
+// - Relationship targets exist
+// - API operations reference valid entities
+//
+// =============================================================================
+// Validator Class
+// =============================================================================
+export class KappaValidator {
+    errors = [];
+    warnings = [];
+    /** Set of all defined entity names */
+    entityNames = new Set();
+    /** Set of all defined API names */
+    apiNames = new Set();
+    /** Set of all defined page names */
+    pageNames = new Set();
+    /** Set of all defined form names */
+    formNames = new Set();
+    /** Set of all defined journey names */
+    journeyNames = new Set();
+    /**
+     * Validate a Kappa specification AST
+     */
+    validate(spec) {
+        this.reset();
+        // First pass: collect all defined names
+        this.collectDefinedNames(spec);
+        // Second pass: validate references
+        this.validateEntities(spec.entities);
+        this.validateAPIs(spec.apis);
+        this.validateJourneys(spec.journeys);
+        this.validatePages(spec.pages);
+        this.validateForms(spec.forms);
+        return {
+            valid: this.errors.length === 0,
+            errors: this.errors,
+            warnings: this.warnings,
+        };
+    }
+    reset() {
+        this.errors = [];
+        this.warnings = [];
+        this.entityNames.clear();
+        this.apiNames.clear();
+        this.pageNames.clear();
+        this.formNames.clear();
+        this.journeyNames.clear();
+    }
+    // ===========================================================================
+    // Name Collection (First Pass)
+    // ===========================================================================
+    collectDefinedNames(spec) {
+        // Collect entity names
+        for (const entity of spec.entities) {
+            if (this.entityNames.has(entity.name)) {
+                this.addError({
+                    code: 'DUPLICATE_ENTITY_NAME',
+                    message: `Duplicate entity name: '${entity.name}'`,
+                    location: entity.loc,
+                    context: { entityName: entity.name },
+                });
+            }
+            this.entityNames.add(entity.name);
+        }
+        // Collect API names
+        for (const api of spec.apis) {
+            if (this.apiNames.has(api.name)) {
+                this.addError({
+                    code: 'DUPLICATE_API_NAME',
+                    message: `Duplicate API name: '${api.name}'`,
+                    location: api.loc,
+                });
+            }
+            this.apiNames.add(api.name);
+        }
+        // Collect page names
+        for (const page of spec.pages) {
+            this.pageNames.add(page.name);
+        }
+        // Collect form names
+        for (const form of spec.forms) {
+            this.formNames.add(form.name);
+        }
+        // Collect journey names
+        for (const journey of spec.journeys) {
+            this.journeyNames.add(journey.name);
+        }
+    }
+    // ===========================================================================
+    // Entity Validation
+    // ===========================================================================
+    validateEntities(entities) {
+        for (const entity of entities) {
+            this.validateEntity(entity);
+        }
+    }
+    validateEntity(entity) {
+        const fieldNames = new Set();
+        let hasPrimaryKey = false;
+        // Validate fields
+        for (const field of entity.fields) {
+            // Check for duplicate field names
+            if (fieldNames.has(field.name)) {
+                this.addError({
+                    code: 'DUPLICATE_FIELD_NAME',
+                    message: `Duplicate field name '${field.name}' in entity '${entity.name}'`,
+                    location: field.loc,
+                    context: { entityName: entity.name, fieldName: field.name },
+                });
+            }
+            fieldNames.add(field.name);
+            // Check for multiple primary keys
+            if (field.modifiers.includes('primary')) {
+                if (hasPrimaryKey) {
+                    this.addError({
+                        code: 'DUPLICATE_PRIMARY_KEY',
+                        message: `Entity '${entity.name}' has multiple primary keys`,
+                        location: field.loc,
+                        context: { entityName: entity.name, fieldName: field.name },
+                    });
+                }
+                hasPrimaryKey = true;
+            }
+            // Validate field type references
+            this.validateFieldType(field.type, field.loc, entity.name, field.name);
+            // Validate modifiers for type
+            this.validateModifiersForType(field, entity.name);
+        }
+        // Validate relationships
+        for (const relationship of entity.relationships) {
+            this.validateRelationship(relationship, entity.name);
+        }
+        // Validate capabilities
+        for (const capability of entity.capabilities) {
+            this.validateCapability(capability, entity.name);
+        }
+    }
+    validateFieldType(type, location, entityName, fieldName) {
+        switch (type.kind) {
+            case 'reference':
+                if (!this.entityNames.has(type.entity)) {
+                    this.addError({
+                        code: 'UNDEFINED_ENTITY_REFERENCE',
+                        message: `Field '${fieldName}' references undefined entity '${type.entity}'`,
+                        location,
+                        context: { entityName, fieldName, referencedEntity: type.entity },
+                    });
+                }
+                break;
+            case 'enum':
+                // Check for empty enum
+                if (type.values.length === 0) {
+                    this.addError({
+                        code: 'EMPTY_ENUM',
+                        message: `Enum field '${fieldName}' has no values`,
+                        location,
+                        context: { entityName, fieldName },
+                    });
+                }
+                // Check for duplicate enum values
+                const enumValues = new Set();
+                for (const value of type.values) {
+                    if (enumValues.has(value)) {
+                        this.addError({
+                            code: 'DUPLICATE_ENUM_VALUE',
+                            message: `Enum field '${fieldName}' has duplicate value '${value}'`,
+                            location,
+                            context: { entityName, fieldName },
+                        });
+                    }
+                    enumValues.add(value);
+                }
+                break;
+            case 'primitive':
+                // Validate range constraints
+                if (type.range) {
+                    const { min, max } = type.range;
+                    if (min !== undefined && max !== undefined && min > max) {
+                        this.addError({
+                            code: 'INVALID_RANGE',
+                            message: `Field '${fieldName}' has invalid range: min (${min}) > max (${max})`,
+                            location,
+                            context: { entityName, fieldName },
+                        });
+                    }
+                    if (min !== undefined && min < 0 && type.type === 'string') {
+                        this.addError({
+                            code: 'INVALID_RANGE',
+                            message: `String field '${fieldName}' cannot have negative min length (${min})`,
+                            location,
+                            context: { entityName, fieldName },
+                        });
+                    }
+                }
+                break;
+            case 'array':
+                // Recursively validate array item type
+                this.validateFieldType(type.itemType, location, entityName, fieldName);
+                break;
+        }
+    }
+    validateModifiersForType(field, entityName) {
+        const { type, modifiers, loc, name } = field;
+        // 'hashed' is only valid on string types
+        if (modifiers.includes('hashed')) {
+            if (type.kind !== 'primitive' || type.type !== 'string') {
+                this.addError({
+                    code: 'INVALID_MODIFIER_FOR_TYPE',
+                    message: `Modifier 'hashed' is only valid on string fields, but '${name}' is not a string`,
+                    location: loc,
+                    context: { entityName, fieldName: name },
+                });
+            }
+        }
+        // 'auto' is only valid on uuid, timestamp, or int (for auto-increment)
+        if (modifiers.includes('auto')) {
+            const validAutoTypes = ['uuid', 'timestamp', 'int'];
+            if (type.kind !== 'primitive' || !validAutoTypes.includes(type.type)) {
+                this.addWarning({
+                    code: 'INVALID_MODIFIER_FOR_TYPE',
+                    message: `Modifier 'auto' on '${name}' may not work as expected for type '${type.kind === 'primitive' ? type.type : type.kind}'`,
+                    location: loc,
+                    context: { entityName, fieldName: name },
+                });
+            }
+        }
+        // 'primary' and 'optional' are conflicting
+        if (modifiers.includes('primary') && modifiers.includes('optional')) {
+            this.addError({
+                code: 'CONFLICTING_MODIFIERS',
+                message: `Field '${name}' cannot be both 'primary' and 'optional'`,
+                location: loc,
+                context: { entityName, fieldName: name },
+            });
+        }
+        // 'unique' on reference types is usually a warning (might be intentional)
+        if (modifiers.includes('unique') && type.kind === 'reference') {
+            this.addWarning({
+                code: 'INVALID_MODIFIER_FOR_TYPE',
+                message: `Modifier 'unique' on reference field '${name}' creates a one-to-one relationship`,
+                location: loc,
+                context: { entityName, fieldName: name },
+            });
+        }
+        // 'immutable' and 'auto' with 'on_update' is conflicting
+        if (modifiers.includes('immutable') && field.updateTrigger) {
+            this.addError({
+                code: 'CONFLICTING_MODIFIERS',
+                message: `Field '${name}' cannot be 'immutable' with update trigger`,
+                location: loc,
+                context: { entityName, fieldName: name },
+            });
+        }
+        // 'internal' is only useful on fields that would otherwise be exposed
+        if (modifiers.includes('internal') && modifiers.includes('hashed')) {
+            // This is fine - password fields are commonly internal + hashed
+        }
+    }
+    validateRelationship(relationship, entityName) {
+        // Check if target entity exists
+        if (!this.entityNames.has(relationship.entity)) {
+            this.addError({
+                code: 'UNDEFINED_ENTITY_REFERENCE',
+                message: `Relationship references undefined entity '${relationship.entity}'`,
+                location: relationship.loc,
+                context: { entityName, referencedEntity: relationship.entity },
+            });
+        }
+        // Check if through entity exists (for many-to-many)
+        if (relationship.through && !this.entityNames.has(relationship.through)) {
+            this.addError({
+                code: 'UNDEFINED_THROUGH_ENTITY',
+                message: `Relationship 'through' references undefined entity '${relationship.through}'`,
+                location: relationship.loc,
+                context: { entityName, referencedEntity: relationship.through },
+            });
+        }
+    }
+    validateCapability(capability, entityName) {
+        // Check if target entity exists (when specified)
+        if (capability.target && !this.entityNames.has(capability.target)) {
+            this.addError({
+                code: 'UNDEFINED_CAPABILITY_TARGET',
+                message: `Capability references undefined entity '${capability.target}'`,
+                location: capability.loc,
+                context: { entityName, referencedEntity: capability.target },
+            });
+        }
+    }
+    // ===========================================================================
+    // API Validation
+    // ===========================================================================
+    validateAPIs(apis) {
+        for (const api of apis) {
+            this.validateAPI(api);
+        }
+    }
+    validateAPI(api) {
+        // Validate CRUD shorthands
+        for (const crud of api.crud) {
+            this.validateCRUD(crud, api.name);
+        }
+        // Validate operations
+        for (const operation of api.operations) {
+            this.validateAPIOperation(operation, api.name);
+        }
+    }
+    validateCRUD(crud, apiName) {
+        // Check if CRUD target entity exists
+        if (!this.entityNames.has(crud.entity)) {
+            this.addError({
+                code: 'UNDEFINED_CRUD_ENTITY',
+                message: `CRUD shorthand references undefined entity '${crud.entity}'`,
+                location: crud.loc,
+                context: { referencedEntity: crud.entity },
+            });
+        }
+    }
+    validateAPIOperation(operation, apiName) {
+        const operationContext = `${apiName}.${operation.name}`;
+        // Validate return type entity reference
+        const returnType = operation.returnType.type;
+        // Skip validation for void and object types
+        if (returnType !== 'void' && !returnType.startsWith('{')) {
+            // Check if it's an entity reference
+            if (!this.entityNames.has(returnType)) {
+                // Could be a primitive or inline type - just warn for now
+                this.addWarning({
+                    code: 'UNDEFINED_RETURN_TYPE_ENTITY',
+                    message: `API operation '${operation.name}' returns unknown type '${returnType}'`,
+                    location: operation.loc,
+                });
+            }
+        }
+        // Validate joined entities in return type
+        if (operation.returnType.joined) {
+            for (const join of operation.returnType.joined) {
+                if (!this.entityNames.has(join.entity)) {
+                    this.addError({
+                        code: 'UNDEFINED_JOINED_ENTITY',
+                        message: `API operation '${operation.name}' joins undefined entity '${join.entity}'`,
+                        location: operation.returnType.loc,
+                        context: { referencedEntity: join.entity },
+                    });
+                }
+            }
+        }
+        // Validate effect annotations
+        const validEffects = new Set(['DB', 'Auth', 'Email', 'Audit', 'Queue', 'Cache', 'External']);
+        for (const effect of operation.effects) {
+            if (!validEffects.has(effect)) {
+                this.addError({
+                    code: 'INVALID_EFFECT_TYPE',
+                    message: `API operation '${operation.name}' has invalid effect '${effect}'`,
+                    location: operation.loc,
+                });
+            }
+        }
+        // Validate parameter types and check for duplicates
+        const paramNames = new Set();
+        for (const param of operation.parameters) {
+            // Check for duplicate parameter names
+            if (paramNames.has(param.name)) {
+                this.addError({
+                    code: 'DUPLICATE_PARAMETER_NAME',
+                    message: `API operation '${operation.name}' has duplicate parameter '${param.name}'`,
+                    location: param.loc,
+                });
+            }
+            paramNames.add(param.name);
+            // Validate parameter type
+            this.validateFieldType(param.type, param.loc, operationContext, param.name);
+        }
+    }
+    // ===========================================================================
+    // Journey Validation
+    // ===========================================================================
+    validateJourneys(journeys) {
+        for (const journey of journeys) {
+            this.validateJourney(journey);
+        }
+    }
+    validateJourney(journey) {
+        const stepNames = new Set();
+        for (const step of journey.steps) {
+            stepNames.add(step.name);
+        }
+        // Validate step references
+        for (const step of journey.steps) {
+            // Check if 'next' step exists
+            if (step.next && !stepNames.has(step.next)) {
+                this.addError({
+                    code: 'UNDEFINED_PAGE_REFERENCE',
+                    message: `Journey step '${step.name}' references undefined next step '${step.next}'`,
+                    location: step.loc,
+                });
+            }
+            // Check if page exists
+            if (step.page && !this.pageNames.has(step.page) && !this.formNames.has(step.page)) {
+                this.addWarning({
+                    code: 'UNDEFINED_PAGE_REFERENCE',
+                    message: `Journey step '${step.name}' references undefined page '${step.page}'`,
+                    location: step.loc,
+                });
+            }
+        }
+        // Validate recovery handlers
+        for (const recovery of journey.recovery) {
+            if (!stepNames.has(recovery.step)) {
+                this.addError({
+                    code: 'UNDEFINED_PAGE_REFERENCE',
+                    message: `Recovery handler references undefined step '${recovery.step}'`,
+                    location: recovery.loc,
+                });
+            }
+        }
+    }
+    // ===========================================================================
+    // Page Validation
+    // ===========================================================================
+    validatePages(pages) {
+        for (const page of pages) {
+            this.validatePage(page);
+        }
+    }
+    validatePage(page) {
+        // Validate component reference
+        if (page.component && !this.formNames.has(page.component)) {
+            // Component might be an external component - just warn
+            this.addWarning({
+                code: 'UNDEFINED_PAGE_REFERENCE',
+                message: `Page '${page.name}' references component '${page.component}' which is not defined in the spec`,
+                location: page.loc,
+            });
+        }
+    }
+    // ===========================================================================
+    // Form Validation
+    // ===========================================================================
+    validateForms(forms) {
+        for (const form of forms) {
+            this.validateForm(form);
+        }
+    }
+    validateForm(form) {
+        const fieldNames = new Set();
+        for (const field of form.fields) {
+            // Check for duplicate field names
+            if (fieldNames.has(field.name)) {
+                this.addError({
+                    code: 'DUPLICATE_FIELD_NAME',
+                    message: `Duplicate field name '${field.name}' in form '${form.name}'`,
+                    location: field.loc,
+                });
+            }
+            fieldNames.add(field.name);
+        }
+        // Validate layout references
+        for (const row of form.layout) {
+            for (const fieldRef of row.fields) {
+                if (!fieldNames.has(fieldRef)) {
+                    this.addError({
+                        code: 'UNDEFINED_PAGE_REFERENCE',
+                        message: `Form layout references undefined field '${fieldRef}'`,
+                        location: row.loc,
+                    });
+                }
+            }
+        }
+    }
+    // ===========================================================================
+    // Helper Methods
+    // ===========================================================================
+    addError(error) {
+        this.errors.push(error);
+    }
+    addWarning(warning) {
+        this.warnings.push(warning);
+    }
+}
+// =============================================================================
+// Convenience Function
+// =============================================================================
+/**
+ * Validate a Kappa specification AST
+ */
+export function validateKappaSpec(spec) {
+    const validator = new KappaValidator();
+    return validator.validate(spec);
+}
+/**
+ * Format a validation error for display (simple format)
+ */
+export function formatValidationError(error) {
+    const { code, message, location, context } = error;
+    const locStr = `${location.startLine}:${location.startColumn}`;
+    let contextStr = '';
+    if (context) {
+        const parts = [];
+        if (context.entityName)
+            parts.push(`entity: ${context.entityName}`);
+        if (context.fieldName)
+            parts.push(`field: ${context.fieldName}`);
+        if (context.referencedEntity)
+            parts.push(`references: ${context.referencedEntity}`);
+        if (parts.length > 0) {
+            contextStr = ` (${parts.join(', ')})`;
+        }
+    }
+    return `[${code}] ${locStr}: ${message}${contextStr}`;
+}
+/**
+ * Format a validation error with code snippet and visual indicators
+ */
+export function formatValidationErrorRich(error, options = {}) {
+    const { code, message, location, context } = error;
+    const { source, colors = false, contextLines = 1 } = options;
+    const lines = [];
+    // Error header with location
+    const locStr = `${location.startLine}:${location.startColumn}`;
+    const header = colors
+        ? `\x1b[31merror\x1b[0m[\x1b[33m${code}\x1b[0m]: ${message}`
+        : `error[${code}]: ${message}`;
+    lines.push(header);
+    // Location pointer
+    const locationLine = colors
+        ? `  \x1b[36m-->\x1b[0m ${locStr}`
+        : `  --> ${locStr}`;
+    lines.push(locationLine);
+    // Code snippet if source is provided
+    if (source) {
+        const sourceLines = source.split('\n');
+        const errorLine = location.startLine;
+        const startLine = Math.max(1, errorLine - contextLines);
+        const endLine = Math.min(sourceLines.length, errorLine + contextLines);
+        // Calculate gutter width based on line numbers
+        const gutterWidth = String(endLine).length;
+        lines.push('   |');
+        for (let i = startLine; i <= endLine; i++) {
+            const lineContent = sourceLines[i - 1] || '';
+            const lineNum = String(i).padStart(gutterWidth, ' ');
+            if (i === errorLine) {
+                // Error line - highlight it
+                const prefix = colors ? `\x1b[31m${lineNum}\x1b[0m |` : `${lineNum} |`;
+                lines.push(`${prefix} ${lineContent}`);
+                // Add caret pointer
+                const caretPadding = ' '.repeat(location.startColumn - 1);
+                const caretLength = Math.max(1, Math.min(location.endColumn - location.startColumn, lineContent.length - location.startColumn + 1));
+                const caret = '^'.repeat(caretLength);
+                const caretLine = colors
+                    ? `${''.padStart(gutterWidth, ' ')} | ${caretPadding}\x1b[31m${caret}\x1b[0m`
+                    : `${''.padStart(gutterWidth, ' ')} | ${caretPadding}${caret}`;
+                lines.push(caretLine);
+            }
+            else {
+                // Context line
+                const prefix = colors
+                    ? `\x1b[90m${lineNum}\x1b[0m |`
+                    : `${lineNum} |`;
+                const content = colors ? `\x1b[90m${lineContent}\x1b[0m` : lineContent;
+                lines.push(`${prefix} ${content}`);
+            }
+        }
+        lines.push('   |');
+    }
+    // Add context info if available
+    if (context) {
+        const parts = [];
+        if (context.entityName)
+            parts.push(`entity: ${context.entityName}`);
+        if (context.fieldName)
+            parts.push(`field: ${context.fieldName}`);
+        if (context.referencedEntity)
+            parts.push(`references: ${context.referencedEntity}`);
+        if (parts.length > 0) {
+            const contextLine = colors
+                ? `  \x1b[90m= note: ${parts.join(', ')}\x1b[0m`
+                : `  = note: ${parts.join(', ')}`;
+            lines.push(contextLine);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format all validation results for display
+ */
+export function formatValidationResults(result, options = {}) {
+    const sections = [];
+    // Format errors
+    if (result.errors.length > 0) {
+        for (const error of result.errors) {
+            sections.push(formatValidationErrorRich(error, options));
+        }
+    }
+    // Format warnings
+    if (result.warnings.length > 0) {
+        const warningOptions = { ...options };
+        for (const warning of result.warnings) {
+            // Modify message to indicate it's a warning
+            const warningError = {
+                ...warning,
+                message: `(warning) ${warning.message}`,
+            };
+            sections.push(formatValidationErrorRich(warningError, warningOptions));
+        }
+    }
+    // Summary
+    const errorCount = result.errors.length;
+    const warningCount = result.warnings.length;
+    const summaryParts = [];
+    if (errorCount > 0) {
+        const errorText = errorCount === 1 ? 'error' : 'errors';
+        summaryParts.push(options.colors
+            ? `\x1b[31m${errorCount} ${errorText}\x1b[0m`
+            : `${errorCount} ${errorText}`);
+    }
+    if (warningCount > 0) {
+        const warningText = warningCount === 1 ? 'warning' : 'warnings';
+        summaryParts.push(options.colors
+            ? `\x1b[33m${warningCount} ${warningText}\x1b[0m`
+            : `${warningCount} ${warningText}`);
+    }
+    if (summaryParts.length > 0) {
+        sections.push(`\nFound ${summaryParts.join(' and ')}`);
+    }
+    else {
+        sections.push(options.colors
+            ? `\n\x1b[32m✓ Validation passed\x1b[0m`
+            : '\n✓ Validation passed');
+    }
+    return sections.join('\n\n');
+}

package/dist/codedna/kappa-zod-generator.d.ts

@@ -0,0 +1,32 @@
+import type { EntityBlock } from './kappa-ast.js';
+export interface ZodGeneratorOptions {
+    /** Add provenance comments (default: true) */
+    provenance?: boolean;
+    /** Generate update schemas with partial fields (default: true) */
+    updateSchemas?: boolean;
+    /** Generate form schemas (default: false) */
+    formSchemas?: boolean;
+}
+export interface GeneratedZodSchemas {
+    /** Main schemas file content */
+    schemas: string;
+}
+export declare class KappaZodGenerator {
+    private provenance;
+    private updateSchemas;
+    private formSchemas;
+    constructor(options?: ZodGeneratorOptions);
+    /**
+     * Generate Zod schemas from entity blocks
+     */
+    generate(entities: EntityBlock[]): GeneratedZodSchemas;
+    private generateSchemasFile;
+    private generateEntitySchemas;
+    private generateFieldSchema;
+    private typeToZodSchema;
+    private primitiveToZod;
+}
+/**
+ * Generate Zod schemas from Kappa entities
+ */
+export declare function generateZodSchemas(entities: EntityBlock[], options?: ZodGeneratorOptions): GeneratedZodSchemas;