@ngcompass/reporters 0.1.1-beta

package/dist/index.d.cts

@@ -0,0 +1,466 @@
+import { RuleResult, ConfigReport, InitResult, HealthReport, RuleListEntry } from '@ngcompass/common';
+import { CacheInfo } from '@ngcompass/cache';
+
+/**
+ * Reporter contracts and DTOs for ngcompass CLI output.
+ *
+ * Design goals:
+ * - Tool-agnostic contracts (no ESLint coupling).
+ * - Explicit, semantic naming.
+ * - Composable interfaces (ISP, DIP).
+ * - Clear public API documentation.
+ */
+
+/** Supported output encodings for analysis results. */
+type ReporterFormat = 'console' | 'json' | 'html' | 'ui' | 'sarif';
+interface ConsoleReporterOptions {
+    /**
+     * Uses compact, standard one-line-per-violation layout.
+     * Suitable for CI environments and editor integration.
+     */
+    readonly compact?: boolean;
+    /**
+     * Output file path for the HTML reporter.
+     * Defaults to `ngcompass-report.html` in the current working directory.
+     * Only used when `ReporterFormat` is `'html'` or `'ui'`.
+     */
+    readonly outputPath?: string;
+    /**
+     * TTY stream used for in-place phase updates.
+     * Defaults to process.stdout. Override to process.stderr for non-console formats.
+     */
+    readonly phaseStream?: NodeJS.WriteStream;
+    /** Suppress violation details — show only the summary counts. */
+    readonly quiet?: boolean;
+    /** Suppress fix/recommendation text from violation output. */
+    readonly noRecommendation?: boolean;
+}
+/**
+ * Summary statistics produced at the end of an analysis run.
+ *
+ * Consumed by `ProgressReporter.summary()`.
+ */
+interface ResultSummary {
+    /** Total number of source files that were scanned (passed to the planner). */
+    readonly scannedFiles: number;
+    /** Total files found by the scanner (all file types, including HTML/SCSS/JSON). */
+    readonly discoveredFiles?: number;
+    /** Files that contained at least one violation. */
+    readonly totalFiles: number;
+    readonly totalTasks: number;
+    readonly cachedTasks?: number;
+    readonly totalErrors: number;
+    readonly totalWarnings: number;
+    readonly failOnSeverity?: 'warn' | 'error';
+    readonly maxWarnings?: number;
+    readonly duration: number;
+}
+/**
+ * Core analysis reporter contract.
+ *
+ * @remarks
+ * Implementations receive analysis results and surface them to the user.
+ * `report()` must handle an empty array gracefully (emit a "no violations" message).
+ * None of the methods should throw — errors are surfaced via `error()`.
+ */
+interface AnalysisReporter {
+    /**
+     * Renders all rule results.
+     * @param results - May be empty; reporters must handle this gracefully.
+     */
+    report(results: ReadonlyArray<RuleResult>): void;
+    /**
+     * Called when an unexpected runtime failure occurs during analysis.
+     * @param error - The caught exception. Implementations should surface both
+     *                `error.message` and (optionally) `error.stack`.
+     */
+    error(error: Error): void;
+    /**
+     * Called when one or more files could not be parsed or analyzed.
+     * @param errors - Array of parse failures; implementations should no-op on empty arrays.
+     */
+    parseErrors(errors: ReadonlyArray<ParseError>): void;
+}
+/**
+ * Progressive reporting contract for interactive / TTY environments.
+ *
+ * @remarks
+ * Non-interactive reporters (e.g. `JsonReporter`) implement this with no-ops.
+ * Callers that only need analysis output should accept `AnalysisReporter`, not `Reporter`.
+ */
+interface ProgressReporter {
+    /** Emits a bold status step, e.g. "Analyzing 42 files…". */
+    summary(stats: ResultSummary): void;
+    /** Emits a high-visibility progress message. */
+    step(message: string): void;
+    /** Emits a dim informational message. */
+    info(message: string): void;
+    /** Emits a debug message; may be suppressed unless verbose mode is active. */
+    debug(message: string): void;
+    /** Erases the current in-place phase line (TTY only). No-op on non-TTY. */
+    clearLine?(): void;
+}
+/**
+ * Combined reporter contract expected by the CLI orchestrator.
+ *
+ * @remarks
+ * Prefer the narrower `AnalysisReporter` or `ProgressReporter` types for
+ * functions that only need one facet, to avoid forcing callers to satisfy
+ * the full combined surface.
+ */
+type Reporter = AnalysisReporter & ProgressReporter;
+/**
+ * Reporter contract for configuration-related commands (`compass config`, `compass health`).
+ *
+ * Separated from `Reporter` because config commands do not produce `RuleResult` output
+ * and must not be forced to implement the full analysis surface.
+ */
+interface ConfigReporter {
+    /**
+     * Renders full config validation output.
+     * @param report - The validation result from the config loader.
+     */
+    reportConfig(report: ConfigReport): void;
+    /**
+     * Renders the outcome of `compass init`.
+     * @param result - The init operation result (success, already-exists, or failure).
+     */
+    renderInitResult(result: InitResult): void;
+    /**
+     * Renders the full project health report.
+     * @param report - Aggregated health issues, one per config concern.
+     */
+    renderHealthReport(report: HealthReport): void;
+}
+/**
+ * Represents a file that could not be parsed during analysis.
+ */
+interface ParseError {
+    readonly filePath: string;
+    readonly message: string;
+}
+/**
+ * A single diagnostic message in structured JSON format.
+ *
+ * Severity encoding:
+ * - `2` → error   (corresponds to `isErrorSeverity() === true`)
+ * - `1` → warning
+ *
+ * Named constants (`JSON_SEVERITY_ERROR`, `JSON_SEVERITY_WARNING`) live in
+ * `json-reporter.ts` to avoid exposing implementation details in the public type.
+ */
+interface DiagnosticMessage {
+    readonly ruleId: string;
+    readonly severity: 1 | 2;
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+}
+/**
+ * Per-file group of diagnostic messages.
+ *
+ * Produced by `JsonReporter` to allow downstream tooling (e.g. reviewdog,
+ * other formatters) to consume ngcompass output without coupling to its
+ * internal `RuleResult` shape.
+ */
+interface FileDiagnosticResult {
+    readonly filePath: string;
+    readonly messages: readonly DiagnosticMessage[];
+    readonly errorCount: number;
+    readonly warningCount: number;
+}
+/**
+ * Reporter contract for cache-related commands (`compass cache`).
+ */
+interface CacheReporter {
+    /**
+     * Renders the clear cache result.
+     * @param type - The type of cache cleared (ast, config, results, all).
+     */
+    renderClearResult(type: 'ast' | 'config' | 'results' | 'all'): void;
+    /**
+     * Renders cache statistics and information.
+     * @param info - The cache information object.
+     */
+    renderCacheInfo(info: CacheInfo): void;
+}
+
+interface RulesReporterOptions {
+    preset?: string;
+}
+declare class RulesReporter {
+    private readonly options;
+    constructor(options?: RulesReporterOptions);
+    render(entries: RuleListEntry[]): void;
+    renderSingleRule(rule: RuleListEntry): void;
+}
+
+declare function getReporter(format?: ReporterFormat, options?: ConsoleReporterOptions): Reporter;
+declare function getConfigReporter(): ConfigReporter;
+declare function getCacheReporter(): CacheReporter;
+declare function getRulesReporter(options?: RulesReporterOptions): RulesReporter;
+
+/**
+ * Core output abstraction used by every reporter.
+ *
+ * Why this interface exists:
+ * - Decouples reporters from Node.js `process` globals.
+ * - Enables deterministic unit tests via in-memory implementations.
+ * - Opens the door to future output targets (files, network, IDE protocol).
+ *
+ * Contract:
+ * - `write`  → standard output (stdout in the default implementation).
+ * - `error`  → diagnostic / error output (stderr in the default implementation).
+ * - Neither method should throw under normal operation.
+ */
+interface ReporterOutput {
+    write(line: string): void;
+    error(line: string): void;
+}
+/**
+ * Process-backed output singleton, wired to `process.stdout` / `process.stderr`.
+ *
+ * Why a singleton constant instead of a factory function:
+ * - Reporters are created once per analysis run; a singleton avoids repeated
+ *   allocation with identical behaviour.
+ * - Makes the default explicit at call-sites without verbosity.
+ *
+ * Do NOT use in tests — use `createTestOutput()` for hermetic assertions.
+ */
+declare const processOutput: ReporterOutput;
+/**
+ * Captured output produced by a reporter under test.
+ *
+ * `lines`  — every call to `output.write()`
+ * `errors` — every call to `output.error()`
+ *
+ * Arrays are live references; assertions can be made at any point after writes.
+ */
+interface TestOutput {
+    readonly output: ReporterOutput;
+    readonly lines: readonly string[];
+    readonly errors: readonly string[];
+}
+/**
+ * Creates an in-memory output capture for use in unit tests.
+ *
+ * Usage:
+ * ```typescript
+ * const out = createTestOutput();
+ * const reporter = new ConsoleReporter(out.output);
+ * reporter.report(results);
+ * expect(out.lines).toContain('...');
+ * ```
+ *
+ * Call `createTestOutput()` in `beforeEach` to get a fresh capture per test,
+ * preventing cross-test pollution.
+ */
+declare function createTestOutput(): TestOutput;
+
+/**
+ * Abstraction over file-system source reading.
+ *
+ * Providing this interface allows callers (reporters) to inject a test double
+ * without touching the module-level cache, keeping each test hermetic and
+ * avoiding real filesystem access during unit tests.
+ */
+interface SourceReader {
+    readLines(filePath: string): string[];
+}
+/**
+ * Reads a source file and splits it into lines.
+ *
+ * Returns an empty array when the file cannot be read (permissions, not found, etc.).
+ * Results are cached for the lifetime of the process (see `sourceCache`).
+ *
+ * @param filePath - Absolute path to the source file.
+ * @returns The file split into lines, or an empty array on read failure.
+ */
+declare function readSourceLines(filePath: string): string[];
+/** Clears the in-memory source cache. Call in `beforeEach` for hermetic tests. */
+declare function clearSourceCache(): void;
+/**
+ * Default SourceReader backed by the process-lifetime filesystem cache.
+ * Inject a different implementation in tests to avoid real filesystem access.
+ */
+declare const defaultSourceReader: SourceReader;
+/**
+ * Renders a code frame for a single violation using @babel/code-frame.
+ *
+ * @param lines        - All source lines for the file (from `readSourceLines`).
+ * @param targetLine   - 1-indexed line number of the violation.
+ * @param _targetColumn - 1-indexed column number of the violation (ignored for full-line highlight).
+ * @param filePath      - Optional path to determine language highlighting.
+ * @returns Coloured frame strings ready to be written to the output.
+ */
+declare function renderCodeFrame(lines: string[], targetLine: number, _targetColumn: number, filePath?: string): string[];
+
+declare class TextConfigReporter implements ConfigReporter {
+    private readonly out;
+    constructor(out?: ReporterOutput);
+    /**
+     * Renders configuration validation errors.
+     * Only produces output when the config is invalid; succeeds silently.
+     *
+     * @param report - The validation result from the config loader.
+     */
+    reportConfig(report: ConfigReport): void;
+    /**
+     * Renders the outcome of `compass init`.
+     *
+     * @param result - The init operation result (success, already-exists, or failure).
+     */
+    renderInitResult(result: InitResult): void;
+    /**
+     * Renders the full project health report.
+     *
+     * @param report - Aggregated health issues, one per config concern.
+     */
+    renderHealthReport(report: HealthReport): void;
+    private renderIssues;
+    private renderSummary;
+}
+
+declare class TextCacheReporter implements CacheReporter {
+    renderClearResult(type: 'ast' | 'config' | 'results' | 'all'): void;
+    renderCacheInfo(info: CacheInfo): void;
+    private printInfoRow;
+    private formatSize;
+}
+
+declare class ConsoleReporter implements Reporter {
+    private readonly out;
+    private readonly compact;
+    private readonly quiet;
+    private readonly noRecommendation;
+    private readonly sourceReader;
+    private readonly cwd;
+    private lastSummary?;
+    constructor(out?: ReporterOutput, options?: ConsoleReporterOptions, 
+    /**
+     * Injected source reader — override in tests to avoid real filesystem access.
+     * Defaults to the process-lifetime fs cache provided by code-frame.ts.
+     */
+    sourceReader?: SourceReader, 
+    /**
+     * Working directory used to compute relative file paths in the output.
+     * Injected (rather than read via `process.cwd()` at call-time) to keep
+     * the reporter deterministic and hermetically testable without patching globals.
+     *
+     * @default process.cwd() — evaluated once at construction, not per-render.
+     */
+    cwd?: string);
+    /**
+     * Renders all rule results to the output.
+     *
+     * @param results - May be empty; a "no violations" message is emitted in that case.
+     */
+    report(results: ReadonlyArray<RuleResult>): void;
+    summary(stats: ResultSummary): void;
+    error(error: Error): void;
+    step(message: string): void;
+    info(message: string): void;
+    clearLine(): void;
+    /**
+     * No-op: debug logging is not handled by the reporter.
+     */
+    debug(_message: string): void;
+    /**
+     * Surfaces parse failures. No-ops gracefully on an empty array.
+     *
+     * @param errors - Files that could not be parsed during analysis.
+     */
+    parseErrors(errors: ReadonlyArray<ParseError>): void;
+    /** Flattens results into a single typed failure list (no narrowing needed later). */
+    private extractAllFailures;
+    /**
+     * Dispatches rendering to either compact or rich mode and appends the
+     * summary divider (rich mode only). Separating dispatch from rendering
+     * satisfies SRP and makes each mode independently testable.
+     *
+     * @param total - Total failure count; threaded through to rich-mode cards
+     *                so each card's indexed separator can display `[X/TOTAL]`.
+     */
+    private renderFileBlocks;
+    private renderCompactBlocks;
+    private renderCompactFileBlock;
+    private renderRichBlocks;
+    /**
+     * Renders all failure cards for a single file.
+     *
+     * Returns the updated global index so the caller can pass it to the next file
+     * without relying on external mutable state.
+     */
+    private renderRichFileBlock;
+    /**
+     * Renders one failure card in the new compact style:
+     *
+     *   ────────────────────────────────────[3/33]─
+     *    ERROR  src\app\violations\rule01.ts:33:5
+     *   × Avoid manual change detection  component-no-manual-detect-changes
+     *
+     *     31 │ this.counter++;
+     *   > 33 │     this.cdr.detectChanges();
+     *                ^^^^^^^^^^^^^^^^^^^^^^
+     *     35 │ }
+     *
+     *   i Add changeDetection: ChangeDetectionStrategy.OnPush
+     *
+     * Layout decisions vs the old design:
+     *   - Indexed separator `[X/TOTAL]` replaces the plain `────` divider and
+     *     the `1  ██ ERROR ██  rule-name` header line — fewer total lines.
+     *   - Badge + filepath:line:col on one line (no separate `--> path` line).
+     *   - Message + rule name on one line (dimmed rule name on the right).
+     *   - Fix text appears immediately after the code frame (no extra blank line
+     *     between frame and fix when fix is absent — card ends cleanly).
+     */
+    private renderRichCard;
+    private renderCardCodeFrame;
+    private renderCardRecommendation;
+}
+
+declare class JsonReporter implements Reporter {
+    private readonly out;
+    private readonly accumulatedResults;
+    private readonly accumulatedParseErrors;
+    constructor(out?: ReporterOutput);
+    report(results: ReadonlyArray<RuleResult>): void;
+    summary(stats: ResultSummary): void;
+    error(err: Error): void;
+    step(_message: string): void;
+    info(_message: string): void;
+    debug(_message: string): void;
+    parseErrors(errors: ReadonlyArray<ParseError>): void;
+}
+
+declare class HtmlReporter implements Reporter {
+    private readonly outputPath;
+    private readonly out;
+    private readonly autoOpen;
+    private readonly accumulatedResults;
+    private readonly accumulatedParseErrors;
+    constructor(outputPath?: string, out?: ReporterOutput, autoOpen?: boolean);
+    report(results: ReadonlyArray<RuleResult>): void;
+    parseErrors(errors: ReadonlyArray<ParseError>): void;
+    error(error: Error): void;
+    summary(stats: ResultSummary): void;
+    step(_message: string): void;
+    info(_message: string): void;
+    debug(_message: string): void;
+}
+
+declare class SarifReporter implements Reporter {
+    private readonly out;
+    private readonly parseErrorBuffer;
+    private readonly resultBuffer;
+    constructor(out?: ReporterOutput);
+    report(results: ReadonlyArray<RuleResult>): void;
+    parseErrors(errors: ReadonlyArray<ParseError>): void;
+    error(error: Error): void;
+    summary(stats: ResultSummary): void;
+    step(_message: string): void;
+    info(_message: string): void;
+    debug(_message: string): void;
+}
+
+export { type AnalysisReporter, type CacheReporter, type ConfigReporter, ConsoleReporter, type ConsoleReporterOptions, type DiagnosticMessage, type FileDiagnosticResult, HtmlReporter, JsonReporter, type ParseError, type ProgressReporter, type Reporter, type ReporterFormat, type ReporterOutput, type ResultSummary, RulesReporter, type RulesReporterOptions, SarifReporter, type SourceReader, type TestOutput, TextCacheReporter, TextConfigReporter, clearSourceCache, createTestOutput, defaultSourceReader, getCacheReporter, getConfigReporter, getReporter, getRulesReporter, processOutput, readSourceLines, renderCodeFrame };