cmpstr/dist/types/utils/DiffChecker.d.ts

CmpStr is a lightweight, fast and well performing package for calculating string similarity

/**
 * DiffChecker Utility
 * src/utils/DiffChecker.ts
 *
 * The DiffChecker class provides a robust and efficient utility for comparing two
 * texts and extracting their differences (full lines or word mode). It supports
 * context-aware grouping of changes, unified diff output (with CLI color or ASCII
 * markup), and detailed change magnitude metrics. The class is highly configurable,
 * allowing users to choose the diff granularity, case sensitivity, context lines,
 * grouping, and output style. It is suitable for text comparison, code review
 * tools, document versioning, and any application requiring precise and human-
 * readable difference reporting.
 *
 * Features:
 *  - Line and word-based diffing
 *  - Case-insensitive comparison option
 *  - Context lines and grouping of adjacent changes
 *  - Unified diff output (ASCII or colored CLI)
 *  - Highlighting of changed segments within lines
 *  - Change magnitude calculation (relative to group or line)
 *  - Expand-all mode for full file context
 *
 * @module Utils/DiffChecker
 * @author Paul Köhler (komed3)
 * @license MIT
 */
import type { DiffOptions, DiffLine, DiffGroup } from './Types';
/**
 * The DiffChecker class provides methods to compare two texts and generate
 * structured diffs, grouped diffs, and unified diff outputs.
 */
export declare class DiffChecker {
    private readonly a;
    private readonly b;
    private readonly options;
    private entries;
    private grouped;
    private diffRun;
    /**
     * Constructs a new DiffChecker instance for comparing two texts.
     *
     * @param {string} a - The first (original) text
     * @param {string} b - The second (modified) text
     * @param {DiffOptions} [opt] - Optional diff configuration
     */
    constructor(a: string, b: string, opt?: DiffOptions);
    /**
     * Splits both input texts into arrays of lines and returns them
     * with the maximum line count.
     *
     * @returns { linesA: string[], linesB: string[], maxLen: number }
     */
    private text2lines;
    /**
     * Tokenizes a string according to the current diff mode (line or word).
     *
     * @param {string} input - The string to tokenize
     * @returns {string[]} - Array of tokens
     */
    private tokenize;
    /**
     * Concatenates an array of tokens back into a string, respecting the diff mode.
     *
     * @param {string[]} input - Array of tokens
     * @returns {string} - Concatenated string
     */
    private concat;
    /**
     * Computes the diff between the two input texts and populates the
     * entries and grouped arrays.
     */
    private computeDiff;
    /**
     * Compares two lines and records their differences at the configured granularity.
     *
     * @param {string} a - Line from the first text
     * @param {string} b - Line from the second text
     * @param {number} line - Line number
     */
    private lineDiff;
    /**
     * Finds all minimal diff blocks between two tokenized strings,
     * returning original text and positions.
     *
     * @param {string} a - Original line (case preserved)
     * @param {string} A - Original line (possibly lowercased)
     * @param {string} b - Modified line (case preserved)
     * @param {string} B - Modified line (possibly lowercased)
     * @returns {DiffEntry[]} - Array of diff entries for this line
     */
    private preciseDiff;
    /**
     * Groups adjacent changed lines together, including context lines,
     * and calculates group metrics.
     */
    private findGroups;
    /**
     * Calculates the change magnitude string for a group or line.
     *
     * @param {number} del - Number of deleted characters
     * @param {number} ins - Number of inserted characters
     * @param {number} baseLen - Base length for normalization
     * @returns {string} - Magnitude string (e.g. "++-")
     */
    private magnitude;
    /**
     * Generates a unified diff output as a string, with optional CLI coloring.
     *
     * @param {boolean} cli - If true, use CLI colors; otherwise, ASCII markup
     * @returns {string} - Unified diff output
     */
    private output;
    /**
     * Returns the structured diff as an array of DiffLine objects.
     *
     * @returns {DiffLine[]} - Array of line-level diffs
     */
    getStructuredDiff(): DiffLine[];
    /**
     * Returns the grouped diff as an array of DiffGroup objects.
     *
     * @returns {DiffGroup[]} - Array of grouped diffs
     */
    getGroupedDiff(): DiffGroup[];
    /**
     * Returns the unified diff as a plain ASCII string.
     *
     * @returns {string} - Unified diff (ASCII)
     */
    getASCIIDiff(): string;
    /**
     * Returns the unified diff as a CLI-colored string.
     *
     * @returns {string} - Unified diff (CLI colors)
     */
    getCLIDiff(): string;
}