arkanalyzer 1.0.93 → 2.0.0-beta1

package/lib/statistics/StageStatistics.js

@@ -0,0 +1,346 @@
+"use strict";
+/*
+ * Copyright (c) 2024-2026 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StageStatistics = exports.StageName = void 0;
+const SignatureCanonicalizerRegistry_1 = require("../core/common/SignatureCanonicalizerRegistry");
+/**
+ * Stage Statistics Module
+ *
+ * Collects time and memory metrics for execution stages (e.g. builder, inferTypes).
+ * Designed as a generic, stage-name-agnostic collector so that future modules
+ * (CG, PTA, etc.) can plug in via `startStage(name)` without interface changes.
+ *
+ * Key design points:
+ * - `enabled` switch: every public method early-returns when disabled (zero overhead).
+ * - Named timers via `startStage(name)` / `endStage(name)`; repeated names auto-suffix
+ *   with `#2`, `#3`, ... so multiple `inferTypes()` calls are distinguished.
+ * - Stage nesting: a stage started while another is still running becomes its child
+ *   (stack top at start time = parent); the report renders children indented.
+ * - Memory peak tracked via synchronous checkpoint sampling at key points
+ *   (`start`, `startStage`, `endStage`, `finish`, and `recordMemoryCheckpoint`).
+ *   No `setInterval` is used — Node.js single-threaded event loop cannot schedule
+ *   timer callbacks during CPU-intensive synchronous operations (AST parsing, IR
+ *   construction, type inference), making interval-based sampling unreliable.
+ * - `customCounters` Map for extensible, module-specific counters.
+ * - `recordSignatureStats(label)`: signature-space snapshots (formal canonicalizer
+ *   sizes + temp index-table stats) at checkpoints like post-build / post-infer.
+ */
+/**
+ * Built-in stage names used by ArkAnalyzer's core pipeline.
+ *
+ * `startStage` / `endStage` accept any `string`, so external modules and
+ * future stages (e.g. CG, PTA) can pass their own names or extend this enum.
+ * Using the enum provides compile-time safety and IDE autocompletion for
+ * well-known stages, while the string overload keeps the interface open.
+ *
+ * Hierarchy: a stage started while another stage is still running becomes its
+ * child (nesting is captured automatically; the report renders indentation).
+ */
+var StageName;
+(function (StageName) {
+    /** 构建总阶段（Scene 构建入口整体，含其下全部细分阶段）。 */
+    StageName["Builder"] = "builder";
+    /** 细分：构建期配置解析（build-profile / oh-package / tsconfig，SceneBuilder.parseProjectConfigs）。 */
+    StageName["BuilderParseConfigs"] = "builderParseConfigs";
+    /** 细分：SDK 构建与推断阶段（SceneBuilder.buildSdkStage）。 */
+    StageName["BuilderSdk"] = "builderSdk";
+    /** 细分（BuilderSdk 子阶段）：SDK 源文件注册构建（buildSdk 逐文件解析注册）。 */
+    StageName["BuilderSdkFiles"] = "builderSdkFiles";
+    /** 细分（BuilderSdk 子阶段）：SDK 类型推导与 global API 合并（doInfer + mergeGlobalAPI + postInferredSdk）。 */
+    StageName["BuilderSdkInfer"] = "builderSdkInfer";
+    /** 细分：project 文件 DFS 构建（SceneBuilder.buildProjectFiles）。 */
+    StageName["BuilderFiles"] = "builderFiles";
+    /** 细分：方法体构建（SceneBuilder.buildAllMethodBodies）。 */
+    StageName["BuilderBodies"] = "builderBodies";
+    /** 推断单轮（inferTypes 的每轮遍历，多轮自动 #2/#3 后缀）。 */
+    StageName["InferTypes"] = "inferTypes";
+    /** 推断收尾（buildStage 推进 + temp 完整性检查 + validate + 各 dispose）。 */
+    StageName["InferTypesFinalize"] = "inferTypesFinalize";
+})(StageName = exports.StageName || (exports.StageName = {}));
+function emptySnapshot() {
+    return { rssMB: 0, heapUsedMB: 0, heapTotalMB: 0 };
+}
+function captureMemory() {
+    const m = process.memoryUsage();
+    return {
+        rssMB: m.rss / 1024 / 1024,
+        heapUsedMB: m.heapUsed / 1024 / 1024,
+        heapTotalMB: m.heapTotal / 1024 / 1024,
+    };
+}
+function maxSnapshot(a, b) {
+    return {
+        rssMB: Math.max(a.rssMB, b.rssMB),
+        heapUsedMB: Math.max(a.heapUsedMB, b.heapUsedMB),
+        heapTotalMB: Math.max(a.heapTotalMB, b.heapTotalMB),
+    };
+}
+class StageStatistics {
+    constructor(enabled = false) {
+        this.runningStages = new Map();
+        this.stageNameCounts = new Map();
+        this.completedStages = [];
+        this.customCounters = new Map();
+        this.signatureSnapshots = [];
+        this.enabled = enabled;
+        this.startTime = 0;
+        this.endTime = 0;
+        this.globalSampledPeak = emptySnapshot();
+        this.globalMemBefore = emptySnapshot();
+        this.globalMemAfter = emptySnapshot();
+        this.finished = false;
+    }
+    enable() {
+        this.enabled = true;
+    }
+    disable() {
+        this.enabled = false;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Start global timing and memory sampling.
+     */
+    start() {
+        if (!this.enabled) {
+            return;
+        }
+        this.startTime = Date.now();
+        this.globalMemBefore = captureMemory();
+        this.globalSampledPeak = Object.assign({}, this.globalMemBefore);
+        this.finished = false;
+    }
+    /**
+     * Start a named stage. If the same name has been used before, a suffix `#N` is appended.
+     *
+     * Nesting: the most recently started still-running stage (stack top) becomes
+     * this stage's parent — the report renders children indented under it.
+     */
+    startStage(name) {
+        if (!this.enabled) {
+            return;
+        }
+        const uniqueName = this.resolveUniqueName(name);
+        const memBefore = captureMemory();
+        this.globalSampledPeak = maxSnapshot(this.globalSampledPeak, memBefore);
+        this.runningStages.set(uniqueName, {
+            name: uniqueName,
+            startTime: Date.now(),
+            memBefore,
+            sampledPeak: Object.assign({}, memBefore),
+            parentName: this.currentStackTop(uniqueName),
+        });
+    }
+    /**
+     * End a named stage and record its entry.
+     * Looks up the running stage whose unique name equals `name` or matches the `name#N` pattern.
+     */
+    endStage(name) {
+        if (!this.enabled) {
+            return;
+        }
+        const uniqueName = this.findRunningStageName(name);
+        if (!uniqueName) {
+            return;
+        }
+        const rs = this.runningStages.get(uniqueName);
+        if (!rs) {
+            return;
+        }
+        this.runningStages.delete(uniqueName);
+        const memAfter = captureMemory();
+        this.globalSampledPeak = maxSnapshot(this.globalSampledPeak, memAfter);
+        const memPeak = maxSnapshot(rs.sampledPeak, memAfter);
+        this.completedStages.push({
+            name: uniqueName,
+            parent: rs.parentName,
+            durationMs: Date.now() - rs.startTime,
+            memBefore: rs.memBefore,
+            memPeak,
+            memAfter,
+        });
+    }
+    /**
+     * Record a memory checkpoint inside the current running stage.
+     *
+     * Synchronously captures memory and updates both the global peak and the
+     * current running stage's peak. Use this at fine-grained points within
+     * long-running stages (e.g. inside per-method or per-file loops) to track
+     * memory growth that `startStage`/`endStage` alone would miss.
+     */
+    recordMemoryCheckpoint() {
+        if (!this.enabled) {
+            return;
+        }
+        const cur = captureMemory();
+        this.globalSampledPeak = maxSnapshot(this.globalSampledPeak, cur);
+        for (const rs of this.runningStages.values()) {
+            rs.sampledPeak = maxSnapshot(rs.sampledPeak, cur);
+        }
+    }
+    /**
+     * Finish global timing and records final memory.
+     */
+    finish() {
+        if (!this.enabled || this.finished) {
+            return;
+        }
+        this.runningStages.clear();
+        this.globalMemAfter = captureMemory();
+        this.globalSampledPeak = maxSnapshot(this.globalSampledPeak, this.globalMemAfter);
+        this.endTime = Date.now();
+        this.finished = true;
+    }
+    /**
+     * Increment a custom counter (extensible for future modules).
+     */
+    incrementCustomCounter(name, value = 1) {
+        var _a;
+        if (!this.enabled) {
+            return;
+        }
+        this.customCounters.set(name, ((_a = this.customCounters.get(name)) !== null && _a !== void 0 ? _a : 0) + value);
+    }
+    getCustomCounter(name) {
+        var _a;
+        return (_a = this.customCounters.get(name)) !== null && _a !== void 0 ? _a : 0;
+    }
+    /**
+     * Snapshot the signature-space sizes at a checkpoint (e.g. 'post-build' /
+     * 'post-infer'): formal canonicalizer entry counts per space + temp
+     * index-table stats (live/retired/replaced). Read-only against the registry.
+     */
+    recordSignatureStats(label) {
+        if (!this.enabled) {
+            return;
+        }
+        const reg = SignatureCanonicalizerRegistry_1.SignatureCanonicalizerRegistry.getInstance();
+        this.signatureSnapshots.push({
+            label,
+            formal: {
+                file: reg.fileSigCanonicalizer.size(),
+                class: reg.classSigCanonicalizer.size(),
+                namespace: reg.namespaceSigCanonicalizer.size(),
+                field: reg.fieldSigCanonicalizer.size(),
+                method: reg.methodSigCanonicalizer.size(),
+            },
+            temp: SignatureCanonicalizerRegistry_1.SignatureCanonicalizerRegistry.getInstance().getTempSpacesStats(),
+        });
+    }
+    /**
+     * Get the complete statistics data. Auto-finishes if still running.
+     */
+    getStatistics() {
+        if (this.enabled && !this.finished) {
+            this.finish();
+        }
+        const totalDurationMs = this.startTime > 0 && this.endTime > 0 ? this.endTime - this.startTime : 0;
+        return {
+            stages: this.completedStages.map(s => (Object.assign({}, s))),
+            totalDurationMs,
+            globalMemBefore: Object.assign({}, this.globalMemBefore),
+            globalMemPeak: Object.assign({}, this.globalSampledPeak),
+            globalMemAfter: Object.assign({}, this.globalMemAfter),
+            customCounters: new Map(this.customCounters),
+            signatureSnapshots: this.signatureSnapshots.map(s => ({
+                label: s.label,
+                formal: Object.assign({}, s.formal),
+                temp: { class: Object.assign({}, s.temp.class), method: Object.assign({}, s.temp.method), field: Object.assign({}, s.temp.field) },
+            })),
+        };
+    }
+    /**
+     * Reset all collected data.
+     */
+    reset() {
+        this.runningStages.clear();
+        this.stageNameCounts.clear();
+        this.completedStages.length = 0;
+        this.customCounters.clear();
+        this.signatureSnapshots.length = 0;
+        this.startTime = 0;
+        this.endTime = 0;
+        this.globalSampledPeak = emptySnapshot();
+        this.globalMemBefore = emptySnapshot();
+        this.globalMemAfter = emptySnapshot();
+        this.finished = false;
+    }
+    /**
+     * Export statistics as a JSON string (Map is converted to a plain object).
+     */
+    exportToJson() {
+        const data = this.getStatistics();
+        const customCounters = {};
+        data.customCounters.forEach((v, k) => {
+            customCounters[k] = v;
+        });
+        return JSON.stringify(Object.assign(Object.assign({}, data), { customCounters }), null, 2);
+    }
+    /**
+     * Resolve a unique stage name by appending `#N` if the name was used before.
+     * The first use keeps the original name; subsequent uses get `#2`, `#3`, ...
+     */
+    resolveUniqueName(name) {
+        var _a;
+        const count = ((_a = this.stageNameCounts.get(name)) !== null && _a !== void 0 ? _a : 0) + 1;
+        this.stageNameCounts.set(name, count);
+        if (count === 1) {
+            return name;
+        }
+        return `${name}#${count}`;
+    }
+    /**
+     * The most recently started still-running stage (Map insertion order = start
+     * order; the last key is the stack top). The stage being started itself is
+     * excluded from the candidate set.
+     */
+    currentStackTop(excludeName) {
+        let top;
+        for (const key of this.runningStages.keys()) {
+            if (key !== excludeName) {
+                top = key;
+            }
+        }
+        return top;
+    }
+    /**
+     * Find the unique name of a currently running stage that matches the given base name.
+     * Matches `name` exactly or the `name#N` pattern. Returns the most recently started match.
+     */
+    findRunningStageName(name) {
+        if (this.runningStages.size === 0) {
+            return undefined;
+        }
+        let exact;
+        let suffixed;
+        let suffixedNum = -1;
+        for (const key of this.runningStages.keys()) {
+            if (key === name) {
+                exact = key;
+            }
+            else if (key.startsWith(`${name}#`)) {
+                const num = parseInt(key.slice(name.length + 1), 10);
+                if (!isNaN(num) && num > suffixedNum) {
+                    suffixedNum = num;
+                    suffixed = key;
+                }
+            }
+        }
+        return suffixed !== null && suffixed !== void 0 ? suffixed : exact;
+    }
+}
+exports.StageStatistics = StageStatistics;

package/lib/statistics/StageStatisticsReporter.d.ts

@@ -0,0 +1,58 @@
+import { StageStatisticsData } from './StageStatistics';
+/**
+ * A logical section of the statistics report.
+ */
+export interface ReportSection {
+    title: string;
+    data: Record<string, string | number>;
+}
+/**
+ * Structured statistics report.
+ */
+export interface StageStatisticsReport {
+    title: string;
+    timestamp: string;
+    summary: ReportSection;
+    stages: ReportSection;
+    signatures: ReportSection;
+    custom: ReportSection;
+}
+/**
+ * Generates text reports from {@link StageStatisticsData}.
+ *
+ * Output format is a human-readable, sectioned text block suitable for
+ * file output or logger.info.
+ */
+export declare class StageStatisticsReporter {
+    /**
+     * Build a structured report from raw statistics data.
+     */
+    static generateReport(data: StageStatisticsData, title?: string): StageStatisticsReport;
+    private static generateSummarySection;
+    private static generateStagesSection;
+    private static generateSignatureSection;
+    private static generateCustomSection;
+    /**
+     * Render a report as a text string.
+     */
+    static exportToText(report: StageStatisticsReport): string;
+    private static formatSection;
+    /**
+     * Format the stages section: values are pre-formatted multi-line strings
+     * stored as numbered keys; render them directly without `key: value`.
+     */
+    private static formatStageSection;
+    /**
+     * Save a text report to a file.
+     */
+    static saveReportToFile(report: StageStatisticsReport, filePath: string): void;
+    /**
+     * Check whether statistics data contains meaningful values.
+     */
+    static isStatisticsValid(data: StageStatisticsData): boolean;
+    /**
+     * Generate a one-line status message.
+     */
+    static generateStatusMessage(data: StageStatisticsData): string;
+}
+//# sourceMappingURL=StageStatisticsReporter.d.ts.map

package/lib/statistics/StageStatisticsReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StageStatisticsReporter.d.ts","sourceRoot":"","sources":["../../src/statistics/StageStatisticsReporter.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkC,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,aAAa,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;CACzB;AAgCD;;;;;GAKG;AACH,qBAAa,uBAAuB;IAChC;;OAEG;WACW,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,KAAK,GAAE,MAA8C,GAAG,qBAAqB;IAWrI,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAerC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA8CpC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAgCvC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAWpC;;OAEG;WACW,YAAY,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM;IAkBjE,OAAO,CAAC,MAAM,CAAC,aAAa;IAc5B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;OAEG;WACW,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IASrF;;OAEG;WACW,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO;IAInE;;OAEG;WACW,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM;CAMzE"}

package/lib/statistics/StageStatisticsReporter.js

@@ -0,0 +1,255 @@
+"use strict";
+/*
+ * Copyright (c) 2024-2026 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StageStatisticsReporter = void 0;
+const fs = __importStar(require("fs"));
+function formatLocalTimestamp(date = new Date()) {
+    const pad2 = (n) => n.toString().padStart(2, '0');
+    const pad3 = (n) => n.toString().padStart(3, '0');
+    const y = date.getFullYear();
+    const mo = pad2(date.getMonth() + 1);
+    const d = pad2(date.getDate());
+    const h = pad2(date.getHours());
+    const mi = pad2(date.getMinutes());
+    const s = pad2(date.getSeconds());
+    const ms = pad3(date.getMilliseconds());
+    const offsetMin = -date.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? '+' : '-';
+    const abs = Math.abs(offsetMin);
+    const offH = pad2(Math.floor(abs / 60));
+    const offM = pad2(abs % 60);
+    return `${y}-${mo}-${d}T${h}:${mi}:${s}.${ms}${sign}${offH}:${offM}`;
+}
+function fmtMB(v) {
+    return v.toFixed(2);
+}
+function fmtMs(v) {
+    return `${v} ms`;
+}
+function memLine(label, m) {
+    return `${label}: RSS ${fmtMB(m.rssMB)} MB | Heap ${fmtMB(m.heapUsedMB)} MB`;
+}
+/**
+ * Generates text reports from {@link StageStatisticsData}.
+ *
+ * Output format is a human-readable, sectioned text block suitable for
+ * file output or logger.info.
+ */
+class StageStatisticsReporter {
+    /**
+     * Build a structured report from raw statistics data.
+     */
+    static generateReport(data, title = 'ArkAnalyzer Stage Statistics Report') {
+        return {
+            title,
+            timestamp: formatLocalTimestamp(),
+            summary: this.generateSummarySection(data),
+            stages: this.generateStagesSection(data),
+            signatures: this.generateSignatureSection(data),
+            custom: this.generateCustomSection(data),
+        };
+    }
+    static generateSummarySection(data) {
+        const incremental = data.globalMemPeak.rssMB - data.globalMemBefore.rssMB;
+        return {
+            title: 'Summary',
+            data: {
+                'Total Time': fmtMs(data.totalDurationMs),
+                [memLine('Start', data.globalMemBefore)]: '',
+                [memLine('Peak', data.globalMemPeak)]: '',
+                [memLine('End', data.globalMemAfter)]: '',
+                'Incremental RSS': `${fmtMB(incremental)} MB`,
+                'Stage Count': data.stages.length,
+            },
+        };
+    }
+    static generateStagesSection(data) {
+        // 层级树形渲染：按 parent 关系组树（完成序天然子先于父，平铺会散乱），
+        // DFS 先序输出——父阶段在前，子阶段按各自完成序缩进跟随。两遍扫描（先
+        // 建全量索引再连边——完成序中父后于子，单遍会误判 root）。parent 链断落
+        // （如父阶段未记录）按顶层渲染，防御不崩。
+        const byName = new Map();
+        for (const stage of data.stages) {
+            byName.set(stage.name, { stage, children: [] });
+        }
+        const roots = [];
+        for (const stage of data.stages) {
+            const p = stage.parent;
+            if (p !== undefined && byName.has(p)) {
+                byName.get(p).children.push(stage);
+            }
+            else {
+                roots.push(stage);
+            }
+        }
+        const entries = [];
+        const render = (stage, depth) => {
+            const indent = '  '.repeat(depth);
+            entries.push(`${indent}[${stage.name}]`);
+            entries.push(`${indent}  Duration: ${fmtMs(stage.durationMs)}`);
+            entries.push(`${indent}  ${memLine('  Before', stage.memBefore)}`);
+            entries.push(`${indent}  ${memLine('  Peak', stage.memPeak)}`);
+            entries.push(`${indent}  ${memLine('  After', stage.memAfter)}`);
+            for (const child of byName.get(stage.name).children) {
+                render(child, depth + 1);
+            }
+        };
+        for (const root of roots) {
+            render(root, 0);
+        }
+        if (entries.length === 0) {
+            entries.push('(no stages recorded)');
+        }
+        const dataMap = {};
+        entries.forEach((line, i) => {
+            dataMap[`line${i}`] = line;
+        });
+        return {
+            title: 'Stage Statistics',
+            data: dataMap,
+        };
+    }
+    static generateSignatureSection(data) {
+        const entries = [];
+        for (const snap of data.signatureSnapshots) {
+            const formalTotal = snap.formal.file + snap.formal.class + snap.formal.namespace + snap.formal.field + snap.formal.method;
+            entries.push(`[${snap.label}]`);
+            entries.push(`  Formal: file=${snap.formal.file.toLocaleString()} class=${snap.formal.class.toLocaleString()} namespace=${snap.formal.namespace.toLocaleString()}` +
+                ` field=${snap.formal.field.toLocaleString()} method=${snap.formal.method.toLocaleString()} (total=${formalTotal.toLocaleString()})`);
+            entries.push(`  Temp class : live=${snap.temp.class.liveCount.toLocaleString()} total=${snap.temp.class.totalRegistered.toLocaleString()}` +
+                ` retired=${snap.temp.class.retiredCount.toLocaleString()} replaced=${snap.temp.class.replacedCount.toLocaleString()}`);
+            entries.push(`  Temp method: live=${snap.temp.method.liveCount.toLocaleString()} total=${snap.temp.method.totalRegistered.toLocaleString()}` +
+                ` retired=${snap.temp.method.retiredCount.toLocaleString()} replaced=${snap.temp.method.replacedCount.toLocaleString()}`);
+            entries.push(`  Temp field : live=${snap.temp.field.liveCount.toLocaleString()} total=${snap.temp.field.totalRegistered.toLocaleString()}` +
+                ` retired=${snap.temp.field.retiredCount.toLocaleString()} replaced=${snap.temp.field.replacedCount.toLocaleString()}`);
+        }
+        const dataMap = {};
+        entries.forEach((line, i) => {
+            dataMap[`line${i}`] = line;
+        });
+        return {
+            title: 'Signature Statistics',
+            data: dataMap,
+        };
+    }
+    static generateCustomSection(data) {
+        const dataMap = {};
+        data.customCounters.forEach((value, key) => {
+            dataMap[key] = value.toLocaleString();
+        });
+        return {
+            title: 'Custom Statistics',
+            data: dataMap,
+        };
+    }
+    /**
+     * Render a report as a text string.
+     */
+    static exportToText(report) {
+        const sep = '='.repeat(40);
+        let out = `${sep}\n`;
+        out += `${report.title}\n`;
+        out += `${sep}\n`;
+        out += `Generated Time: ${report.timestamp}\n\n`;
+        out += this.formatSection(report.summary);
+        out += this.formatStageSection(report.stages);
+        if (Object.keys(report.signatures.data).length > 0) {
+            out += this.formatStageSection(report.signatures);
+        }
+        if (Object.keys(report.custom.data).length > 0) {
+            out += this.formatSection(report.custom);
+        }
+        out += `${sep}\n`;
+        return out;
+    }
+    static formatSection(section) {
+        let out = `${section.title}\n`;
+        out += '-'.repeat(section.title.length) + '\n';
+        for (const [key, value] of Object.entries(section.data)) {
+            if (value === '') {
+                out += `${key}\n`;
+            }
+            else {
+                out += `${key}: ${value}\n`;
+            }
+        }
+        out += '\n';
+        return out;
+    }
+    /**
+     * Format the stages section: values are pre-formatted multi-line strings
+     * stored as numbered keys; render them directly without `key: value`.
+     */
+    static formatStageSection(section) {
+        let out = `${section.title}\n`;
+        out += '-'.repeat(section.title.length) + '\n';
+        for (const value of Object.values(section.data)) {
+            out += `${value}\n`;
+        }
+        out += '\n';
+        return out;
+    }
+    /**
+     * Save a text report to a file.
+     */
+    static saveReportToFile(report, filePath) {
+        const text = this.exportToText(report);
+        const dir = filePath.substring(0, Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\')));
+        if (dir) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, text, 'utf-8');
+    }
+    /**
+     * Check whether statistics data contains meaningful values.
+     */
+    static isStatisticsValid(data) {
+        return data.totalDurationMs > 0 || data.stages.length > 0;
+    }
+    /**
+     * Generate a one-line status message.
+     */
+    static generateStatusMessage(data) {
+        if (!this.isStatisticsValid(data)) {
+            return 'No valid statistics data collected.';
+        }
+        return `Analysis completed in ${data.totalDurationMs} ms across ${data.stages.length} stage(s).`;
+    }
+}
+exports.StageStatisticsReporter = StageStatisticsReporter;

package/lib/utils/Canonicalizer.d.ts

@@ -1,5 +1,5 @@
 type CanonicalizerStrategy = 'uninitialized' | 'objectIdentity' | 'numberWithEquality' | 'stringIdentity';
-interface CanonicalizerStats {
+export interface CanonicalizerStats {
     strategy: CanonicalizerStrategy;
     size: number;
     bucketCount: number;
@@ -57,7 +57,14 @@ export declare class Canonicalizer<T> {
      */
     get(id: number): T | undefined;
     /**
-     * Get the total number of unique items seen so far.
+     * Remove the item at the given ID by setting the slot to undefined.
+     * The ID is NOT recycled — subsequent registrations still get fresh dense IDs.
+     * Note: does NOT remove the Symbol property from the object (if objectIdentity strategy);
+     * the Symbol remains for audit traceability.
+     */
+    removeAt(id: number): void;
+    /**
+     * Get the total number of unique items seen so far (includes removed slots).
      */
     size(): number;
     getStats(): CanonicalizerStats;