causantic 0.2.0

package/dist/eval/metrics.js

@@ -0,0 +1,134 @@
+/**
+ * Evaluation metrics for embedding quality.
+ *
+ * - ROC AUC from labeled pairs scored by angular distance
+ * - Silhouette score for cluster quality
+ */
+import { angularDistance } from '../utils/angular-distance.js';
+/**
+ * Score all labeled pairs by angular distance between their embeddings.
+ */
+export function scorePairs(pairs, embeddings) {
+    return pairs
+        .filter((p) => embeddings.has(p.chunkIdA) && embeddings.has(p.chunkIdB))
+        .map((pair) => ({
+        pair,
+        distance: angularDistance(embeddings.get(pair.chunkIdA), embeddings.get(pair.chunkIdB)),
+    }));
+}
+/**
+ * Compute ROC AUC for binary classification.
+ *
+ * Positive class: 'related' or 'code-nl-pair' (should have low distance)
+ * Negative class: 'unrelated' (should have high distance)
+ *
+ * We use distance as the score, so lower distance = more likely positive.
+ * For AUC calculation we invert: score = 1 - distance.
+ */
+export function rocAuc(scoredPairs) {
+    // Split into positive (related) and negative (unrelated)
+    const positives = [];
+    const negatives = [];
+    for (const { pair, distance } of scoredPairs) {
+        const score = 1 - distance; // Higher score = more related
+        if (pair.label === 'unrelated') {
+            negatives.push(score);
+        }
+        else {
+            positives.push(score);
+        }
+    }
+    if (positives.length === 0 || negatives.length === 0)
+        return 0.5;
+    // Wilcoxon-Mann-Whitney statistic
+    let concordant = 0;
+    let ties = 0;
+    for (const pos of positives) {
+        for (const neg of negatives) {
+            if (pos > neg)
+                concordant++;
+            else if (pos === neg)
+                ties++;
+        }
+    }
+    return (concordant + 0.5 * ties) / (positives.length * negatives.length);
+}
+/**
+ * Compute silhouette score for a clustering.
+ *
+ * For each point:
+ *   a(i) = mean distance to other points in same cluster
+ *   b(i) = min over clusters C != own: mean distance to points in C
+ *   s(i) = (b(i) - a(i)) / max(a(i), b(i))
+ *
+ * Returns mean silhouette across all clustered points. Range [-1, 1].
+ */
+export function silhouetteScore(embeddings, labels) {
+    const n = embeddings.length;
+    if (n < 2)
+        return 0;
+    // Find unique clusters (exclude noise label -1)
+    const clusters = [...new Set(labels.filter((l) => l >= 0))];
+    if (clusters.length < 2)
+        return 0;
+    // Group indices by cluster
+    const clusterMembers = new Map();
+    for (const c of clusters) {
+        clusterMembers.set(c, labels.reduce((acc, l, i) => {
+            if (l === c)
+                acc.push(i);
+            return acc;
+        }, []));
+    }
+    let totalSilhouette = 0;
+    let clusteredCount = 0;
+    for (let i = 0; i < n; i++) {
+        if (labels[i] < 0)
+            continue; // Skip noise
+        clusteredCount++;
+        const ownCluster = labels[i];
+        const ownMembers = clusterMembers.get(ownCluster);
+        // a(i): mean distance to same-cluster points
+        let ai = 0;
+        if (ownMembers.length > 1) {
+            for (const j of ownMembers) {
+                if (j !== i)
+                    ai += angularDistance(embeddings[i], embeddings[j]);
+            }
+            ai /= ownMembers.length - 1;
+        }
+        // b(i): min mean distance to other clusters
+        let bi = Infinity;
+        for (const c of clusters) {
+            if (c === ownCluster)
+                continue;
+            const members = clusterMembers.get(c);
+            let meanDist = 0;
+            for (const j of members) {
+                meanDist += angularDistance(embeddings[i], embeddings[j]);
+            }
+            meanDist /= members.length;
+            if (meanDist < bi)
+                bi = meanDist;
+        }
+        const si = Math.max(ai, bi) === 0 ? 0 : (bi - ai) / Math.max(ai, bi);
+        totalSilhouette += si;
+    }
+    return clusteredCount > 0 ? totalSilhouette / clusteredCount : 0;
+}
+/**
+ * Compute the noise ratio (proportion of unclustered points).
+ */
+export function noiseRatio(labels) {
+    if (labels.length === 0)
+        return 0;
+    const noiseCount = labels.filter((l) => l < 0).length;
+    return noiseCount / labels.length;
+}
+/**
+ * Count the number of unique clusters (excluding noise).
+ */
+export function clusterCount(labels) {
+    return new Set(labels.filter((l) => l >= 0)).size;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/eval/metrics.js.map

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

package/dist/hooks/claudemd-generator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CLAUDE.md memory section generator.
+ * Auto-generates memory context for inclusion in project CLAUDE.md files.
+ *
+ * Features:
+ * - Retry logic for transient errors
+ * - Structured JSON logging
+ * - Execution metrics
+ * - Graceful degradation on failure
+ */
+import { type HookMetrics } from './hook-utils.js';
+import type { SessionStartOptions } from './session-start.js';
+/**
+ * Options for CLAUDE.md generation.
+ */
+export interface ClaudeMdOptions extends SessionStartOptions {
+    /** Path to CLAUDE.md file. Default: ./CLAUDE.md */
+    claudeMdPath?: string;
+    /** Create file if it doesn't exist. Default: false */
+    createIfMissing?: boolean;
+}
+/**
+ * Result of CLAUDE.md update.
+ */
+export interface ClaudeMdResult {
+    /** Whether the file was updated */
+    updated: boolean;
+    /** Whether the file was created */
+    created: boolean;
+    /** Path to the file */
+    path: string;
+    /** Memory section token count */
+    tokenCount: number;
+    /** Hook execution metrics */
+    metrics?: HookMetrics;
+    /** Whether this is a fallback result due to error */
+    degraded?: boolean;
+}
+/**
+ * Update CLAUDE.md with memory section.
+ * Inserts or updates the memory section between markers.
+ *
+ * @param projectPath - Project path (used for memory lookup)
+ * @param options - Options for generation
+ * @returns Update result
+ */
+export declare function updateClaudeMd(projectPath: string, options?: ClaudeMdOptions): Promise<ClaudeMdResult>;
+/**
+ * Remove memory section from CLAUDE.md.
+ *
+ * @param claudeMdPath - Path to CLAUDE.md file
+ * @returns Whether section was removed
+ */
+export declare function removeMemorySection(claudeMdPath: string): Promise<boolean>;
+/**
+ * Check if CLAUDE.md has memory section.
+ *
+ * @param claudeMdPath - Path to CLAUDE.md file
+ * @returns Whether memory section exists
+ */
+export declare function hasMemorySection(claudeMdPath: string): Promise<boolean>;
+//# sourceMappingURL=claudemd-generator.d.ts.map

package/dist/hooks/claudemd-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudemd-generator.d.ts","sourceRoot":"","sources":["../../src/hooks/claudemd-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQ9D;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA2ID;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAmCzB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAuChF;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW7E"}

package/dist/hooks/claudemd-generator.js

@@ -0,0 +1,220 @@
+/**
+ * CLAUDE.md memory section generator.
+ * Auto-generates memory context for inclusion in project CLAUDE.md files.
+ *
+ * Features:
+ * - Retry logic for transient errors
+ * - Structured JSON logging
+ * - Execution metrics
+ * - Graceful degradation on failure
+ */
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { generateMemorySection } from './session-start.js';
+import { executeHook, logHook, isTransientError, } from './hook-utils.js';
+/**
+ * Markers for memory section in CLAUDE.md.
+ */
+const MEMORY_START_MARKER = '<!-- MEMORY_START -->';
+const MEMORY_END_MARKER = '<!-- MEMORY_END -->';
+/**
+ * Internal handler without retry logic.
+ */
+async function internalUpdateClaudeMd(projectPath, options) {
+    const { claudeMdPath = join(projectPath, 'CLAUDE.md'), createIfMissing = false, ...sessionOptions } = options;
+    // Generate memory section
+    const memorySection = await generateMemorySection(projectPath, sessionOptions);
+    if (!memorySection) {
+        logHook({
+            level: 'debug',
+            hook: 'claudemd-generator',
+            event: 'no_memory_section',
+            details: { path: claudeMdPath },
+        });
+        return {
+            updated: false,
+            created: false,
+            path: claudeMdPath,
+            tokenCount: 0,
+        };
+    }
+    const wrappedSection = `${MEMORY_START_MARKER}\n${memorySection}\n${MEMORY_END_MARKER}`;
+    // Check if file exists
+    if (!existsSync(claudeMdPath)) {
+        if (createIfMissing) {
+            await writeFile(claudeMdPath, wrappedSection, 'utf-8');
+            logHook({
+                level: 'info',
+                hook: 'claudemd-generator',
+                event: 'file_created',
+                details: { path: claudeMdPath },
+            });
+            return {
+                updated: true,
+                created: true,
+                path: claudeMdPath,
+                tokenCount: memorySection.length / 4, // Rough estimate
+            };
+        }
+        logHook({
+            level: 'debug',
+            hook: 'claudemd-generator',
+            event: 'file_not_found',
+            details: { path: claudeMdPath, createIfMissing },
+        });
+        return {
+            updated: false,
+            created: false,
+            path: claudeMdPath,
+            tokenCount: 0,
+        };
+    }
+    // Read existing file
+    const existing = await readFile(claudeMdPath, 'utf-8');
+    // Check for existing memory section
+    const startIdx = existing.indexOf(MEMORY_START_MARKER);
+    const endIdx = existing.indexOf(MEMORY_END_MARKER);
+    let newContent;
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing section
+        newContent =
+            existing.slice(0, startIdx) +
+                wrappedSection +
+                existing.slice(endIdx + MEMORY_END_MARKER.length);
+        logHook({
+            level: 'debug',
+            hook: 'claudemd-generator',
+            event: 'section_replaced',
+            details: { path: claudeMdPath },
+        });
+    }
+    else {
+        // Append to end
+        newContent = existing.trimEnd() + '\n\n' + wrappedSection + '\n';
+        logHook({
+            level: 'debug',
+            hook: 'claudemd-generator',
+            event: 'section_appended',
+            details: { path: claudeMdPath },
+        });
+    }
+    // Only write if content changed
+    if (newContent !== existing) {
+        await writeFile(claudeMdPath, newContent, 'utf-8');
+        logHook({
+            level: 'info',
+            hook: 'claudemd-generator',
+            event: 'file_updated',
+            details: { path: claudeMdPath },
+        });
+        return {
+            updated: true,
+            created: false,
+            path: claudeMdPath,
+            tokenCount: memorySection.length / 4,
+        };
+    }
+    logHook({
+        level: 'debug',
+        hook: 'claudemd-generator',
+        event: 'no_changes',
+        details: { path: claudeMdPath },
+    });
+    return {
+        updated: false,
+        created: false,
+        path: claudeMdPath,
+        tokenCount: memorySection.length / 4,
+    };
+}
+/**
+ * Update CLAUDE.md with memory section.
+ * Inserts or updates the memory section between markers.
+ *
+ * @param projectPath - Project path (used for memory lookup)
+ * @param options - Options for generation
+ * @returns Update result
+ */
+export async function updateClaudeMd(projectPath, options = {}) {
+    const { enableRetry = true, maxRetries = 3, gracefulDegradation = true, } = options;
+    const claudeMdPath = options.claudeMdPath ?? join(projectPath, 'CLAUDE.md');
+    const fallbackResult = {
+        updated: false,
+        created: false,
+        path: claudeMdPath,
+        tokenCount: 0,
+        degraded: true,
+    };
+    const { result, metrics } = await executeHook('claudemd-generator', () => internalUpdateClaudeMd(projectPath, options), {
+        retry: enableRetry
+            ? {
+                maxRetries,
+                retryOn: isTransientError,
+            }
+            : undefined,
+        fallback: gracefulDegradation ? fallbackResult : undefined,
+    });
+    return {
+        ...result,
+        metrics,
+    };
+}
+/**
+ * Remove memory section from CLAUDE.md.
+ *
+ * @param claudeMdPath - Path to CLAUDE.md file
+ * @returns Whether section was removed
+ */
+export async function removeMemorySection(claudeMdPath) {
+    if (!existsSync(claudeMdPath)) {
+        return false;
+    }
+    try {
+        const existing = await readFile(claudeMdPath, 'utf-8');
+        const startIdx = existing.indexOf(MEMORY_START_MARKER);
+        const endIdx = existing.indexOf(MEMORY_END_MARKER);
+        if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+            return false;
+        }
+        const newContent = existing.slice(0, startIdx).trimEnd() +
+            existing.slice(endIdx + MEMORY_END_MARKER.length);
+        await writeFile(claudeMdPath, newContent.trimEnd() + '\n', 'utf-8');
+        logHook({
+            level: 'info',
+            hook: 'claudemd-generator',
+            event: 'section_removed',
+            details: { path: claudeMdPath },
+        });
+        return true;
+    }
+    catch (error) {
+        logHook({
+            level: 'error',
+            hook: 'claudemd-generator',
+            event: 'remove_failed',
+            error: error instanceof Error ? error.message : String(error),
+            details: { path: claudeMdPath },
+        });
+        return false;
+    }
+}
+/**
+ * Check if CLAUDE.md has memory section.
+ *
+ * @param claudeMdPath - Path to CLAUDE.md file
+ * @returns Whether memory section exists
+ */
+export async function hasMemorySection(claudeMdPath) {
+    if (!existsSync(claudeMdPath)) {
+        return false;
+    }
+    try {
+        const content = await readFile(claudeMdPath, 'utf-8');
+        return content.includes(MEMORY_START_MARKER) && content.includes(MEMORY_END_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=claudemd-generator.js.map

package/dist/hooks/claudemd-generator.js.map

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

package/dist/hooks/hook-utils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Hook utilities for error recovery, logging, and metrics.
+ *
+ * Provides:
+ * - Structured JSON logging
+ * - Retry logic with exponential backoff
+ * - Hook execution metrics
+ * - Graceful degradation on failure
+ */
+/** Log entry structure */
+export interface HookLogEntry {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    hook: string;
+    event: string;
+    durationMs?: number;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/** Hook execution metrics */
+export interface HookMetrics {
+    hookName: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    success?: boolean;
+    retryCount: number;
+    error?: string;
+}
+/** Retry options */
+export interface RetryOptions {
+    /** Maximum number of retries. Default: 3 */
+    maxRetries?: number;
+    /** Initial delay in ms. Default: 1000 */
+    initialDelayMs?: number;
+    /** Maximum delay in ms. Default: 10000 */
+    maxDelayMs?: number;
+    /** Backoff multiplier. Default: 2 */
+    backoffFactor?: number;
+    /** Errors to retry on. Default: all errors */
+    retryOn?: (error: Error) => boolean;
+}
+/** Hook configuration */
+export interface HookConfig {
+    /** Enable structured JSON logging. Default: env CAUSANTIC_HOOK_LOGGING === 'true' */
+    enableLogging?: boolean;
+    /** Log level: 'debug' | 'info' | 'warn' | 'error'. Default: 'info' */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Configure hook utilities.
+ */
+export declare function configureHooks(config: Partial<HookConfig>): void;
+/**
+ * Log a structured message.
+ */
+export declare function logHook(entry: Omit<HookLogEntry, 'timestamp'>): void;
+/**
+ * Execute a function with retry logic.
+ */
+export declare function withRetry<T>(hookName: string, fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Create a metrics tracker for a hook execution.
+ */
+export declare function createMetrics(hookName: string): HookMetrics;
+/**
+ * Complete metrics tracking.
+ */
+export declare function completeMetrics(metrics: HookMetrics, success: boolean, error?: Error): HookMetrics;
+/**
+ * Wrap a hook function with logging, metrics, and error handling.
+ */
+export declare function executeHook<T>(hookName: string, fn: () => Promise<T>, options?: {
+    retry?: RetryOptions;
+    fallback?: T;
+}): Promise<{
+    result: T;
+    metrics: HookMetrics;
+}>;
+/**
+ * Check if an error is transient (worth retrying).
+ */
+export declare function isTransientError(error: Error): boolean;
+//# sourceMappingURL=hook-utils.d.ts.map

package/dist/hooks/hook-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-utils.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oBAAoB;AACpB,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CACrC;AAED,yBAAyB;AACzB,MAAM,WAAW,UAAU;IACzB,qFAAqF;IACrF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAQD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG,IAAI,CAgBpE;AAsBD;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAgDZ;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAM3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,OAAO,EAChB,KAAK,CAAC,EAAE,KAAK,GACZ,WAAW,CAQb;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,CAAC;CACT,GACL,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,CAoD9C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CA6BtD"}