logpare 0.0.1 → 0.0.3

package/dist/index.d.cts

@@ -0,0 +1,259 @@
+/**
+ * Strategy for preprocessing and parsing log lines.
+ * Decouples policy from mechanism for extensibility.
+ */
+interface ParsingStrategy {
+    /** Transform line before parsing (masking, normalization) */
+    preprocess(line: string): string;
+    /** Split line into tokens */
+    tokenize(line: string): string[];
+    /** Dynamic similarity threshold (can vary by tree depth) */
+    getSimThreshold(depth: number): number;
+}
+/**
+ * A discovered log template.
+ */
+interface Template {
+    /** Unique identifier for this template */
+    id: string;
+    /** Pattern string with variables replaced by <*> */
+    pattern: string;
+    /** Number of log lines matching this template */
+    occurrences: number;
+    /** Sample variable values from first N matches */
+    sampleVariables: string[][];
+    /** Line index of first occurrence */
+    firstSeen: number;
+    /** Line index of most recent occurrence */
+    lastSeen: number;
+}
+/**
+ * Result of log compression.
+ */
+interface CompressionResult {
+    /** All discovered templates */
+    templates: Template[];
+    /** Compression statistics */
+    stats: {
+        /** Total input lines processed */
+        inputLines: number;
+        /** Number of unique templates discovered */
+        uniqueTemplates: number;
+        /** Compression ratio (0.0 - 1.0, higher = more compression) */
+        compressionRatio: number;
+        /** Estimated token reduction percentage */
+        estimatedTokenReduction: number;
+    };
+    /** Formatted output string */
+    formatted: string;
+}
+/**
+ * Configuration options for Drain algorithm.
+ */
+interface DrainOptions {
+    /** Parse tree depth (excluding length/first-token levels). Default: 4 */
+    depth?: number;
+    /** Minimum similarity to match existing cluster (0.0-1.0). Default: 0.4 */
+    simThreshold?: number;
+    /** Maximum children per node (prevents explosion). Default: 100 */
+    maxChildren?: number;
+    /** Maximum total clusters (memory bound). Default: 1000 */
+    maxClusters?: number;
+    /** Maximum sample variables to store per template. Default: 3 */
+    maxSamples?: number;
+    /** Custom preprocessing strategy */
+    preprocessing?: ParsingStrategy;
+}
+/**
+ * Output format for compression results.
+ */
+type OutputFormat = 'summary' | 'detailed' | 'json';
+/**
+ * Options for the compress() function.
+ */
+interface CompressOptions {
+    /** Output format. Default: 'summary' */
+    format?: OutputFormat;
+    /** Maximum templates to include in output. Default: 50 */
+    maxTemplates?: number;
+    /** Drain algorithm options */
+    drain?: DrainOptions;
+}
+
+/**
+ * Compress log lines by extracting templates.
+ *
+ * This is the main entry point for simple use cases.
+ * For more control, use `createDrain()` directly.
+ *
+ * @param lines - Array of log lines to compress
+ * @param options - Compression options
+ * @returns Compression result with templates and statistics
+ *
+ * @example
+ * ```typescript
+ * import { compress } from 'logpare';
+ *
+ * const logs = [
+ *   'Connection from 192.168.1.1 established',
+ *   'Connection from 192.168.1.2 established',
+ *   'Connection from 10.0.0.1 established',
+ * ];
+ *
+ * const result = compress(logs);
+ * console.log(result.formatted);
+ * // Output: [3x] Connection from <*> established
+ * ```
+ */
+declare function compress(lines: string[], options?: CompressOptions): CompressionResult;
+/**
+ * Compress a single string containing multiple log lines.
+ *
+ * @param text - Raw log text (lines separated by newlines)
+ * @param options - Compression options
+ * @returns Compression result with templates and statistics
+ */
+declare function compressText(text: string, options?: CompressOptions): CompressionResult;
+
+/**
+ * Represents a log cluster (template) discovered by the Drain algorithm.
+ *
+ * V8 Optimization: All properties are initialized in the constructor
+ * to ensure monomorphic object shapes for optimal property access.
+ */
+declare class LogCluster {
+    /** Unique identifier for this cluster */
+    readonly id: string;
+    /** Template tokens (with wildcards for variable positions) */
+    readonly tokens: string[];
+    /** Number of log lines matching this template */
+    count: number;
+    /** Sample variable values from first N matches */
+    readonly sampleVariables: string[][];
+    /** Line index of first occurrence */
+    firstSeen: number;
+    /** Line index of most recent occurrence */
+    lastSeen: number;
+    /** Maximum number of sample variables to store */
+    private readonly maxSamples;
+    constructor(id: string, tokens: string[], lineIndex: number, maxSamples?: number);
+    /**
+     * Update the cluster with a new matching log line.
+     * Returns the variables extracted from this match.
+     */
+    update(tokens: string[], lineIndex: number): string[];
+    /**
+     * Get the template pattern as a string.
+     */
+    getPattern(): string;
+    /**
+     * Compute similarity between this cluster's template and a set of tokens.
+     * Returns a value between 0.0 and 1.0.
+     */
+    computeSimilarity(tokens: string[]): number;
+    /**
+     * Merge tokens into the template, converting differing positions to wildcards.
+     * Mutates the template tokens in place.
+     */
+    mergeTokens(tokens: string[]): void;
+}
+
+/**
+ * Drain algorithm implementation for log template mining.
+ *
+ * The algorithm constructs a fixed-depth parse tree to efficiently
+ * cluster log messages by their template structure.
+ *
+ * Tree Structure:
+ * - Level 0 (root): Entry point
+ * - Level 1: Token count (length of log message)
+ * - Level 2: First token of the message
+ * - Levels 3+: Subsequent tokens up to configured depth
+ * - Leaf: LogCluster containing the template
+ */
+declare class Drain {
+    private readonly root;
+    private readonly clusters;
+    private readonly strategy;
+    private readonly depth;
+    private readonly maxChildren;
+    private readonly maxClusters;
+    private readonly maxSamples;
+    private lineCount;
+    private nextClusterId;
+    constructor(options?: DrainOptions);
+    /**
+     * Process a single log line.
+     */
+    addLogLine(line: string): LogCluster | null;
+    /**
+     * Process multiple log lines.
+     */
+    addLogLines(lines: string[]): void;
+    /**
+     * Search the parse tree for a matching cluster.
+     */
+    private treeSearch;
+    /**
+     * Find the best matching cluster at a node.
+     */
+    private findBestMatch;
+    /**
+     * Create a new cluster and add it to the tree.
+     */
+    private createCluster;
+    /**
+     * Determine if we should use a wildcard key for a token.
+     * Uses maxChildren limit to prevent tree explosion.
+     */
+    private shouldUseWildcard;
+    /**
+     * Heuristic to detect if a token looks like a variable value.
+     */
+    private looksLikeVariable;
+    /**
+     * Get all discovered templates.
+     */
+    getTemplates(): Template[];
+    /**
+     * Get compression result with formatted output.
+     */
+    getResult(format?: OutputFormat, maxTemplates?: number): CompressionResult;
+    /**
+     * Calculate compression statistics.
+     */
+    private calculateStats;
+    /**
+     * Get the number of lines processed.
+     */
+    get totalLines(): number;
+    /**
+     * Get the number of clusters (templates) discovered.
+     */
+    get totalClusters(): number;
+}
+/**
+ * Create a new Drain instance with the given options.
+ */
+declare function createDrain(options?: DrainOptions): Drain;
+
+/**
+ * Built-in regex patterns for common variable types.
+ * These are applied in order during preprocessing to mask variables.
+ * Order matters: more specific patterns (like timestamps) must run before
+ * patterns that could match substrings (like port numbers).
+ */
+declare const DEFAULT_PATTERNS: Record<string, RegExp>;
+/**
+ * Placeholder used when masking variables.
+ */
+declare const WILDCARD = "<*>";
+
+/**
+ * Create a custom parsing strategy by extending the default.
+ */
+declare function defineStrategy(overrides: Partial<ParsingStrategy> & {
+    patterns?: Record<string, RegExp>;
+}): ParsingStrategy;
+
+export { type CompressOptions, type CompressionResult, DEFAULT_PATTERNS, Drain, type DrainOptions, type OutputFormat, type ParsingStrategy, type Template, WILDCARD, compress, compressText, createDrain, defineStrategy };

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Strategy for preprocessing and parsing log lines.
+ * Decouples policy from mechanism for extensibility.
+ */
+interface ParsingStrategy {
+    /** Transform line before parsing (masking, normalization) */
+    preprocess(line: string): string;
+    /** Split line into tokens */
+    tokenize(line: string): string[];
+    /** Dynamic similarity threshold (can vary by tree depth) */
+    getSimThreshold(depth: number): number;
+}
+/**
+ * A discovered log template.
+ */
+interface Template {
+    /** Unique identifier for this template */
+    id: string;
+    /** Pattern string with variables replaced by <*> */
+    pattern: string;
+    /** Number of log lines matching this template */
+    occurrences: number;
+    /** Sample variable values from first N matches */
+    sampleVariables: string[][];
+    /** Line index of first occurrence */
+    firstSeen: number;
+    /** Line index of most recent occurrence */
+    lastSeen: number;
+}
+/**
+ * Result of log compression.
+ */
+interface CompressionResult {
+    /** All discovered templates */
+    templates: Template[];
+    /** Compression statistics */
+    stats: {
+        /** Total input lines processed */
+        inputLines: number;
+        /** Number of unique templates discovered */
+        uniqueTemplates: number;
+        /** Compression ratio (0.0 - 1.0, higher = more compression) */
+        compressionRatio: number;
+        /** Estimated token reduction percentage */
+        estimatedTokenReduction: number;
+    };
+    /** Formatted output string */
+    formatted: string;
+}
+/**
+ * Configuration options for Drain algorithm.
+ */
+interface DrainOptions {
+    /** Parse tree depth (excluding length/first-token levels). Default: 4 */
+    depth?: number;
+    /** Minimum similarity to match existing cluster (0.0-1.0). Default: 0.4 */
+    simThreshold?: number;
+    /** Maximum children per node (prevents explosion). Default: 100 */
+    maxChildren?: number;
+    /** Maximum total clusters (memory bound). Default: 1000 */
+    maxClusters?: number;
+    /** Maximum sample variables to store per template. Default: 3 */
+    maxSamples?: number;
+    /** Custom preprocessing strategy */
+    preprocessing?: ParsingStrategy;
+}
+/**
+ * Output format for compression results.
+ */
+type OutputFormat = 'summary' | 'detailed' | 'json';
+/**
+ * Options for the compress() function.
+ */
+interface CompressOptions {
+    /** Output format. Default: 'summary' */
+    format?: OutputFormat;
+    /** Maximum templates to include in output. Default: 50 */
+    maxTemplates?: number;
+    /** Drain algorithm options */
+    drain?: DrainOptions;
+}
+
+/**
+ * Compress log lines by extracting templates.
+ *
+ * This is the main entry point for simple use cases.
+ * For more control, use `createDrain()` directly.
+ *
+ * @param lines - Array of log lines to compress
+ * @param options - Compression options
+ * @returns Compression result with templates and statistics
+ *
+ * @example
+ * ```typescript
+ * import { compress } from 'logpare';
+ *
+ * const logs = [
+ *   'Connection from 192.168.1.1 established',
+ *   'Connection from 192.168.1.2 established',
+ *   'Connection from 10.0.0.1 established',
+ * ];
+ *
+ * const result = compress(logs);
+ * console.log(result.formatted);
+ * // Output: [3x] Connection from <*> established
+ * ```
+ */
+declare function compress(lines: string[], options?: CompressOptions): CompressionResult;
+/**
+ * Compress a single string containing multiple log lines.
+ *
+ * @param text - Raw log text (lines separated by newlines)
+ * @param options - Compression options
+ * @returns Compression result with templates and statistics
+ */
+declare function compressText(text: string, options?: CompressOptions): CompressionResult;
+
+/**
+ * Represents a log cluster (template) discovered by the Drain algorithm.
+ *
+ * V8 Optimization: All properties are initialized in the constructor
+ * to ensure monomorphic object shapes for optimal property access.
+ */
+declare class LogCluster {
+    /** Unique identifier for this cluster */
+    readonly id: string;
+    /** Template tokens (with wildcards for variable positions) */
+    readonly tokens: string[];
+    /** Number of log lines matching this template */
+    count: number;
+    /** Sample variable values from first N matches */
+    readonly sampleVariables: string[][];
+    /** Line index of first occurrence */
+    firstSeen: number;
+    /** Line index of most recent occurrence */
+    lastSeen: number;
+    /** Maximum number of sample variables to store */
+    private readonly maxSamples;
+    constructor(id: string, tokens: string[], lineIndex: number, maxSamples?: number);
+    /**
+     * Update the cluster with a new matching log line.
+     * Returns the variables extracted from this match.
+     */
+    update(tokens: string[], lineIndex: number): string[];
+    /**
+     * Get the template pattern as a string.
+     */
+    getPattern(): string;
+    /**
+     * Compute similarity between this cluster's template and a set of tokens.
+     * Returns a value between 0.0 and 1.0.
+     */
+    computeSimilarity(tokens: string[]): number;
+    /**
+     * Merge tokens into the template, converting differing positions to wildcards.
+     * Mutates the template tokens in place.
+     */
+    mergeTokens(tokens: string[]): void;
+}
+
+/**
+ * Drain algorithm implementation for log template mining.
+ *
+ * The algorithm constructs a fixed-depth parse tree to efficiently
+ * cluster log messages by their template structure.
+ *
+ * Tree Structure:
+ * - Level 0 (root): Entry point
+ * - Level 1: Token count (length of log message)
+ * - Level 2: First token of the message
+ * - Levels 3+: Subsequent tokens up to configured depth
+ * - Leaf: LogCluster containing the template
+ */
+declare class Drain {
+    private readonly root;
+    private readonly clusters;
+    private readonly strategy;
+    private readonly depth;
+    private readonly maxChildren;
+    private readonly maxClusters;
+    private readonly maxSamples;
+    private lineCount;
+    private nextClusterId;
+    constructor(options?: DrainOptions);
+    /**
+     * Process a single log line.
+     */
+    addLogLine(line: string): LogCluster | null;
+    /**
+     * Process multiple log lines.
+     */
+    addLogLines(lines: string[]): void;
+    /**
+     * Search the parse tree for a matching cluster.
+     */
+    private treeSearch;
+    /**
+     * Find the best matching cluster at a node.
+     */
+    private findBestMatch;
+    /**
+     * Create a new cluster and add it to the tree.
+     */
+    private createCluster;
+    /**
+     * Determine if we should use a wildcard key for a token.
+     * Uses maxChildren limit to prevent tree explosion.
+     */
+    private shouldUseWildcard;
+    /**
+     * Heuristic to detect if a token looks like a variable value.
+     */
+    private looksLikeVariable;
+    /**
+     * Get all discovered templates.
+     */
+    getTemplates(): Template[];
+    /**
+     * Get compression result with formatted output.
+     */
+    getResult(format?: OutputFormat, maxTemplates?: number): CompressionResult;
+    /**
+     * Calculate compression statistics.
+     */
+    private calculateStats;
+    /**
+     * Get the number of lines processed.
+     */
+    get totalLines(): number;
+    /**
+     * Get the number of clusters (templates) discovered.
+     */
+    get totalClusters(): number;
+}
+/**
+ * Create a new Drain instance with the given options.
+ */
+declare function createDrain(options?: DrainOptions): Drain;
+
+/**
+ * Built-in regex patterns for common variable types.
+ * These are applied in order during preprocessing to mask variables.
+ * Order matters: more specific patterns (like timestamps) must run before
+ * patterns that could match substrings (like port numbers).
+ */
+declare const DEFAULT_PATTERNS: Record<string, RegExp>;
+/**
+ * Placeholder used when masking variables.
+ */
+declare const WILDCARD = "<*>";
+
+/**
+ * Create a custom parsing strategy by extending the default.
+ */
+declare function defineStrategy(overrides: Partial<ParsingStrategy> & {
+    patterns?: Record<string, RegExp>;
+}): ParsingStrategy;
+
+export { type CompressOptions, type CompressionResult, DEFAULT_PATTERNS, Drain, type DrainOptions, type OutputFormat, type ParsingStrategy, type Template, WILDCARD, compress, compressText, createDrain, defineStrategy };

package/dist/index.js

@@ -0,0 +1,19 @@
+import {
+  DEFAULT_PATTERNS,
+  Drain,
+  WILDCARD,
+  compress,
+  compressText,
+  createDrain,
+  defineStrategy
+} from "./chunk-JRS36ZWP.js";
+export {
+  DEFAULT_PATTERNS,
+  Drain,
+  WILDCARD,
+  compress,
+  compressText,
+  createDrain,
+  defineStrategy
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,23 +1,57 @@
 {
   "name": "logpare",
-  "version": "0.0.1",
-  "description": "Semantic log reduction for LLM debugging - see @logpare/mcp for the MCP server implementation",
-  "main": "index.js",
+  "version": "0.0.3",
+  "description": "Semantic log compression that reduces repetitive events while preserving diagnostic information",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "logpare": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
   "keywords": [
     "log",
     "compression",
+    "parsing",
+    "drain",
+    "template",
     "llm",
-    "mcp",
-    "semantic-reduction"
+    "mcp"
   ],
   "author": "Jeff Green <contact@hirejeffgreen.com>",
+  "homepage": "https://github.com/logpare/logpare",
+  "bugs": {
+    "url": "https://github.com/logpare/logpare/issues"
+  },
   "license": "MIT",
-  "homepage": "https://github.com/logpare",
   "repository": {
     "type": "git",
-    "url": "https://github.com/logpare/logpare-mcp"
+    "url": "https://github.com/logpare/logpare"
   },
-  "bugs": {
-    "url": "https://github.com/logpare/logpare-mcp/issues"
+  "engines": {
+    "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   }
 }

package/index.js

@@ -1 +0,0 @@
-module.exports = {};