@nathanvale/chatline 0.0.1 → 0.0.2-next.1

package/dist/utils/delta-detection.js

@@ -1,199 +0,0 @@
-/**
- * Delta Detection Module (INCREMENTAL--T02)
- *
- * Identifies new messages for enrichment by comparing current normalized state
- * with previous enrichment state.
- *
- * Implements:
- * - AC01: Load previous state from .imessage-state.json
- * - AC02: Diff normalized messages against enrichedGuids
- * - AC03: Return only new GUIDs for enrichment
- * - AC04: Handle state file missing (treat as first run)
- * - AC05: Log delta summary: Found X new messages to enrich
- *
- * Architecture:
- * - DeltaResult: Complete delta detection output
- * - detectDelta: Main entry point for delta detection
- * - extractGuidsFromMessages: Convert messages to GUID set
- * - computeDelta: Core diff logic
- * - logDeltaSummary: Human-readable delta report
- */
-import { humanInfo } from '#utils/human';
-import { createLogger } from '#utils/logger';
-import { detectNewMessages, loadIncrementalState } from './incremental-state';
-// ============================================================================
-// AC01 + AC04: Load previous state safely
-// ============================================================================
-/**
- * AC01 + AC04: Load incremental state from disk
- *
- * Handles missing state file gracefully:
- * - Returns null if file doesn't exist (first run)
- * - Returns null if JSON is corrupted
- * - Returns parsed state if valid
- *
- * @param stateFilePath - Path to .imessage-state.json
- * @returns IncrementalState if found and valid, null if missing or corrupted
- */
-async function loadPreviousState(stateFilePath) {
-    return loadIncrementalState(stateFilePath);
-}
-// ============================================================================
-// AC02 + AC03: Extract GUIDs and compute delta
-// ============================================================================
-/**
- * AC02 + AC03: Extract message GUIDs from normalized messages
- *
- * Converts Message[] to Set<guid> for efficient delta computation
- *
- * @param messages - Normalized messages to process
- * @returns Set of unique message GUIDs
- */
-export function extractGuidsFromMessages(messages) {
-    const guids = new Set();
-    for (const msg of messages) {
-        guids.add(msg.guid);
-    }
-    return guids;
-}
-/**
- * AC02 + AC03: Compute delta between current and previous state
- *
- * Performance: O(n + m) where:
- * - n = number of current messages
- * - m = number of previously enriched messages
- *
- * Uses Set-based deduplication for O(1) lookup
- *
- * @param currentGuids - Set of message GUIDs from normalized state
- * @param previousState - Prior state with enriched GUIDs (null if first run)
- * @returns New GUIDs not in previous state
- */
-function computeDelta(currentGuids, previousState) {
-    if (!previousState) {
-        // First run: all current messages are "new"
-        return Array.from(currentGuids);
-    }
-    // Use existing delta detection from incremental-state module
-    return detectNewMessages(currentGuids, previousState);
-}
-// ============================================================================
-// AC05: Delta Summary Logging
-// ============================================================================
-/**
- * AC05: Log human-readable delta summary
- *
- * Outputs lines like:
- * - "Found 142 new messages to enrich"
- * - "Previously enriched: 358"
- * - "This is your first enrichment run"
- * - "Delta: 28.3% of 500 total messages"
- *
- * @param result - DeltaResult to summarize
- */
-export function logDeltaSummary(result) {
-    const logger = createLogger('utils:delta-detection');
-    const newCount = result.newCount;
-    const totalCount = result.totalMessages;
-    const previousCount = result.previousEnrichedCount;
-    // Log delta summary (AC05)
-    if (result.isFirstRun) {
-        // Structured log (machine consumption)
-        logger.info('First enrichment run', { totalMessages: totalCount });
-        // Human-friendly console output retained for tests & CLI UX
-        // Format expected by tests: contains both 'First enrichment run' and '<N> messages'
-        humanInfo(`First enrichment run: ${totalCount} messages`);
-    }
-    else {
-        const percentNew = totalCount > 0 ? (newCount / totalCount) * 100 : 0;
-        // Structured log
-        logger.info('Delta detected', {
-            newMessages: newCount,
-            percentNew,
-            totalMessages: totalCount,
-            previouslyEnriched: previousCount,
-        });
-        // Human-readable lines expected by tests
-        // Includes phrases: 'Delta detected', '<X> new messages', '<Y.Y%>' and 'Previously enriched: <N>'
-        humanInfo(`Delta detected: ${newCount} new messages (${percentNew.toFixed(1)}%) of ${totalCount} total messages`);
-        humanInfo(`Previously enriched: ${previousCount}`);
-    }
-}
-// ============================================================================
-// AC01-AC05: Main entry point for delta detection
-// ============================================================================
-/**
- * AC01-AC05: Perform complete delta detection
- *
- * Workflow:
- * 1. AC04: Load previous state (null if missing)
- * 2. AC02: Extract current message GUIDs
- * 3. AC03: Compute delta (new GUIDs only)
- * 4. AC05: Log summary
- *
- * Returns DeltaResult with:
- * - newGuids to enrich
- * - metadata for progress tracking
- * - state to update after enrichment
- *
- * @param messages - Normalized messages from normalize-link stage
- * @param stateFilePath - Path to .imessage-state.json
- * @returns DeltaResult with new GUIDs and metadata
- * @throws Error if state file can't be read (permission denied, etc.)
- */
-export async function detectDelta(messages, stateFilePath) {
-    // AC01 + AC04: Load previous state (null if missing)
-    const previousState = await loadPreviousState(stateFilePath);
-    const isFirstRun = previousState === null;
-    // AC02 + AC03: Extract current GUIDs and compute delta
-    const currentGuids = extractGuidsFromMessages(messages);
-    const newGuids = computeDelta(currentGuids, previousState);
-    // Build result
-    const result = {
-        newGuids,
-        totalMessages: messages.length,
-        previousEnrichedCount: previousState?.enrichedGuids.length ?? 0,
-        newCount: newGuids.length,
-        isFirstRun,
-        state: previousState ?? {
-            version: '1.0',
-            lastEnrichedAt: new Date().toISOString(),
-            totalMessages: messages.length,
-            enrichedGuids: [],
-            pipelineConfig: {
-                configHash: '',
-            },
-            enrichmentStats: null,
-        },
-    };
-    // AC05: Log summary
-    logDeltaSummary(result);
-    return result;
-}
-// ============================================================================
-// Utility: Get delta statistics for progress reporting
-// ============================================================================
-/**
- * Calculate delta statistics for progress monitoring
- *
- * Useful for:
- * - Progress bars (show percentage to enrich)
- * - ETA calculation
- * - Summary reports
- *
- * @param result - DeltaResult to analyze
- * @returns Statistics object with counts and percentages
- */
-export function getDeltaStats(result) {
-    const total = result.totalMessages;
-    const newCount = result.newCount;
-    const previousCount = result.previousEnrichedCount;
-    return {
-        total,
-        new: newCount,
-        previous: previousCount,
-        percentNew: total > 0 ? (newCount / total) * 100 : 0,
-        percentPrevious: total > 0 ? (previousCount / total) * 100 : 0,
-    };
-}
-//# sourceMappingURL=delta-detection.js.map

package/dist/utils/delta-detection.js.map

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

package/dist/utils/enrichment-merge.d.ts

@@ -1,135 +0,0 @@
-/**
- * Enrichment Merge Module (INCREMENTAL--T03)
- *
- * Implements merge strategy for incremental enrichment results into existing
- * enriched JSON, preserving prior work and handling new enrichments.
- *
- * Implements:
- * - AC01: Load existing enriched.json if exists
- * - AC02: Merge new enrichments by GUID (new messages + updates)
- * - AC03: Preserve existing enrichments (no overwrites unless --force-refresh)
- * - AC04: Update statistics in state file
- * - AC05: Backup previous enriched.json as enriched.json.backup
- *
- * Architecture:
- * - MergeResult: Complete merge operation output
- * - MergeOptions: Configuration for merge behavior
- * - loadExistingEnriched: Load prior enriched.json safely
- * - mergeEnrichments: Core merge logic with preservation
- * - backupEnrichedJson: Atomic backup creation
- * - updateMergeStatistics: Statistics calculation
- */
-import type { ExportEnvelope, Message } from '#schema/message';
-/**
- * Options for merge behavior
- */
-export type MergeOptions = {
-    /** Force refresh overwrites existing enrichments (default: false) */
-    forceRefresh?: boolean;
-};
-/**
- * Statistics from merge operation
- */
-export type MergeStatistics = {
-    /** Number of messages merged (existing GUIDs updated) */
-    mergedCount: number;
-    /** Number of messages added (new GUIDs) */
-    addedCount: number;
-    /** Number of messages with preserved enrichments */
-    preservedCount: number;
-    /** Total messages in result */
-    totalMessages: number;
-    /** Percentage of messages that were merged */
-    mergedPercentage?: number;
-    /** Percentage of messages that were added */
-    addedPercentage?: number;
-};
-/**
- * Result of merge operation
- */
-export type MergeResult = {
-    /** Merged messages with enrichments preserved/updated */
-    messages: Message[];
-    /** Statistics about the merge operation */
-    statistics: MergeStatistics;
-    /** Count of messages merged */
-    mergedCount: number;
-    /** Count of messages added */
-    addedCount: number;
-    /** Count of messages with preserved enrichments */
-    preservedCount: number;
-};
-/**
- * AC01: Load existing enriched JSON safely
- *
- * Handles:
- * - File doesn't exist (returns null)
- * - JSON is corrupted (returns null)
- * - Schema version mismatch (returns null or handles gracefully)
- * - Preserves all enrichment data
- *
- * @param filePath - Path to existing enriched.json
- * @returns ExportEnvelope if valid, null if missing or corrupted
- */
-export declare function loadExistingEnriched(filePath: string): Promise<ExportEnvelope | null>;
-/**
- * AC02 + AC03: Merge new enrichments with existing messages
- *
- * Strategy:
- * 1. Build index of existing messages by GUID
- * 2. For each new message:
- *    - If GUID exists: merge enrichments (preserve existing unless --force-refresh)
- *    - If GUID is new: add message
- * 3. Preserve enrichment order and structure
- *
- * @param existingMessages - Messages from prior enriched.json
- * @param newMessages - New/updated messages from enrichment
- * @param options - Merge options (forceRefresh, etc.)
- * @returns MergeResult with merged messages and statistics
- */
-export declare function mergeEnrichments(existingMessages: Message[], newMessages: Message[], options?: MergeOptions): MergeResult;
-/**
- * AC04: Calculate and update merge statistics
- *
- * Computes merge percentages and summary information
- *
- * @param stats - Raw statistics
- * @returns Updated statistics with percentages
- */
-export declare function updateMergeStatistics(stats: MergeStatistics): MergeStatistics;
-/**
- * AC05: Create atomic backup of existing enriched.json
- *
- * Pattern:
- * 1. Read existing file
- * 2. Write to enriched.json.backup (overwrite if exists)
- * 3. Ensures no data loss on merge
- *
- * @param filePath - Path to enriched.json to backup
- * @throws Error if source file can't be read
- */
-export declare function backupEnrichedJson(filePath: string): Promise<void>;
-/**
- * Create a new MergeResult with given parameters
- *
- * @param messages - Merged messages
- * @param options - Statistics options
- * @returns Complete MergeResult
- */
-export declare function createEnrichmentMergeResult(messages: Message[], options: {
-    mergedCount: number;
-    addedCount: number;
-    preservedCount: number;
-}): MergeResult;
-/**
- * AC05: Log human-readable merge summary
- *
- * Outputs lines like:
- * - "Merged 50 existing messages with new enrichments"
- * - "Added 10 new messages to enriched.json"
- * - "Preserved 60 enrichments from prior run"
- *
- * @param result - MergeResult to summarize
- */
-export declare function logMergeSummary(result: MergeResult): void;
-//# sourceMappingURL=enrichment-merge.d.ts.map

package/dist/utils/enrichment-merge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"enrichment-merge.d.ts","sourceRoot":"","sources":["../../src/utils/enrichment-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAU9D;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,qEAAqE;IACrE,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAA;IAEnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAElB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAA;IAEtB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAA;IAErB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,EAAE,CAAA;IAEnB,2CAA2C;IAC3C,UAAU,EAAE,eAAe,CAAA;IAE3B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAA;IAEnB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAA;IAElB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAA;CACtB,CAAA;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACzC,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAmBhC;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC/B,gBAAgB,EAAE,OAAO,EAAE,EAC3B,WAAW,EAAE,OAAO,EAAE,EACtB,OAAO,GAAE,YAAiB,GACxB,WAAW,CAoEb;AAqED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAQ7E;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxE;AAMD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAC1C,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE;IACR,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;CACtB,GACC,WAAW,CAiBb;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAqBzD"}

package/dist/utils/enrichment-merge.js

@@ -1,280 +0,0 @@
-/**
- * Enrichment Merge Module (INCREMENTAL--T03)
- *
- * Implements merge strategy for incremental enrichment results into existing
- * enriched JSON, preserving prior work and handling new enrichments.
- *
- * Implements:
- * - AC01: Load existing enriched.json if exists
- * - AC02: Merge new enrichments by GUID (new messages + updates)
- * - AC03: Preserve existing enrichments (no overwrites unless --force-refresh)
- * - AC04: Update statistics in state file
- * - AC05: Backup previous enriched.json as enriched.json.backup
- *
- * Architecture:
- * - MergeResult: Complete merge operation output
- * - MergeOptions: Configuration for merge behavior
- * - loadExistingEnriched: Load prior enriched.json safely
- * - mergeEnrichments: Core merge logic with preservation
- * - backupEnrichedJson: Atomic backup creation
- * - updateMergeStatistics: Statistics calculation
- */
-import { promises as fs } from 'node:fs';
-import { createLogger } from '#utils/logger';
-// ============================================================================
-// AC01: Load existing enriched.json
-// ============================================================================
-/**
- * AC01: Load existing enriched JSON safely
- *
- * Handles:
- * - File doesn't exist (returns null)
- * - JSON is corrupted (returns null)
- * - Schema version mismatch (returns null or handles gracefully)
- * - Preserves all enrichment data
- *
- * @param filePath - Path to existing enriched.json
- * @returns ExportEnvelope if valid, null if missing or corrupted
- */
-export async function loadExistingEnriched(filePath) {
-    try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        const parsed = JSON.parse(content);
-        // Validate basic structure
-        if (!parsed.messages || !Array.isArray(parsed.messages)) {
-            return null;
-        }
-        return parsed;
-    }
-    catch (error) {
-        // File doesn't exist or is corrupted
-        if (error instanceof Error && error.message.includes('ENOENT')) {
-            return null;
-        }
-        // JSON parse error or other read error
-        return null;
-    }
-}
-// ============================================================================
-// AC02 + AC03: Merge enrichments by GUID
-// ============================================================================
-/**
- * AC02 + AC03: Merge new enrichments with existing messages
- *
- * Strategy:
- * 1. Build index of existing messages by GUID
- * 2. For each new message:
- *    - If GUID exists: merge enrichments (preserve existing unless --force-refresh)
- *    - If GUID is new: add message
- * 3. Preserve enrichment order and structure
- *
- * @param existingMessages - Messages from prior enriched.json
- * @param newMessages - New/updated messages from enrichment
- * @param options - Merge options (forceRefresh, etc.)
- * @returns MergeResult with merged messages and statistics
- */
-export function mergeEnrichments(existingMessages, newMessages, options = {}) {
-    // Build index of existing messages by GUID
-    const existingByGuid = new Map();
-    for (const msg of existingMessages) {
-        existingByGuid.set(msg.guid, msg);
-    }
-    // Track merge statistics
-    let mergedCount = 0;
-    let addedCount = 0;
-    let preservedCount = 0;
-    // Track GUIDs we've processed to avoid duplicates
-    const processedGuids = new Set();
-    // Result messages with merged enrichments
-    const resultMessages = [];
-    // Process new messages
-    for (const newMsg of newMessages) {
-        const existing = existingByGuid.get(newMsg.guid);
-        if (existing) {
-            // Message exists: merge enrichments
-            if (!processedGuids.has(newMsg.guid)) {
-                const merged = mergeMessageEnrichments(existing, newMsg, options);
-                resultMessages.push(merged);
-                mergedCount++;
-                // Count preserved enrichments
-                if (merged.messageKind === 'media' &&
-                    merged.media?.enrichment &&
-                    merged.media.enrichment.length > 0) {
-                    preservedCount++;
-                }
-                processedGuids.add(newMsg.guid);
-            }
-        }
-        else {
-            // New message: add to result
-            if (!processedGuids.has(newMsg.guid)) {
-                resultMessages.push(newMsg);
-                addedCount++;
-                processedGuids.add(newMsg.guid);
-            }
-        }
-    }
-    const totalMessages = resultMessages.length;
-    return {
-        messages: resultMessages,
-        statistics: {
-            mergedCount,
-            addedCount,
-            preservedCount,
-            totalMessages,
-            mergedPercentage: totalMessages > 0 ? (mergedCount / totalMessages) * 100 : 0,
-            addedPercentage: totalMessages > 0 ? (addedCount / totalMessages) * 100 : 0,
-        },
-        mergedCount,
-        addedCount,
-        preservedCount,
-    };
-}
-/**
- * AC02 + AC03: Merge enrichments for a single message
- *
- * Preservation logic:
- * - If forceRefresh: use new enrichments
- * - Otherwise:
- *   - Preserve existing enrichments by kind
- *   - Append new enrichments for different kinds
- *   - Skip enrichments for kinds that already exist (unless force)
- *
- * @param existing - Existing message with enrichments
- * @param newMsg - New message with enrichments
- * @param options - Merge options
- * @returns Merged message with preserved enrichments
- */
-function mergeMessageEnrichments(existing, newMsg, options) {
-    // If not media message, just return existing (no enrichment to merge)
-    if (existing.messageKind !== 'media' || !existing.media) {
-        return existing;
-    }
-    // If no new enrichments, keep existing as-is
-    if (!newMsg.media?.enrichment || newMsg.media.enrichment.length === 0) {
-        return existing;
-    }
-    // If forceRefresh, use all new enrichments
-    if (options.forceRefresh) {
-        return {
-            ...existing,
-            media: {
-                ...existing.media,
-                enrichment: newMsg.media.enrichment,
-            },
-        };
-    }
-    // Otherwise: preserve existing, append new for different kinds
-    const existingEnrichment = existing.media.enrichment ?? [];
-    const newEnrichment = newMsg.media.enrichment ?? [];
-    // Build set of existing enrichment kinds
-    const existingKinds = new Set(existingEnrichment.map((e) => e.kind));
-    // Only add new enrichments for kinds not already present
-    const mergedEnrichment = [
-        ...existingEnrichment,
-        ...newEnrichment.filter((e) => !existingKinds.has(e.kind)),
-    ];
-    return {
-        ...existing,
-        media: {
-            ...existing.media,
-            enrichment: mergedEnrichment,
-        },
-    };
-}
-// ============================================================================
-// AC04: Update merge statistics
-// ============================================================================
-/**
- * AC04: Calculate and update merge statistics
- *
- * Computes merge percentages and summary information
- *
- * @param stats - Raw statistics
- * @returns Updated statistics with percentages
- */
-export function updateMergeStatistics(stats) {
-    const total = stats.totalMessages;
-    return {
-        ...stats,
-        mergedPercentage: total > 0 ? (stats.mergedCount / total) * 100 : 0,
-        addedPercentage: total > 0 ? (stats.addedCount / total) * 100 : 0,
-    };
-}
-// ============================================================================
-// AC05: Backup existing enriched.json
-// ============================================================================
-/**
- * AC05: Create atomic backup of existing enriched.json
- *
- * Pattern:
- * 1. Read existing file
- * 2. Write to enriched.json.backup (overwrite if exists)
- * 3. Ensures no data loss on merge
- *
- * @param filePath - Path to enriched.json to backup
- * @throws Error if source file can't be read
- */
-export async function backupEnrichedJson(filePath) {
-    const backupPath = `${filePath}.backup`;
-    const content = await fs.readFile(filePath, 'utf-8');
-    await fs.writeFile(backupPath, content, 'utf-8');
-}
-// ============================================================================
-// Helper: Create enrichment merge result
-// ============================================================================
-/**
- * Create a new MergeResult with given parameters
- *
- * @param messages - Merged messages
- * @param options - Statistics options
- * @returns Complete MergeResult
- */
-export function createEnrichmentMergeResult(messages, options) {
-    return {
-        messages,
-        statistics: {
-            mergedCount: options.mergedCount,
-            addedCount: options.addedCount,
-            preservedCount: options.preservedCount,
-            totalMessages: messages.length,
-            mergedPercentage: messages.length > 0 ? (options.mergedCount / messages.length) * 100 : 0,
-            addedPercentage: messages.length > 0 ? (options.addedCount / messages.length) * 100 : 0,
-        },
-        mergedCount: options.mergedCount,
-        addedCount: options.addedCount,
-        preservedCount: options.preservedCount,
-    };
-}
-// ============================================================================
-// Helper: Log merge summary
-// ============================================================================
-/**
- * AC05: Log human-readable merge summary
- *
- * Outputs lines like:
- * - "Merged 50 existing messages with new enrichments"
- * - "Added 10 new messages to enriched.json"
- * - "Preserved 60 enrichments from prior run"
- *
- * @param result - MergeResult to summarize
- */
-export function logMergeSummary(result) {
-    const { mergedCount, addedCount, preservedCount } = result;
-    const logger = createLogger('utils:enrichment-merge');
-    if (mergedCount > 0) {
-        logger.info('Merged existing messages with new enrichments', {
-            mergedCount,
-        });
-    }
-    if (addedCount > 0) {
-        logger.info('Added new messages to enriched.json', { addedCount });
-    }
-    if (preservedCount > 0) {
-        logger.info('Preserved enrichments from prior run', { preservedCount });
-    }
-    if (mergedCount === 0 && addedCount === 0) {
-        logger.info('No new enrichments to merge');
-    }
-}
-//# sourceMappingURL=enrichment-merge.js.map

package/dist/utils/enrichment-merge.js.map

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

package/dist/utils/human.d.ts

@@ -1,15 +0,0 @@
-/**
- * Human Output Helper
- *
- * Centralizes human-facing console output so we can globally toggle it
- * (e.g. suppressed when --json or LOG_FORMAT=json-only is active).
- * Tests that spy on console.* remain compatible.
- */
-export type HumanLoggerOptions = {
-    enabled?: boolean;
-};
-export declare function setHumanLoggingEnabled(enabled: boolean): void;
-export declare function humanInfo(...args: Array<unknown>): void;
-export declare function humanWarn(...args: Array<unknown>): void;
-export declare function humanError(...args: Array<unknown>): void;
-//# sourceMappingURL=human.d.ts.map

package/dist/utils/human.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"human.d.ts","sourceRoot":"","sources":["../../src/utils/human.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAID,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE7D;AAeD,wBAAgB,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAEvD;AAED,wBAAgB,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAEvD;AAED,wBAAgB,UAAU,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAExD"}