archunit/dist/src/metrics/calculation/distance.d.ts

ArchUnit TypeScript is an architecture testing library, to specify and assert architecture rules in your TypeScript app

import { FileAnalysisResult } from '../extraction';
import { CheckOptions } from '../../common';
/**
 * Distance to Main Sequence metrics interface
 */
export interface DistanceMetric {
    name: string;
    calculateForFile(analysisResult: FileAnalysisResult): number;
    description: string;
}
/**
 * Abstractness metric (A)
 *
 * Measures the ratio of abstract declarations to total declarations in a file.
 * Formula: A = Na / N
 * Where:
 * - Na = number of abstract elements (interfaces, abstract classes, abstract methods)
 * - N = total number of declarations
 */
export declare class Abstractness implements DistanceMetric {
    name: string;
    description: string;
    calculateForFile(analysisResult: FileAnalysisResult): number;
}
/**
 * Instability metric (I)
 *
 * Measures the ratio of efferent coupling (outgoing dependencies) to total coupling.
 * Formula: I = Ce / (Ca + Ce)
 * Where:
 * - Ce = efferent coupling (outgoing dependencies)
 * - Ca = afferent coupling (incoming dependencies)
 */
export declare class Instability implements DistanceMetric {
    name: string;
    description: string;
    calculateForFile(analysisResult: FileAnalysisResult): number;
}
/**
 * Distance from Main Sequence metric (D)
 *
 * Robert Martin's metric that measures how far a component is from the ideal
 * balance between abstractness and instability.
 *
 * Formula: D = |A + I - 1|
 * Where:
 * - A = Abstractness (0 to 1)
 * - I = Instability (0 to 1)
 * - The main sequence is the line A + I = 1
 *
 * Interpretation:
 * - D = 0: On the main sequence (ideal)
 * - D closer to 0: Better design
 * - D closer to 1: Further from ideal balance
 *
 * When applied to files (file-wise analysis):
 * - Files that are abstract and stable (A high, I low) are on the main sequence
 * - Files that are concrete and unstable (A low, I high) are on the main sequence
 * - Files that are abstract and unstable are in the Zone of Uselessness
 * - Files that are concrete and stable are in the Zone of Pain
 */
export declare class DistanceFromMainSequence implements DistanceMetric {
    name: string;
    description: string;
    private abstractness;
    private instability;
    calculateForFile(analysisResult: FileAnalysisResult): number;
}
/**
 * Coupling Factor metric (CF)
 *
 * Measures how tightly coupled a file is based on both incoming and outgoing dependencies.
 * Higher values indicate more coupling, which generally should be minimized.
 * Formula: CF = (Ca + Ce) / Cmax
 * Where:
 * - Ca = afferent coupling (incoming dependencies)
 * - Ce = efferent coupling (outgoing dependencies)
 * - Cmax = maximum possible coupling (a normalization factor, typically file count - 1)
 */
export declare class CouplingFactor implements DistanceMetric {
    name: string;
    description: string;
    calculateForFile(analysisResult: FileAnalysisResult, totalFiles?: number): number;
}
/**
 * Normalized Distance metric (ND)
 *
 * A modified version of Distance from Main Sequence that accounts for file size.
 * Files with more code are expected to be more complex and potentially have
 * more responsibilities, so they should be closer to the main sequence.
 * Formula: ND = D * (1 - S/Smax)
 * Where:
 * - D = Distance from Main Sequence
 * - S = Size of file (measured in LOC or declarations)
 * - Smax = Maximum size for normalization
 */
export declare class NormalizedDistance implements DistanceMetric {
    name: string;
    description: string;
    private distance;
    calculateForFile(analysisResult: FileAnalysisResult): number;
}
/**
 * Calculate distance metrics for a single file
 * @param analysisResult The file analysis result
 * @param totalFiles Optional total number of files for coupling factor calculation
 * @returns Distance metrics for the file
 */
export declare function calculateFileDistanceMetrics(analysisResult: FileAnalysisResult, totalFiles?: number): {
    filePath: string;
    abstractness: number;
    instability: number;
    distanceFromMainSequence: number;
    couplingFactor: number;
    normalizedDistance: number;
    analysisResult: FileAnalysisResult;
};
/**
 * Utility function to calculate distance metrics for an entire project
 * using file-wise analysis based on TypeScript AST and dependency graphs
 */
export declare function calculateDistanceMetricsForProject(tsConfigPath?: string, projectPath?: string, options?: CheckOptions): Promise<{
    fileResults: Array<{
        filePath: string;
        abstractness: number;
        instability: number;
        distanceFromMainSequence: number;
        couplingFactor: number;
        normalizedDistance: number;
        analysisResult: FileAnalysisResult;
    }>;
    projectSummary: {
        totalFiles: number;
        averageAbstractness: number;
        averageInstability: number;
        averageDistance: number;
        averageCouplingFactor: number;
        averageNormalizedDistance: number;
        filesOnMainSequence: number;
    };
}>;