@claudetools/tools 0.8.10 → 0.9.0

package/dist/codedna/kappa-provenance.d.ts

@@ -0,0 +1,101 @@
+import type { SourceLocation, EntityBlock, EntityField } from './kappa-ast.js';
+export interface ProvenanceOptions {
+    /** Path to the Kappa spec file (optional) */
+    specFile?: string;
+    /** Include timestamp in header (default: true) */
+    timestamp?: boolean;
+    /** Include field-level provenance (default: false) */
+    fieldLevel?: boolean;
+    /** Comment style (default: 'line') */
+    style?: 'line' | 'block' | 'jsdoc';
+}
+export interface ProvenanceInfo {
+    /** Entity name */
+    entity: string;
+    /** Field name (if field-level) */
+    field?: string;
+    /** Source location in the spec */
+    location: SourceLocation;
+    /** Spec file path */
+    specFile?: string;
+}
+export declare class ProvenanceGenerator {
+    private options;
+    constructor(options?: ProvenanceOptions);
+    /**
+     * Generate file header comment
+     */
+    generateHeader(): string;
+    /**
+     * Generate provenance comment for an entity
+     */
+    generateEntityProvenance(entity: EntityBlock): string;
+    /**
+     * Generate provenance comment for a field
+     */
+    generateFieldProvenance(entity: EntityBlock, field: EntityField): string;
+    /**
+     * Generate inline provenance reference
+     */
+    generateInlineRef(info: ProvenanceInfo): string;
+    /**
+     * Format a source location for display
+     */
+    formatLocation(loc: SourceLocation): string;
+    /**
+     * Generate regeneration warning
+     */
+    generateWarning(): string;
+}
+/**
+ * Generate a file header with provenance info
+ */
+export declare function generateProvenanceHeader(options?: ProvenanceOptions): string;
+/**
+ * Generate provenance comment for an entity
+ */
+export declare function generateEntityProvenance(entity: EntityBlock, options?: ProvenanceOptions): string;
+/**
+ * Generate provenance comment for a field
+ */
+export declare function generateFieldProvenance(entity: EntityBlock, field: EntityField, options?: ProvenanceOptions): string;
+/**
+ * Wrap generated code with provenance header and footer
+ */
+export declare function wrapWithProvenance(code: string, options?: ProvenanceOptions): string;
+export interface SourceMapEntry {
+    /** Generated line number */
+    generatedLine: number;
+    /** Generated column */
+    generatedColumn: number;
+    /** Original source location */
+    originalLocation: SourceLocation;
+    /** Entity name */
+    entity: string;
+    /** Field name (optional) */
+    field?: string;
+}
+/**
+ * Create a source map for generated code
+ */
+export declare class ProvenanceSourceMap {
+    private entries;
+    private specFile?;
+    constructor(specFile?: string);
+    /**
+     * Add a mapping entry
+     */
+    addMapping(generatedLine: number, generatedColumn: number, originalLocation: SourceLocation, entity: string, field?: string): void;
+    /**
+     * Find the original location for a generated position
+     */
+    findOriginal(line: number, column: number): SourceMapEntry | undefined;
+    /**
+     * Export as JSON for tooling integration
+     */
+    toJSON(): object;
+    /**
+     * Generate inline source map comment
+     */
+    toInlineComment(): string;
+}

package/dist/codedna/kappa-provenance.js

@@ -0,0 +1,199 @@
+// =============================================================================
+// Kappa v2.5 Provenance Comments
+// =============================================================================
+//
+// Utilities for adding provenance comments to generated code.
+// Links generated code back to the original Kappa specification.
+//
+// =============================================================================
+// Comment Formatters
+// =============================================================================
+/**
+ * Format a single-line comment
+ */
+function lineComment(text) {
+    return `// ${text}`;
+}
+/**
+ * Format a block comment
+ */
+function blockComment(lines) {
+    if (lines.length === 1) {
+        return `/* ${lines[0]} */`;
+    }
+    return ['/*', ...lines.map(l => ` * ${l}`), ' */'].join('\n');
+}
+/**
+ * Format a JSDoc comment
+ */
+function jsdocComment(lines) {
+    return ['/**', ...lines.map(l => ` * ${l}`), ' */'].join('\n');
+}
+// =============================================================================
+// Provenance Generator
+// =============================================================================
+export class ProvenanceGenerator {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            specFile: options.specFile ?? '',
+            timestamp: options.timestamp ?? true,
+            fieldLevel: options.fieldLevel ?? false,
+            style: options.style ?? 'line',
+        };
+    }
+    /**
+     * Generate file header comment
+     */
+    generateHeader() {
+        const lines = ['Generated by Kappa v2.5 CodeDNA'];
+        if (this.options.specFile) {
+            lines.push(`Source: ${this.options.specFile}`);
+        }
+        if (this.options.timestamp) {
+            lines.push(`Generated at: ${new Date().toISOString()}`);
+        }
+        lines.push('');
+        lines.push('DO NOT EDIT - Changes will be overwritten on regeneration.');
+        switch (this.options.style) {
+            case 'block':
+                return blockComment(lines);
+            case 'jsdoc':
+                return jsdocComment(lines);
+            default:
+                return lines.map(l => lineComment(l)).join('\n');
+        }
+    }
+    /**
+     * Generate provenance comment for an entity
+     */
+    generateEntityProvenance(entity) {
+        const loc = entity.loc;
+        const locStr = this.formatLocation(loc);
+        const lines = [`Entity: ${entity.name}`, `Defined at: ${locStr}`];
+        switch (this.options.style) {
+            case 'block':
+                return blockComment(lines);
+            case 'jsdoc':
+                return jsdocComment(lines);
+            default:
+                return lines.map(l => lineComment(l)).join('\n');
+        }
+    }
+    /**
+     * Generate provenance comment for a field
+     */
+    generateFieldProvenance(entity, field) {
+        if (!this.options.fieldLevel) {
+            return '';
+        }
+        const loc = field.loc;
+        const locStr = this.formatLocation(loc);
+        return lineComment(`${entity.name}.${field.name} @ ${locStr}`);
+    }
+    /**
+     * Generate inline provenance reference
+     */
+    generateInlineRef(info) {
+        const locStr = this.formatLocation(info.location);
+        const ref = info.field
+            ? `${info.entity}.${info.field}`
+            : info.entity;
+        return lineComment(`@kappa ${ref} @ ${locStr}`);
+    }
+    /**
+     * Format a source location for display
+     */
+    formatLocation(loc) {
+        const file = this.options.specFile ? `${this.options.specFile}:` : '';
+        return `${file}${loc.startLine}:${loc.startColumn}`;
+    }
+    /**
+     * Generate regeneration warning
+     */
+    generateWarning() {
+        return lineComment('WARNING: This file is auto-generated. Do not modify manually.');
+    }
+}
+// =============================================================================
+// Convenience Functions
+// =============================================================================
+/**
+ * Generate a file header with provenance info
+ */
+export function generateProvenanceHeader(options = {}) {
+    const generator = new ProvenanceGenerator(options);
+    return generator.generateHeader();
+}
+/**
+ * Generate provenance comment for an entity
+ */
+export function generateEntityProvenance(entity, options = {}) {
+    const generator = new ProvenanceGenerator(options);
+    return generator.generateEntityProvenance(entity);
+}
+/**
+ * Generate provenance comment for a field
+ */
+export function generateFieldProvenance(entity, field, options = {}) {
+    const generator = new ProvenanceGenerator(options);
+    return generator.generateFieldProvenance(entity, field);
+}
+/**
+ * Wrap generated code with provenance header and footer
+ */
+export function wrapWithProvenance(code, options = {}) {
+    const generator = new ProvenanceGenerator(options);
+    const header = generator.generateHeader();
+    const warning = generator.generateWarning();
+    return `${header}\n\n${code}\n\n${warning}\n`;
+}
+/**
+ * Create a source map for generated code
+ */
+export class ProvenanceSourceMap {
+    entries = [];
+    specFile;
+    constructor(specFile) {
+        this.specFile = specFile;
+    }
+    /**
+     * Add a mapping entry
+     */
+    addMapping(generatedLine, generatedColumn, originalLocation, entity, field) {
+        this.entries.push({
+            generatedLine,
+            generatedColumn,
+            originalLocation,
+            entity,
+            field,
+        });
+    }
+    /**
+     * Find the original location for a generated position
+     */
+    findOriginal(line, column) {
+        // Find the closest entry at or before the given position
+        return this.entries
+            .filter(e => e.generatedLine <= line)
+            .sort((a, b) => b.generatedLine - a.generatedLine)[0];
+    }
+    /**
+     * Export as JSON for tooling integration
+     */
+    toJSON() {
+        return {
+            version: 1,
+            specFile: this.specFile,
+            mappings: this.entries,
+        };
+    }
+    /**
+     * Generate inline source map comment
+     */
+    toInlineComment() {
+        const json = JSON.stringify(this.toJSON());
+        const base64 = Buffer.from(json).toString('base64');
+        return `//# kappaSourceMap=${base64}`;
+    }
+}

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

@@ -0,0 +1,37 @@
+import type { EntityBlock } from './kappa-ast.js';
+export interface TypesGeneratorOptions {
+    /** Add provenance comments (default: true) */
+    provenance?: boolean;
+    /** Generate insert types (default: true) */
+    insertTypes?: boolean;
+    /** Generate update types (default: true) */
+    updateTypes?: boolean;
+    /** Export as interfaces vs type aliases (default: 'interface') */
+    style?: 'interface' | 'type';
+    /** Add JSDoc comments from field descriptions (default: true) */
+    jsdoc?: boolean;
+}
+export interface GeneratedTypes {
+    /** Types file content */
+    types: string;
+}
+export declare class KappaTypesGenerator {
+    private provenance;
+    private insertTypes;
+    private updateTypes;
+    private style;
+    private jsdoc;
+    constructor(options?: TypesGeneratorOptions);
+    /**
+     * Generate TypeScript types from entity blocks
+     */
+    generate(entities: EntityBlock[]): GeneratedTypes;
+    private generateTypesFile;
+    private generateEntityTypes;
+    private generateType;
+    private fieldTypeToTS;
+}
+/**
+ * Generate TypeScript types from Kappa entities
+ */
+export declare function generateTypeScriptTypes(entities: EntityBlock[], options?: TypesGeneratorOptions): GeneratedTypes;

package/dist/codedna/kappa-types-generator.js

@@ -0,0 +1,159 @@
+// =============================================================================
+// Kappa v2.5 TypeScript Types Generator
+// =============================================================================
+//
+// Generates pure TypeScript interfaces from Kappa entity blocks.
+// No runtime dependencies - types only.
+//
+// =============================================================================
+// Type Mappings
+// =============================================================================
+const PRIMITIVE_TYPE_MAP = {
+    string: 'string',
+    int: 'number',
+    float: 'number',
+    bool: 'boolean',
+    email: 'string',
+    url: 'string',
+    uuid: 'string',
+    phone: 'string',
+    slug: 'string',
+    markdown: 'string',
+    json: 'Record<string, unknown>',
+    timestamp: 'Date',
+    date: 'string',
+    time: 'string',
+    duration: 'string',
+};
+// =============================================================================
+// Generator Class
+// =============================================================================
+export class KappaTypesGenerator {
+    provenance;
+    insertTypes;
+    updateTypes;
+    style;
+    jsdoc;
+    constructor(options = {}) {
+        this.provenance = options.provenance ?? true;
+        this.insertTypes = options.insertTypes ?? true;
+        this.updateTypes = options.updateTypes ?? true;
+        this.style = options.style ?? 'interface';
+        this.jsdoc = options.jsdoc ?? true;
+    }
+    /**
+     * Generate TypeScript types from entity blocks
+     */
+    generate(entities) {
+        const types = this.generateTypesFile(entities);
+        return { types };
+    }
+    // ===========================================================================
+    // Types File Generation
+    // ===========================================================================
+    generateTypesFile(entities) {
+        const lines = [];
+        // Header comment
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Generated at: ${new Date().toISOString()}`);
+            lines.push('');
+        }
+        // Generate types for each entity
+        for (const entity of entities) {
+            lines.push(this.generateEntityTypes(entity));
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    generateEntityTypes(entity) {
+        const lines = [];
+        // Main type (for select/read - all fields)
+        if (this.jsdoc) {
+            lines.push(`/** ${entity.name} entity */`);
+        }
+        lines.push(this.generateType(entity.name, entity.fields));
+        // Insert type (excludes auto-generated fields, makes optional fields optional)
+        if (this.insertTypes) {
+            lines.push('');
+            const insertFields = entity.fields.filter(f => !f.modifiers.includes('auto'));
+            if (this.jsdoc) {
+                lines.push(`/** Data required to create a new ${entity.name} */`);
+            }
+            lines.push(this.generateType(`New${entity.name}`, insertFields, { forInsert: true }));
+        }
+        // Update type (all fields optional, excludes auto fields)
+        if (this.updateTypes) {
+            lines.push('');
+            if (this.jsdoc) {
+                lines.push(`/** Data for updating an existing ${entity.name} */`);
+            }
+            // If insert types are enabled, reference NewEntity; otherwise reference main Entity
+            const baseType = this.insertTypes ? `New${entity.name}` : entity.name;
+            if (this.style === 'interface') {
+                lines.push(`export interface Update${entity.name} extends Partial<${baseType}> {}`);
+            }
+            else {
+                lines.push(`export type Update${entity.name} = Partial<${baseType}>;`);
+            }
+        }
+        return lines.join('\n');
+    }
+    generateType(name, fields, options = {}) {
+        const lines = [];
+        if (this.style === 'interface') {
+            lines.push(`export interface ${name} {`);
+        }
+        else {
+            lines.push(`export type ${name} = {`);
+        }
+        for (const field of fields) {
+            const { name: fieldName, type, modifiers } = field;
+            const tsType = this.fieldTypeToTS(type);
+            const isOptional = modifiers.includes('optional');
+            const isPrimary = modifiers.includes('primary');
+            const isAuto = modifiers.includes('auto');
+            // Determine if field should be optional in output
+            let optional = isOptional;
+            if (options.forInsert && isPrimary && isAuto) {
+                optional = true; // Auto-generated primary keys are optional on insert
+            }
+            const optionalMark = optional ? '?' : '';
+            const nullableMark = isOptional ? ' | null' : '';
+            lines.push(`  ${fieldName}${optionalMark}: ${tsType}${nullableMark};`);
+        }
+        if (this.style === 'interface') {
+            lines.push('}');
+        }
+        else {
+            lines.push('};');
+        }
+        return lines.join('\n');
+    }
+    fieldTypeToTS(type) {
+        switch (type.kind) {
+            case 'primitive':
+                return PRIMITIVE_TYPE_MAP[type.type];
+            case 'enum':
+                return type.values.map(v => `'${v}'`).join(' | ');
+            case 'reference':
+                // Reference fields are strings (usually UUIDs)
+                return 'string';
+            case 'array':
+                const itemType = this.fieldTypeToTS(type.itemType);
+                return `${itemType}[]`;
+            default:
+                return 'unknown';
+        }
+    }
+}
+// =============================================================================
+// Convenience Function
+// =============================================================================
+/**
+ * Generate TypeScript types from Kappa entities
+ */
+export function generateTypeScriptTypes(entities, options = {}) {
+    const generator = new KappaTypesGenerator(options);
+    return generator.generate(entities);
+}

package/dist/codedna/kappa-validator.d.ts

@@ -0,0 +1,86 @@
+import type { KappaSpec, SourceLocation } from './kappa-ast.js';
+export interface ValidationError {
+    /** Error code for programmatic handling */
+    code: ValidationErrorCode;
+    /** Human-readable message */
+    message: string;
+    /** Source location in the spec */
+    location: SourceLocation;
+    /** Related entity/field names for context */
+    context?: {
+        entityName?: string;
+        fieldName?: string;
+        referencedEntity?: string;
+    };
+}
+export type ValidationErrorCode = 'UNDEFINED_ENTITY_REFERENCE' | 'UNDEFINED_THROUGH_ENTITY' | 'SELF_REFERENCE_INVALID' | 'DUPLICATE_FIELD_NAME' | 'INVALID_MODIFIER_FOR_TYPE' | 'DUPLICATE_PRIMARY_KEY' | 'DUPLICATE_ENUM_VALUE' | 'INVALID_RANGE' | 'CONFLICTING_MODIFIERS' | 'EMPTY_ENUM' | 'DUPLICATE_RELATIONSHIP' | 'INVALID_CASCADE_ACTION' | 'UNDEFINED_CRUD_ENTITY' | 'UNDEFINED_RETURN_TYPE_ENTITY' | 'INVALID_EFFECT_TYPE' | 'UNDEFINED_JOINED_ENTITY' | 'DUPLICATE_PARAMETER_NAME' | 'UNDEFINED_CAPABILITY_TARGET' | 'UNDEFINED_PAGE_REFERENCE' | 'UNDEFINED_API_REFERENCE' | 'DUPLICATE_ENTITY_NAME' | 'DUPLICATE_API_NAME';
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+export declare class KappaValidator {
+    private errors;
+    private warnings;
+    /** Set of all defined entity names */
+    private entityNames;
+    /** Set of all defined API names */
+    private apiNames;
+    /** Set of all defined page names */
+    private pageNames;
+    /** Set of all defined form names */
+    private formNames;
+    /** Set of all defined journey names */
+    private journeyNames;
+    /**
+     * Validate a Kappa specification AST
+     */
+    validate(spec: KappaSpec): ValidationResult;
+    private reset;
+    private collectDefinedNames;
+    private validateEntities;
+    private validateEntity;
+    private validateFieldType;
+    private validateModifiersForType;
+    private validateRelationship;
+    private validateCapability;
+    private validateAPIs;
+    private validateAPI;
+    private validateCRUD;
+    private validateAPIOperation;
+    private validateJourneys;
+    private validateJourney;
+    private validatePages;
+    private validatePage;
+    private validateForms;
+    private validateForm;
+    private addError;
+    private addWarning;
+}
+/**
+ * Validate a Kappa specification AST
+ */
+export declare function validateKappaSpec(spec: KappaSpec): ValidationResult;
+/**
+ * Format a validation error for display (simple format)
+ */
+export declare function formatValidationError(error: ValidationError): string;
+/**
+ * Options for rich error formatting
+ */
+export interface FormatOptions {
+    /** Original source code (required for code snippets) */
+    source?: string;
+    /** Use ANSI colors for terminal output */
+    colors?: boolean;
+    /** Number of context lines to show before/after error */
+    contextLines?: number;
+}
+/**
+ * Format a validation error with code snippet and visual indicators
+ */
+export declare function formatValidationErrorRich(error: ValidationError, options?: FormatOptions): string;
+/**
+ * Format all validation results for display
+ */
+export declare function formatValidationResults(result: ValidationResult, options?: FormatOptions): string;