@mkpro118/semantic-change-detector/dist/analysis-runner.d.ts

Semantic change detection for TypeScript and TSX code with GitHub Actions integration

/**
 * @file This module contains the core logic for analyzing file changes.
 * It orchestrates fetching file content from git, generating diffs, creating semantic contexts,
 * and running the final analysis.
 */
import { type AnalyzerConfig } from './types/config.js';
import type { AnalysisResult, DiffHunk, SemanticChangeType, SeverityLevel } from './types/index.js';
/**
 * Represents a single semantic change detected in a file.
 */
/**
 * FileChange describes a single semantic change within a file when
 * running file-by-file analysis. This is the lightweight shape used by
 * the CLI before aggregation.
 *
 * @library-export
 * @public
 */
export type FileChange = {
    /** The line number where the change occurred. */
    line: number;
    /** The column number where the change occurred. */
    column: number;
    /** The specific type of change that was detected. */
    kind: SemanticChangeType;
    /** A human-readable description of the change. */
    detail: string;
    /** The severity of the change (high, medium, or low). */
    severity: SeverityLevel;
    /** The type of the AST node related to the change. */
    astNode: string;
    /** Optional additional context about the change, like the original and new function signatures. */
    context?: string;
};
/**
 * Analyzes the semantic changes between two versions of a single file.
 * @param filePath The path to the file to analyze.
 * @param baseRef The git ref for the base version of the file.
 * @param headRef The git ref for the head version of the file.
 * @param config The analyzer configuration.
 * @returns An array of detected semantic changes for the file.
 */
export declare function analyzeFileChanges(filePath: string, baseRef: string, headRef: string, config: AnalyzerConfig): Promise<Array<FileChange>>;
/**
 * Overrides the internal git runner function. Used for testing purposes.
 * @param fn The function to use for running git commands.
 * @internal
 */
export declare function __setGitRunner(fn: (args: string[]) => {
    status: number;
    stdout?: string;
}): void;
/**
 * Retrieves the content of a file from a specific git ref.
 * @param filePath The path to the file.
 * @param ref The git ref (e.g., commit SHA, branch name).
 * @returns The file content as a string, or null if it could not be retrieved.
 */
export declare function getFileContent(filePath: string, ref: string): string | null;
/**
 * Performs a lightweight analysis of a new file to find some basic changes.
 * @param content The full content of the new file.
 * @param _filePath The path to the new file (currently unused).
 * @returns An array of high-level changes found in the new file.
 */
export declare function analyzeNewFile(content: string, filePath: string): Array<FileChange>;
/**
 * Generates an array of diff hunks representing the changes between two versions of a file.
 * It attempts to use `git diff` for precision, falling back to a single, full-file hunk.
 * @param baseContent The content of the base version.
 * @param headContent The content of the head version.
 * @param filePath The path to the file.
 * @param baseRef The git ref for the base version.
 * @param headRef The git ref for the head version.
 * @returns An array of diff hunks.
 */
export declare function generateDiffHunks(baseContent: string, headContent: string, filePath: string, baseRef: string, headRef: string): DiffHunk[];
/**
 * Parses a unified diff patch string into an array of DiffHunk objects.
 * @param patch The raw string output from a `git diff` command.
 * @param filePath The path to the file the patch applies to.
 * @returns An array of structured diff hunks.
 */
export declare function parseUnifiedDiff(patch: string, filePath: string): DiffHunk[];
/**
 * Checks if a file has any diffs between two git refs.
 * @param filePath The path to the file to check.
 * @param baseRef The git ref for the base version.
 * @param headRef The git ref for the head version.
 * @returns True if the file has diffs, false otherwise.
 */
export declare function hasDiffs(filePath: string, baseRef: string, headRef: string): boolean;
/**
 * Defines the shape of the command-line options for the CLI.
 */
/**
 * AnalysisOptions defines the CLI's user-configurable options. These
 * values determine which refs and files are analyzed and how results
 * are reported.
 *
 * @library-export
 * @public
 */
export type AnalysisOptions = {
    /** The git ref for the base version (e.g., main, sha). */
    baseRef: string;
    /** The git ref for the head version (e.g., feature-branch, sha). */
    headRef: string;
    /** A list of file paths to analyze. */
    files: string[];
    /** The desired output format. */
    outputFormat: 'json' | 'github-actions' | 'console' | 'machine';
    /** The path to write JSON output to. */
    outputFile?: string;
    /** Flag to enable maximum debug logging. */
    debug?: boolean;
    /** Flag to suppress all output except for exit codes. */
    quiet?: boolean;
    /** The timeout in milliseconds for analyzing a single file. */
    timeoutMs?: number;
    /** Whether to show help. */
    help?: boolean;
    /** Whether to read file paths from stdin. */
    stdin?: boolean;
    /** Path to a custom analyzer configuration file. */
    configPath?: string;
};
/**
 * The main function to run the semantic analysis process.
 * It coordinates file filtering, concurrent analysis, and result processing.
 * @param options The analysis options parsed from the command line.
 * @returns A promise that resolves with the final analysis result.
 */
export declare function runSemanticAnalysis(options: AnalysisOptions): Promise<AnalysisResult>;
/**
 * Writes the `requires-tests` output for GitHub Actions.
 * @param requiresTests A boolean indicating if tests are required.
 */
export declare function writeGitHubOutputFlag(requiresTests: boolean): void;
//# sourceMappingURL=analysis-runner.d.ts.map