@opensip-tools/fitness 1.0.4

package/dist/framework/ignore-processing.js

@@ -0,0 +1,241 @@
+// @fitness-ignore-file batch-operation-limits -- iterates bounded collections (config entries, registry items, or small analysis results)
+// @fitness-ignore-file concurrency-safety -- Single-threaded Node.js; Map-based caches are safe without synchronization
+/**
+ * @fileoverview Ignore directive processing for fitness checks
+ *
+ * Filters signals based on file-level and line-level ignore directives.
+ * Signals pointing at lines that contain @fitness-ignore directives are
+ * never suppressed — this prevents recursive suppression loops where
+ * directive-auditing checks would otherwise flag their own suppressions.
+ */
+import { logger } from '@opensip-tools/core';
+import { countErrors, countWarnings } from '../types/severity.js';
+import { extractGroup, isWeakReason, parseDirectiveLine } from './directive-inventory.js';
+import { parseFileIgnoreDirective, parseIgnoreDirectives } from './directive-parsing.js';
+import { fileCache } from './file-cache.js';
+// =============================================================================
+// DIRECTIVE LINE DETECTION
+// =============================================================================
+/**
+ * Scan file content and return the set of 1-based line numbers that contain
+ * @fitness-ignore directives. These lines are framework infrastructure and
+ * must never be suppressed by other directives (prevents recursive loops).
+ */
+function findDirectiveLines(content) {
+    const directiveLines = new Set();
+    const lines = content.split('\n');
+    for (const [i, line] of lines.entries()) {
+        const trimmed = (line ?? '').trimStart();
+        if ((trimmed.startsWith('//') || trimmed.startsWith('/*')) &&
+            trimmed.includes('@fitness-ignore')) {
+            directiveLines.add(i + 1);
+        }
+    }
+    return directiveLines;
+}
+/**
+ * Processes file ignore status and caches the result.
+ */
+async function processFileIgnoreStatus(filePath, checkId, fileIgnoreCache, lineIgnoreCache, directiveLineCache) {
+    // in-memory: single-threaded Node.js access pattern
+    const fileIgnored = fileIgnoreCache.get(filePath);
+    if (fileIgnored !== undefined) {
+        return {
+            fileIgnored,
+            ignoredLines: lineIgnoreCache.get(filePath) ?? null,
+            directiveLines: directiveLineCache?.get(filePath) ?? new Set(),
+        };
+    }
+    try {
+        const content = await fileCache.get(filePath);
+        const isIgnored = parseFileIgnoreDirective(content, checkId);
+        fileIgnoreCache.set(filePath, isIgnored);
+        // Always scan for directive lines (needed for recursive loop prevention)
+        const dirLines = findDirectiveLines(content);
+        directiveLineCache?.set(filePath, dirLines);
+        let ignoredLines = null;
+        if (!isIgnored) {
+            ignoredLines = parseIgnoreDirectives(content, checkId);
+            lineIgnoreCache.set(filePath, ignoredLines);
+        }
+        return { fileIgnored: isIgnored, ignoredLines, directiveLines: dirLines };
+    }
+    catch (error) {
+        logger.warn('fitness.ignore.file_read.failed', { evt: 'fitness.ignore.file_read.failed', module: 'fitness:ignore-processing', filePath, err: error });
+        fileIgnoreCache.set(filePath, false);
+        return { fileIgnored: false, ignoredLines: null, directiveLines: new Set() };
+    }
+}
+function classifySignals(signals, initialIgnoredCount, fileIgnoreCache, lineIgnoreCache, directiveLineCache) {
+    const filteredSignals = [];
+    let ignoredCount = initialIgnoredCount;
+    const appliedFileIgnores = new Set();
+    const appliedLineIgnores = new Map();
+    for (const signal of signals) {
+        if (!isSignalIgnored(signal, fileIgnoreCache, lineIgnoreCache, directiveLineCache)) {
+            filteredSignals.push(signal);
+            continue;
+        }
+        ignoredCount++;
+        const filePath = signal.code?.file;
+        if (!filePath)
+            continue;
+        if (fileIgnoreCache.get(filePath)) {
+            appliedFileIgnores.add(filePath);
+        }
+        else {
+            const line = signal.code?.line;
+            if (line) {
+                let lineSet = appliedLineIgnores.get(filePath);
+                if (!lineSet) {
+                    lineSet = new Set();
+                    appliedLineIgnores.set(filePath, lineSet);
+                }
+                lineSet.add(line);
+            }
+        }
+    }
+    return { filteredSignals, ignoredCount, appliedFileIgnores, appliedLineIgnores };
+}
+/** Filter signals based on file-level and line-level @fitness-ignore directives */
+export async function filterSignalsByDirectives(signals, checkId, initialIgnoredCount) {
+    const fileIgnoreCache = new Map();
+    const lineIgnoreCache = new Map();
+    const directiveLineCache = new Map();
+    // Pre-populate file ignore status for all unique file paths in parallel
+    const uniqueFiles = new Set();
+    for (const signal of signals) {
+        const filePath = signal.code?.file;
+        if (filePath)
+            uniqueFiles.add(filePath);
+    }
+    await Promise.all([...uniqueFiles].map((filePath) => processFileIgnoreStatus(filePath, checkId, fileIgnoreCache, lineIgnoreCache, directiveLineCache)));
+    const { filteredSignals, ignoredCount, appliedFileIgnores, appliedLineIgnores } = classifySignals(signals, initialIgnoredCount, fileIgnoreCache, lineIgnoreCache, directiveLineCache);
+    const appliedDirectives = await collectAppliedDirectives(checkId, appliedFileIgnores, appliedLineIgnores);
+    return { filteredSignals, ignoredCount, appliedDirectives };
+}
+/**
+ * Determines whether a single signal should be ignored based on cached directive data.
+ *
+ * File-level ignores always apply (the entire file is suppressed).
+ * Line-level ignores apply unless the signal points at a directive line itself
+ * (prevents recursive loops where directive-auditing checks suppress their own findings).
+ */
+function isSignalIgnored(signal, fileIgnoreCache, lineIgnoreCache, directiveLineCache) {
+    const filePath = signal.code?.file;
+    if (!filePath)
+        return false;
+    // File-level ignores always apply — no anti-recursion needed
+    if (fileIgnoreCache.get(filePath))
+        return true;
+    const signalLine = signal.code?.line;
+    const dirLines = directiveLineCache.get(filePath);
+    // For line-level ignores: never suppress signals pointing at directive lines (anti-recursion)
+    if (signalLine && dirLines?.has(signalLine))
+        return false;
+    const ignoredLines = lineIgnoreCache.get(filePath);
+    if (signalLine && ignoredLines?.has(signalLine))
+        return true;
+    return false;
+}
+// =============================================================================
+// APPLIED DIRECTIVE COLLECTION
+// =============================================================================
+function toDirectiveEntry(filePath, lineNumber, parsed) {
+    return {
+        filePath,
+        lineNumber,
+        type: parsed.type,
+        checkId: parsed.checkId,
+        group: extractGroup(parsed.checkId),
+        reason: parsed.reason,
+        weakReason: isWeakReason(parsed.reason),
+    };
+}
+async function collectFileIgnoreDirectives(checkId, appliedFileIgnores) {
+    const results = await Promise.all([...appliedFileIgnores].map(async (filePath) => {
+        try {
+            const content = await fileCache.get(filePath);
+            const lines = content.split('\n');
+            for (let i = 0; i < Math.min(lines.length, 50); i++) {
+                const parsed = parseDirectiveLine(lines[i] ?? '');
+                if (parsed?.type === 'file' && parsed.checkId === checkId) {
+                    return toDirectiveEntry(filePath, i + 1, parsed);
+                }
+            }
+        }
+        catch (error) {
+            logger.warn('fitness.ignore.directive_read.failed', { evt: 'fitness.ignore.directive_read.failed', module: 'fitness:ignore-processing', err: error });
+        }
+        return null;
+    }));
+    return results.filter((d) => d !== null);
+}
+async function collectLineIgnoreDirectives(checkId, appliedLineIgnores) {
+    const results = await Promise.all([...appliedLineIgnores.entries()].map(async ([filePath, suppressedLines]) => {
+        const found = [];
+        try {
+            const content = await fileCache.get(filePath);
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const parsed = parseDirectiveLine(lines[i] ?? '');
+                if (parsed?.type !== 'next-line' || parsed.checkId !== checkId)
+                    continue;
+                let targetLine = i + 1;
+                while (targetLine < lines.length && (lines[targetLine] ?? '').trimStart().startsWith('//')) {
+                    targetLine++;
+                }
+                if (suppressedLines.has(targetLine + 1)) {
+                    found.push(toDirectiveEntry(filePath, i + 1, parsed));
+                }
+            }
+        }
+        catch (error) {
+            logger.warn('fitness.ignore.directive_read.failed', { evt: 'fitness.ignore.directive_read.failed', module: 'fitness:ignore-processing', err: error });
+        }
+        return found;
+    }));
+    const directives = [];
+    for (const batch of results) {
+        for (const d of batch) {
+            directives.push(d);
+        }
+    }
+    return directives;
+}
+async function collectAppliedDirectives(checkId, appliedFileIgnores, appliedLineIgnores) {
+    const [fileDirectives, lineDirectives] = await Promise.all([
+        collectFileIgnoreDirectives(checkId, appliedFileIgnores),
+        collectLineIgnoreDirectives(checkId, appliedLineIgnores),
+    ]);
+    return [...fileDirectives, ...lineDirectives];
+}
+// =============================================================================
+// RESULT BUILDING
+// =============================================================================
+/**
+ * Builds the filtered result from the original result and filtered signals.
+ */
+export function buildFilteredResult(result, filteredSignals, ignoredCount, start) {
+    if (!Array.isArray(filteredSignals)) {
+        return result;
+    }
+    const durationMs = result.metadata.durationMs ?? Date.now() - start;
+    const filteredErrors = countErrors(filteredSignals);
+    const filteredWarnings = countWarnings(filteredSignals);
+    const filteredResult = {
+        ...result,
+        passed: filteredErrors === 0,
+        errors: filteredErrors,
+        warnings: filteredWarnings,
+        signals: filteredSignals,
+        metadata: {
+            ...result.metadata,
+            durationMs,
+            signals: filteredSignals,
+        },
+        ...(ignoredCount > 0 ? { ignoredCount } : {}),
+    };
+    return filteredResult;
+}
+//# sourceMappingURL=ignore-processing.js.map

package/dist/framework/ignore-processing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore-processing.js","sourceRoot":"","sources":["../../src/framework/ignore-processing.ts"],"names":[],"mappings":"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"}

package/dist/framework/import-graph.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Project-wide import graph builder.
+ *
+ * Builds a file-level dependency graph from a set of TypeScript/JavaScript
+ * source files, plus a Tarjan's strongly-connected-components implementation
+ * for cycle detection. Used by structural-drift checks like
+ * circular-import-detection and module-coupling-fan-out.
+ *
+ * Module resolution is deliberately a heuristic: relative imports are
+ * resolved by trying common extension/index.ts suffixes; bare specifiers
+ * (npm packages) are dropped; tsconfig path aliases are NOT resolved
+ * (treated as unresolved — they simply don't appear as edges in the graph).
+ *
+ * This matches the heuristic the existing `phantom-dependency-detection`
+ * check uses, which has been shipping reliably. Adding tsconfig-aware
+ * resolution is a follow-up plan.
+ */
+/** A file-level import graph for a project. */
+export interface ImportGraph {
+    /** All node file paths (absolute, as supplied by the caller). */
+    readonly nodes: ReadonlySet<string>;
+    /** Adjacency: file → set of files it imports (intra-project edges only). */
+    readonly outbound: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Reverse adjacency: file → set of files that import it. */
+    readonly inbound: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/**
+ * Build an import graph from a collection of file paths and their content.
+ *
+ * Each file's TS AST is walked for top-level `import` and `export ... from`
+ * declarations. Relative specifiers (`./foo`, `../bar/baz.js`) are resolved
+ * against the importing file's directory using the heuristic in
+ * `resolveRelativeSpecifier`. Bare specifiers (`react`, `lodash`) are
+ * dropped — they don't represent intra-project edges.
+ *
+ * Files that fail to parse are still added as nodes (with no edges) so the
+ * graph remains complete.
+ */
+export declare function buildImportGraph(files: ReadonlyMap<string, string>): ImportGraph;
+/**
+ * Find strongly-connected components in the graph using Tarjan's algorithm.
+ *
+ * Returns an array of SCCs, each represented as an array of node names. SCCs
+ * of size 1 represent a node with no cycle (or a self-loop, which is rare in
+ * import graphs). Cycle-detection callers typically filter to `scc.length > 1`
+ * to get only real multi-file cycles.
+ *
+ * Algorithm: standard iterative Tarjan's SCC. O(V + E), single pass.
+ */
+export declare function findStronglyConnectedComponents(graph: ImportGraph): readonly (readonly string[])[];
+//# sourceMappingURL=import-graph.d.ts.map

package/dist/framework/import-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-graph.d.ts","sourceRoot":"","sources":["../../src/framework/import-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;IAC3D,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAA;CAC3D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAwBhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,WAAW,GACjB,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAiGhC"}

package/dist/framework/import-graph.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Project-wide import graph builder.
+ *
+ * Builds a file-level dependency graph from a set of TypeScript/JavaScript
+ * source files, plus a Tarjan's strongly-connected-components implementation
+ * for cycle detection. Used by structural-drift checks like
+ * circular-import-detection and module-coupling-fan-out.
+ *
+ * Module resolution is deliberately a heuristic: relative imports are
+ * resolved by trying common extension/index.ts suffixes; bare specifiers
+ * (npm packages) are dropped; tsconfig path aliases are NOT resolved
+ * (treated as unresolved — they simply don't appear as edges in the graph).
+ *
+ * This matches the heuristic the existing `phantom-dependency-detection`
+ * check uses, which has been shipping reliably. Adding tsconfig-aware
+ * resolution is a follow-up plan.
+ */
+import * as path from 'node:path';
+import ts from 'typescript';
+import { getSharedSourceFile } from './parse-cache.js';
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Build an import graph from a collection of file paths and their content.
+ *
+ * Each file's TS AST is walked for top-level `import` and `export ... from`
+ * declarations. Relative specifiers (`./foo`, `../bar/baz.js`) are resolved
+ * against the importing file's directory using the heuristic in
+ * `resolveRelativeSpecifier`. Bare specifiers (`react`, `lodash`) are
+ * dropped — they don't represent intra-project edges.
+ *
+ * Files that fail to parse are still added as nodes (with no edges) so the
+ * graph remains complete.
+ */
+export function buildImportGraph(files) {
+    const nodes = new Set(files.keys());
+    const outbound = new Map();
+    const inbound = new Map();
+    // Initialize empty edge sets for every node so callers can safely
+    // outbound.get(file) without checking for undefined.
+    for (const node of nodes) {
+        outbound.set(node, new Set());
+        inbound.set(node, new Set());
+    }
+    for (const [filePath, content] of files) {
+        const specifiers = extractImportSpecifiers(filePath, content);
+        for (const spec of specifiers) {
+            const resolved = resolveRelativeSpecifier(filePath, spec, nodes);
+            if (resolved !== null) {
+                outbound.get(filePath).add(resolved);
+                inbound.get(resolved).add(filePath);
+            }
+        }
+    }
+    return { nodes, outbound, inbound };
+}
+/**
+ * Find strongly-connected components in the graph using Tarjan's algorithm.
+ *
+ * Returns an array of SCCs, each represented as an array of node names. SCCs
+ * of size 1 represent a node with no cycle (or a self-loop, which is rare in
+ * import graphs). Cycle-detection callers typically filter to `scc.length > 1`
+ * to get only real multi-file cycles.
+ *
+ * Algorithm: standard iterative Tarjan's SCC. O(V + E), single pass.
+ */
+export function findStronglyConnectedComponents(graph) {
+    const indexOf = new Map();
+    const lowlinkOf = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let nextIndex = 0;
+    // eslint-disable-next-line sonarjs/cognitive-complexity -- iterative Tarjan SCC: explicit stack to avoid recursion; the algorithm is canonical and reads cleanest as a single function
+    function strongConnect(start) {
+        const callStack = [];
+        indexOf.set(start, nextIndex);
+        lowlinkOf.set(start, nextIndex);
+        nextIndex++;
+        stack.push(start);
+        onStack.add(start);
+        callStack.push({
+            node: start,
+            neighbors: [...(graph.outbound.get(start) ?? [])],
+            next: 0,
+        });
+        while (callStack.length > 0) {
+            const frame = callStack.at(-1);
+            if (frame.next < frame.neighbors.length) {
+                const w = frame.neighbors[frame.next];
+                frame.next++;
+                if (!indexOf.has(w)) {
+                    // Recurse into w.
+                    indexOf.set(w, nextIndex);
+                    lowlinkOf.set(w, nextIndex);
+                    nextIndex++;
+                    stack.push(w);
+                    onStack.add(w);
+                    callStack.push({
+                        node: w,
+                        neighbors: [...(graph.outbound.get(w) ?? [])],
+                        next: 0,
+                    });
+                    continue;
+                }
+                if (onStack.has(w)) {
+                    // Back edge — update v's lowlink.
+                    const vLow = lowlinkOf.get(frame.node);
+                    const wIdx = indexOf.get(w);
+                    if (wIdx < vLow)
+                        lowlinkOf.set(frame.node, wIdx);
+                }
+                continue;
+            }
+            // All neighbors processed — finalize this node.
+            const v = frame.node;
+            const vLow = lowlinkOf.get(v);
+            const vIdx = indexOf.get(v);
+            if (vLow === vIdx) {
+                // v is the root of an SCC — pop until v is removed.
+                const scc = [];
+                let w;
+                do {
+                    w = stack.pop();
+                    onStack.delete(w);
+                    scc.push(w);
+                } while (w !== v);
+                sccs.push(scc);
+            }
+            callStack.pop();
+            // Propagate lowlink up to the parent frame.
+            if (callStack.length > 0) {
+                const parent = callStack.at(-1);
+                const parentLow = lowlinkOf.get(parent.node);
+                if (vLow < parentLow)
+                    lowlinkOf.set(parent.node, vLow);
+            }
+        }
+    }
+    for (const node of graph.nodes) {
+        if (!indexOf.has(node)) {
+            strongConnect(node);
+        }
+    }
+    return sccs;
+}
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+/** Walk the AST and collect top-level import / export-from specifiers. */
+function extractImportSpecifiers(filePath, content) {
+    const sourceFile = getSharedSourceFile(filePath, content);
+    if (sourceFile === null)
+        return [];
+    const specifiers = [];
+    for (const stmt of sourceFile.statements) {
+        // import foo from './bar';  import './side-effect';  import * as ns from './m';
+        if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier)) {
+            specifiers.push(stmt.moduleSpecifier.text);
+            continue;
+        }
+        // export * from './foo';   export { x } from './foo';
+        if (ts.isExportDeclaration(stmt) &&
+            stmt.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(stmt.moduleSpecifier)) {
+            specifiers.push(stmt.moduleSpecifier.text);
+        }
+    }
+    return specifiers;
+}
+/**
+ * Resolve a module specifier to an actual file path in the project, or
+ * return null if the specifier is non-relative (npm package, path alias) or
+ * doesn't resolve to a known project file.
+ *
+ * Supports:
+ *   - `./foo` → `<dir>/foo.ts`, `.tsx`, `/index.ts`, `/index.tsx`
+ *   - `./foo.js` → `<dir>/foo.ts` (ESM extension swap, common in TS+ESM)
+ *   - `./foo.ts` → `<dir>/foo.ts` (literal)
+ *   - `../bar/baz` → resolved relative to importer's directory
+ *
+ * Does NOT support:
+ *   - tsconfig `paths` aliases (deferred per plan)
+ *   - npm packages (correctly dropped — out of scope for intra-project graph)
+ */
+function resolveRelativeSpecifier(importerPath, specifier, knownPaths) {
+    // Only relative specifiers participate in the intra-project graph.
+    if (!specifier.startsWith('.'))
+        return null;
+    const importerDir = path.dirname(importerPath);
+    const base = path.resolve(importerDir, specifier);
+    // Try the candidate paths in priority order. The first one that exists in
+    // the project's file set wins.
+    const candidates = [base];
+    // 1. Literal path (specifier already includes extension).
+    // 2. ESM extension swap: `.js` → `.ts` / `.tsx` (TypeScript ESM convention).
+    if (base.endsWith('.js')) {
+        candidates.push(base.slice(0, -3) + '.ts', base.slice(0, -3) + '.tsx');
+    }
+    if (base.endsWith('.jsx')) {
+        candidates.push(base.slice(0, -4) + '.tsx');
+    }
+    // 3. Append common extensions if the specifier was extension-less.
+    const hasExt = path.extname(base) !== '';
+    if (!hasExt) {
+        // Direct extensions and index resolution.
+        candidates.push(base + '.ts', base + '.tsx', base + '.js', base + '.jsx', path.join(base, 'index.ts'), path.join(base, 'index.tsx'), path.join(base, 'index.js'), path.join(base, 'index.jsx'));
+    }
+    for (const candidate of candidates) {
+        if (knownPaths.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+//# sourceMappingURL=import-graph.js.map

package/dist/framework/import-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-graph.js","sourceRoot":"","sources":["../../src/framework/import-graph.ts"],"names":[],"mappings":"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"}

package/dist/framework/memory-profiler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Memory profiler for fitness checks
+ *
+ * Always-on, low-overhead memory tracking for check execution.
+ * Collects per-check profiles for trending analysis.
+ */
+/** Memory usage profile recorded for a single check execution */
+export interface CheckMemoryProfile {
+    readonly checkId: string;
+    readonly memoryBeforeMB: number;
+    readonly memoryAfterMB: number;
+    readonly memoryDeltaMB: number;
+    readonly violationCount: number;
+    readonly durationMs: number;
+}
+/** Aggregated memory profiling summary across all check executions */
+interface MemoryProfileSummary {
+    readonly prewarmMemoryMB: number;
+    readonly peakMemoryMB: number;
+    readonly checksExceedingThreshold: number;
+    readonly topConsumers: readonly CheckMemoryProfile[];
+    readonly allProfiles: readonly CheckMemoryProfile[];
+}
+/** Low-overhead memory profiler that tracks per-check heap usage during fitness runs */
+declare class MemoryProfiler {
+    private readonly profiles;
+    private prewarmMemoryMB;
+    private peakMemoryMB;
+    private readonly warningThresholdMB;
+    constructor(warningThresholdMB?: number);
+    private takeSnapshot;
+    private bytesToMB;
+    /** Record memory baseline after cache prewarm completes */
+    recordPrewarmComplete(): void;
+    /** Return current heap usage in megabytes */
+    getCurrentMemoryMB(): number;
+    /** Record memory before a check starts; returns the pre-check heap in MB */
+    recordCheckStart(): number;
+    /** Record memory after a check completes and return the check's memory profile */
+    recordCheckComplete(checkId: string, memoryBeforeMB: number, violationCount: number, durationMs: number): CheckMemoryProfile;
+    /** Check whether a memory delta exceeds the configured warning threshold */
+    exceedsThreshold(deltaMB: number): boolean;
+    /** Return the configured warning threshold in megabytes */
+    getWarningThresholdMB(): number;
+    /** Build and return an aggregated summary of all recorded check profiles */
+    getSummary(): MemoryProfileSummary;
+    /** Reset all recorded profiles and counters */
+    reset(): void;
+}
+/** Shared singleton memory profiler instance used across fitness check runs */
+export declare const memoryProfiler: MemoryProfiler;
+export {};
+//# sourceMappingURL=memory-profiler.d.ts.map

package/dist/framework/memory-profiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-profiler.d.ts","sourceRoot":"","sources":["../../src/framework/memory-profiler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,sEAAsE;AACtE,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAA;IACzC,QAAQ,CAAC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACpD,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACpD;AAID,wFAAwF;AACxF,cAAM,cAAc;IAClB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;gBAE/B,kBAAkB,SAAsC;IAIpE,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,SAAS;IAIjB,2DAA2D;IAC3D,qBAAqB,IAAI,IAAI;IAM7B,6CAA6C;IAC7C,kBAAkB,IAAI,MAAM;IAK5B,4EAA4E;IAC5E,gBAAgB,IAAI,MAAM;IAI1B,kFAAkF;IAClF,mBAAmB,CACjB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GACjB,kBAAkB;IAqBrB,4EAA4E;IAC5E,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI1C,2DAA2D;IAC3D,qBAAqB,IAAI,MAAM;IAI/B,4EAA4E;IAC5E,UAAU,IAAI,oBAAoB;IAgBlC,+CAA+C;IAC/C,KAAK,IAAI,IAAI;CAKd;AAED,+EAA+E;AAC/E,eAAO,MAAM,cAAc,gBAAuB,CAAA"}