@lumenflow/core 3.2.0 → 3.2.1

package/dist/test-baseline.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Test Baseline - Test Ratchet Pattern (WU-1253)
+ *
+ * Implements a "ratchet" pattern for test failures:
+ * - Track known failures in a baseline file (.lumenflow/test-baseline.json)
+ * - Block NEW failures (not in baseline)
+ * - Allow pre-existing failures with warning
+ * - Auto-update baseline when tests are fixed (ratchet forward)
+ *
+ * This enables agents to work on WUs without being blocked by unrelated
+ * test failures, while still preventing introduction of NEW failures.
+ *
+ * @see https://lumenflow.dev/reference/test-ratchet/
+ */
+import { z } from 'zod';
+/** Default path for the test baseline file (WU-1430: Use centralized constant) */
+export declare const DEFAULT_BASELINE_PATH: string;
+/** Environment variable to override baseline path */
+export declare const BASELINE_PATH_ENV = "LUMENFLOW_TEST_BASELINE";
+/** Current schema version */
+export declare const BASELINE_VERSION = 1;
+/**
+ * Schema for a known test failure entry
+ */
+export declare const KnownFailureSchema: z.ZodObject<{
+    test_name: z.ZodString;
+    file_path: z.ZodString;
+    failure_reason: z.ZodString;
+    added_at: z.ZodString;
+    added_by_wu: z.ZodString;
+    expected_fix_wu: z.ZodOptional<z.ZodString>;
+    skip_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type KnownFailure = z.infer<typeof KnownFailureSchema>;
+/**
+ * Schema for baseline statistics
+ */
+export declare const BaselineStatsSchema: z.ZodObject<{
+    total_known_failures: z.ZodNumber;
+    last_ratchet_forward: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BaselineStats = z.infer<typeof BaselineStatsSchema>;
+/**
+ * Schema for the complete test baseline file
+ */
+export declare const TestBaselineSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    updated_at: z.ZodString;
+    updated_by: z.ZodString;
+    known_failures: z.ZodArray<z.ZodObject<{
+        test_name: z.ZodString;
+        file_path: z.ZodString;
+        failure_reason: z.ZodString;
+        added_at: z.ZodString;
+        added_by_wu: z.ZodString;
+        expected_fix_wu: z.ZodOptional<z.ZodString>;
+        skip_reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    stats: z.ZodObject<{
+        total_known_failures: z.ZodNumber;
+        last_ratchet_forward: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TestBaseline = z.infer<typeof TestBaselineSchema>;
+/**
+ * Result from a test run (input to comparison)
+ */
+export interface TestResult {
+    test_name: string;
+    file_path: string;
+    passed: boolean;
+    error_message?: string;
+}
+/**
+ * Result of comparing test results against baseline
+ */
+export interface BaselineComparison {
+    /** Tests that failed but are NOT in baseline (blocks gate) */
+    newFailures: TestResult[];
+    /** Tests that failed and ARE in baseline (warning only) */
+    preExistingFailures: KnownFailure[];
+    /** Tests that were in baseline but now pass (ratchet forward candidates) */
+    fixedTests: KnownFailure[];
+    /** Should this block the gate? (true if newFailures > 0) */
+    shouldBlock: boolean;
+    /** Are there warnings to show? (true if preExistingFailures > 0) */
+    hasWarnings: boolean;
+    /** Should baseline be updated? (true if fixedTests > 0) */
+    shouldRatchetForward: boolean;
+}
+/**
+ * Parse result type
+ */
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Options for updating the baseline
+ */
+export interface UpdateBaselineOptions {
+    /** Tests that were fixed (to remove from baseline) */
+    fixedTests?: string[];
+    /** New known failures to add to baseline */
+    newKnownFailures?: Array<{
+        test_name: string;
+        file_path: string;
+        failure_reason: string;
+        expected_fix_wu?: string;
+    }>;
+}
+/**
+ * Parse a test baseline JSON string
+ *
+ * @param json - JSON string content of baseline file
+ * @returns Parse result with baseline data or error
+ */
+export declare function parseTestBaseline(json: string): ParseResult<TestBaseline>;
+/**
+ * Create a new test baseline
+ *
+ * @param wuId - WU creating the baseline
+ * @param initialFailures - Optional initial failures to add
+ * @returns New test baseline
+ */
+export declare function createTestBaseline(wuId: string, initialFailures?: Array<{
+    test_name: string;
+    file_path: string;
+    failure_reason: string;
+    expected_fix_wu?: string;
+}>): TestBaseline;
+/**
+ * Compare current test results against the baseline
+ *
+ * This is the core ratchet logic:
+ * - NEW failures (not in baseline) block the gate
+ * - Pre-existing failures (in baseline) show warning
+ * - Fixed tests (in baseline but now passing) trigger ratchet forward
+ *
+ * @param baseline - The test baseline
+ * @param currentFailures - Current test failures from test run
+ * @returns Comparison result
+ */
+export declare function compareTestResults(baseline: TestBaseline, currentFailures: TestResult[]): BaselineComparison;
+/**
+ * Update the baseline (ratchet forward or add new known failures)
+ *
+ * @param baseline - Current baseline
+ * @param wuId - WU making the update
+ * @param options - Update options
+ * @returns Updated baseline (immutable)
+ */
+export declare function updateBaseline(baseline: TestBaseline, wuId: string, options: UpdateBaselineOptions): TestBaseline;
+/**
+ * Format a warning message for pre-existing failures
+ *
+ * @param preExisting - Pre-existing failures from baseline
+ * @returns Formatted warning string
+ */
+export declare function formatBaselineWarning(preExisting: KnownFailure[]): string;
+/**
+ * Format an error message for new failures
+ *
+ * @param newFailures - New test failures
+ * @returns Formatted error string
+ */
+export declare function formatNewFailureError(newFailures: TestResult[]): string;
+/**
+ * Get the path to the test baseline file
+ *
+ * @returns Baseline file path
+ */
+export declare function getBaselineFilePath(): string;
+//# sourceMappingURL=test-baseline.d.ts.map

package/dist/test-baseline.d.ts.map

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

package/dist/test-baseline.js

@@ -0,0 +1,286 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Test Baseline - Test Ratchet Pattern (WU-1253)
+ *
+ * Implements a "ratchet" pattern for test failures:
+ * - Track known failures in a baseline file (.lumenflow/test-baseline.json)
+ * - Block NEW failures (not in baseline)
+ * - Allow pre-existing failures with warning
+ * - Auto-update baseline when tests are fixed (ratchet forward)
+ *
+ * This enables agents to work on WUs without being blocked by unrelated
+ * test failures, while still preventing introduction of NEW failures.
+ *
+ * @see https://lumenflow.dev/reference/test-ratchet/
+ */
+import { z } from 'zod';
+import { parseISO, isValid } from 'date-fns';
+import { LUMENFLOW_PATHS } from './wu-constants.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default path for the test baseline file (WU-1430: Use centralized constant) */
+export const DEFAULT_BASELINE_PATH = LUMENFLOW_PATHS.TEST_BASELINE;
+/** Environment variable to override baseline path */
+export const BASELINE_PATH_ENV = 'LUMENFLOW_TEST_BASELINE';
+/** Current schema version */
+export const BASELINE_VERSION = 1;
+/**
+ * Zod schema for ISO8601 datetime strings.
+ * Uses date-fns (well-maintained library) for validation instead of regex.
+ */
+const isoDateTimeString = z.string().refine((val) => {
+    const parsed = parseISO(val);
+    return isValid(parsed);
+}, { message: 'Invalid ISO8601 datetime string' });
+// ============================================================================
+// Schema Definitions
+// ============================================================================
+/**
+ * Schema for a known test failure entry
+ */
+export const KnownFailureSchema = z.object({
+    /** Name of the failing test (describe > it format) */
+    test_name: z.string().min(1),
+    /** Path to the test file */
+    file_path: z.string().min(1),
+    /** Why this failure is in the baseline */
+    failure_reason: z.string().min(1),
+    /** When this failure was added to baseline */
+    added_at: isoDateTimeString,
+    /** Which WU added this to baseline */
+    added_by_wu: z.string().regex(/^WU-\d+$/),
+    /** WU expected to fix this failure (optional) */
+    expected_fix_wu: z
+        .string()
+        .regex(/^WU-\d+$/)
+        .optional(),
+    /** Optional reason for skipping this test */
+    skip_reason: z.string().optional(),
+});
+/**
+ * Schema for baseline statistics
+ */
+export const BaselineStatsSchema = z.object({
+    /** Total number of known failures */
+    total_known_failures: z.number().int().min(0),
+    /** Last time the baseline ratcheted forward (tests fixed) */
+    last_ratchet_forward: isoDateTimeString.optional(),
+});
+/**
+ * Schema for the complete test baseline file
+ */
+export const TestBaselineSchema = z.object({
+    /** Schema version for future migrations */
+    version: z.literal(BASELINE_VERSION),
+    /** When the baseline was last updated */
+    updated_at: isoDateTimeString,
+    /** Which WU last updated the baseline */
+    updated_by: z.string().regex(/^WU-\d+$/),
+    /** List of known test failures */
+    known_failures: z.array(KnownFailureSchema),
+    /** Baseline statistics */
+    stats: BaselineStatsSchema,
+});
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Parse a test baseline JSON string
+ *
+ * @param json - JSON string content of baseline file
+ * @returns Parse result with baseline data or error
+ */
+export function parseTestBaseline(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: `Invalid JSON: ${e instanceof Error ? e.message : 'Unknown error'}`,
+        };
+    }
+    const result = TestBaselineSchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            success: false,
+            error: `Schema validation failed: ${result.error.message}`,
+        };
+    }
+    return { success: true, data: result.data };
+}
+/**
+ * Create a new test baseline
+ *
+ * @param wuId - WU creating the baseline
+ * @param initialFailures - Optional initial failures to add
+ * @returns New test baseline
+ */
+export function createTestBaseline(wuId, initialFailures) {
+    const now = new Date().toISOString();
+    const knownFailures = (initialFailures ?? []).map((f) => ({
+        test_name: f.test_name,
+        file_path: f.file_path,
+        failure_reason: f.failure_reason,
+        added_at: now,
+        added_by_wu: wuId,
+        expected_fix_wu: f.expected_fix_wu,
+    }));
+    return {
+        version: BASELINE_VERSION,
+        updated_at: now,
+        updated_by: wuId,
+        known_failures: knownFailures,
+        stats: {
+            total_known_failures: knownFailures.length,
+        },
+    };
+}
+/**
+ * Compare current test results against the baseline
+ *
+ * This is the core ratchet logic:
+ * - NEW failures (not in baseline) block the gate
+ * - Pre-existing failures (in baseline) show warning
+ * - Fixed tests (in baseline but now passing) trigger ratchet forward
+ *
+ * @param baseline - The test baseline
+ * @param currentFailures - Current test failures from test run
+ * @returns Comparison result
+ */
+export function compareTestResults(baseline, currentFailures) {
+    const failingTests = currentFailures.filter((t) => !t.passed);
+    // Build lookup sets for efficient comparison
+    const baselineTestNames = new Set(baseline.known_failures.map((f) => f.test_name));
+    const currentFailingNames = new Set(failingTests.map((f) => f.test_name));
+    // Find NEW failures (in current failures, NOT in baseline)
+    const newFailures = failingTests.filter((f) => !baselineTestNames.has(f.test_name));
+    // Find pre-existing failures (in current failures AND in baseline)
+    const preExistingFailures = baseline.known_failures.filter((f) => currentFailingNames.has(f.test_name));
+    // Find fixed tests (in baseline but NOT in current failures)
+    const fixedTests = baseline.known_failures.filter((f) => !currentFailingNames.has(f.test_name));
+    return {
+        newFailures,
+        preExistingFailures,
+        fixedTests,
+        shouldBlock: newFailures.length > 0,
+        hasWarnings: preExistingFailures.length > 0,
+        shouldRatchetForward: fixedTests.length > 0,
+    };
+}
+/**
+ * Update the baseline (ratchet forward or add new known failures)
+ *
+ * @param baseline - Current baseline
+ * @param wuId - WU making the update
+ * @param options - Update options
+ * @returns Updated baseline (immutable)
+ */
+export function updateBaseline(baseline, wuId, options) {
+    const now = new Date().toISOString();
+    const { fixedTests = [], newKnownFailures = [] } = options;
+    // Remove fixed tests (ratchet forward)
+    const fixedTestSet = new Set(fixedTests);
+    let knownFailures = baseline.known_failures.filter((f) => !fixedTestSet.has(f.test_name));
+    // Add new known failures
+    const newEntries = newKnownFailures.map((f) => ({
+        test_name: f.test_name,
+        file_path: f.file_path,
+        failure_reason: f.failure_reason,
+        added_at: now,
+        added_by_wu: wuId,
+        expected_fix_wu: f.expected_fix_wu,
+    }));
+    knownFailures = [...knownFailures, ...newEntries];
+    const stats = {
+        total_known_failures: knownFailures.length,
+    };
+    // Record ratchet forward if we removed tests
+    if (fixedTests.length > 0) {
+        stats.last_ratchet_forward = now;
+    }
+    return {
+        version: BASELINE_VERSION,
+        updated_at: now,
+        updated_by: wuId,
+        known_failures: knownFailures,
+        stats,
+    };
+}
+// ============================================================================
+// Formatting Functions
+// ============================================================================
+/**
+ * Format a warning message for pre-existing failures
+ *
+ * @param preExisting - Pre-existing failures from baseline
+ * @returns Formatted warning string
+ */
+export function formatBaselineWarning(preExisting) {
+    const lines = [
+        '',
+        '='.repeat(70),
+        '  Pre-existing test failures (from baseline)',
+        '='.repeat(70),
+        '',
+        `  These failures are tracked in .lumenflow/test-baseline.json`,
+        '  They do not block your WU, but should be fixed eventually.',
+        '',
+    ];
+    for (const failure of preExisting) {
+        lines.push(`  - ${failure.test_name}`);
+        lines.push(`    File: ${failure.file_path}`);
+        lines.push(`    Reason: ${failure.failure_reason}`);
+        if (failure.expected_fix_wu) {
+            lines.push(`    Expected fix: ${failure.expected_fix_wu}`);
+        }
+        lines.push('');
+    }
+    lines.push('='.repeat(70));
+    return lines.join('\n');
+}
+/**
+ * Format an error message for new failures
+ *
+ * @param newFailures - New test failures
+ * @returns Formatted error string
+ */
+export function formatNewFailureError(newFailures) {
+    const lines = [
+        '',
+        '='.repeat(70),
+        '  NEW test failure(s) detected!',
+        '='.repeat(70),
+        '',
+        '  The following tests failed and are NOT in the baseline.',
+        '  This blocks your WU from completion.',
+        '',
+        '  Options:',
+        '    1. Fix the test or add to baseline with:',
+        '       pnpm baseline:add --test "<test_name>" --reason "<why>" --fix-wu WU-XXXX',
+        '    2. If this is a pre-existing failure on main, it should be in the baseline.',
+        '',
+    ];
+    for (const failure of newFailures) {
+        lines.push(`  - ${failure.test_name}`);
+        lines.push(`    File: ${failure.file_path}`);
+        if (failure.error_message) {
+            lines.push(`    Error: ${failure.error_message.substring(0, 100)}...`);
+        }
+        lines.push('');
+    }
+    lines.push('='.repeat(70));
+    return lines.join('\n');
+}
+/**
+ * Get the path to the test baseline file
+ *
+ * @returns Baseline file path
+ */
+export function getBaselineFilePath() {
+    return process.env[BASELINE_PATH_ENV] ?? DEFAULT_BASELINE_PATH;
+}
+//# sourceMappingURL=test-baseline.js.map

package/dist/test-baseline.js.map

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

package/dist/token-counter.d.ts

@@ -0,0 +1,50 @@
+interface PromptLoadResult {
+    text: string;
+    raw: string;
+}
+interface PromptAnalysisResult extends PromptLoadResult {
+    tokenCount: number;
+    hash: string;
+}
+interface LongestLine {
+    line: string;
+    length: number;
+    number: number;
+}
+/**
+ * Count tokens in text using gpt-5-nano tokenizer
+ * @param {string} text - Text to tokenize
+ * @returns {number} Token count
+ */
+export declare function countTokens(text: string): number;
+/**
+ * Compute SHA256 hash of text (for stability checks)
+ * @param {string} text - Text to hash
+ * @returns {string} Hex hash
+ */
+export declare function computeHash(text: string): string;
+/**
+ * Load and render a prompt file (resolves includes, strips comments)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{text: string, raw: string}} Rendered text and raw YAML
+ */
+export declare function loadPrompt(promptPath: string): PromptLoadResult;
+/**
+ * Analyze a prompt file (count tokens, compute hash, extract metadata)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{tokenCount: number, hash: string, text: string, raw: string}}
+ */
+export declare function analyzePrompt(promptPath: string): PromptAnalysisResult;
+/**
+ * Get top N longest lines from text (for cleanup targeting)
+ * @param {string} text - Text to analyze
+ * @param {number} n - Number of lines to return
+ * @returns {Array<{line: string, length: number, number: number}>} Longest lines
+ */
+export declare function getLongestLines(text: string, n?: number): LongestLine[];
+/**
+ * Cleanup function (call on process exit to free tokenizer)
+ */
+export declare function cleanup(): void;
+export {};
+//# sourceMappingURL=token-counter.d.ts.map

package/dist/token-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.d.ts","sourceRoot":"","sources":["../src/token-counter.ts"],"names":[],"mappings":"AAqBA,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,oBAAqB,SAAQ,gBAAgB;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAgBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAcD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAqC/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,CAWtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,WAAW,EAAE,CAalE;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAK9B"}

package/dist/token-counter.js

@@ -0,0 +1,144 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Token Counter Utility
+ *
+ * Wraps tiktoken for counting tokens in prompts using the o200k_base encoding
+ * (used by gpt-5-nano). Provides caching and hash computation for stability checks.
+ *
+ * Part of WU-676: Single-Call LLM Orchestrator token budget enforcement.
+ */
+import { get_encoding } from 'tiktoken';
+import { readFileSync } from 'fs';
+import { createHash } from 'crypto';
+import { parseYAML } from './wu-yaml.js';
+import { createError, ErrorCodes } from './error-handler.js';
+import { STRING_LITERALS } from './wu-constants.js';
+// Cache tokenizer instance (expensive to create)
+let tokenizerCache = null;
+/**
+ * Get or create tiktoken instance with o200k_base encoding (gpt-5-nano)
+ * @returns {Tiktoken} Tokenizer instance
+ */
+function getTokenizer() {
+    if (!tokenizerCache) {
+        tokenizerCache = get_encoding('o200k_base');
+    }
+    return tokenizerCache;
+}
+/**
+ * Count tokens in text using gpt-5-nano tokenizer
+ * @param {string} text - Text to tokenize
+ * @returns {number} Token count
+ */
+export function countTokens(text) {
+    if (!text || typeof text !== 'string') {
+        return 0;
+    }
+    const tokenizer = getTokenizer();
+    const tokens = tokenizer.encode(text);
+    return tokens.length;
+}
+/**
+ * Compute SHA256 hash of text (for stability checks)
+ * @param {string} text - Text to hash
+ * @returns {string} Hex hash
+ */
+export function computeHash(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/**
+ * Strip YAML comments from prompt text
+ * @param {string} text - YAML text
+ * @returns {string} Text with comments removed
+ */
+function stripYAMLComments(text) {
+    return text
+        .split(STRING_LITERALS.NEWLINE)
+        .filter((line) => !line.trim().startsWith('#'))
+        .join(STRING_LITERALS.NEWLINE);
+}
+/**
+ * Load and render a prompt file (resolves includes, strips comments)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{text: string, raw: string}} Rendered text and raw YAML
+ */
+export function loadPrompt(promptPath) {
+    try {
+        const raw = readFileSync(promptPath, { encoding: 'utf-8' });
+        // Parse YAML to access prompt structure
+        const parsed = parseYAML(raw);
+        // Extract prompt text (handle different YAML structures)
+        let promptText = '';
+        if (typeof parsed === 'string') {
+            promptText = parsed;
+        }
+        else if (parsed && parsed.prompt) {
+            promptText = parsed.prompt;
+        }
+        else if (parsed && parsed.system) {
+            promptText = parsed.system;
+        }
+        else if (parsed && parsed.content) {
+            promptText = parsed.content;
+        }
+        else {
+            // Fallback: use entire YAML stringified (for complex structures)
+            promptText = JSON.stringify(parsed, null, 2);
+        }
+        // Strip comments from rendered text
+        const renderedText = stripYAMLComments(promptText);
+        return { text: renderedText, raw };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Failed to load prompt from ${promptPath}: ${message}`, { path: promptPath, originalError: message });
+    }
+}
+/**
+ * Analyze a prompt file (count tokens, compute hash, extract metadata)
+ * @param {string} promptPath - Absolute path to prompt YAML file
+ * @returns {{tokenCount: number, hash: string, text: string, raw: string}}
+ */
+export function analyzePrompt(promptPath) {
+    const { text, raw } = loadPrompt(promptPath);
+    const tokenCount = countTokens(text);
+    const hash = computeHash(text);
+    return {
+        tokenCount,
+        hash,
+        text,
+        raw,
+    };
+}
+/**
+ * Get top N longest lines from text (for cleanup targeting)
+ * @param {string} text - Text to analyze
+ * @param {number} n - Number of lines to return
+ * @returns {Array<{line: string, length: number, number: number}>} Longest lines
+ */
+export function getLongestLines(text, n = 3) {
+    const lines = text.split(STRING_LITERALS.NEWLINE);
+    const linesWithMetadata = lines.map((line, index) => ({
+        line: line.trim(),
+        length: line.length,
+        number: index + 1,
+    }));
+    // Sort by length descending, take top N
+    return linesWithMetadata
+        .filter((lineInfo) => lineInfo.line.length > 0)
+        .sort((a, b) => b.length - a.length)
+        .slice(0, n);
+}
+/**
+ * Cleanup function (call on process exit to free tokenizer)
+ */
+export function cleanup() {
+    if (tokenizerCache) {
+        tokenizerCache.free();
+        tokenizerCache = null;
+    }
+}
+// Auto-cleanup on process exit
+process.on('exit', cleanup);
+//# sourceMappingURL=token-counter.js.map