bsprof-cli 1.0.0

package/dist/index.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'fs';
+import { Command } from 'commander';
+import { BsprofParser } from './parser/BsprofParser.js';
+import { analyzeMemory } from './analyzer/MemoryAnalyzer.js';
+import { analyzeCpu } from './analyzer/CpuAnalyzer.js';
+import { compareBsprof } from './analyzer/DiffAnalyzer.js';
+import { buildHeaderInfo, buildParseStats } from './analyzer/common.js';
+import { aggregate, rankFunctions } from './analyzer/Aggregator.js';
+import { TextFormatter } from './formatter/TextFormatter.js';
+import { JsonFormatter } from './formatter/JsonFormatter.js';
+import { MarkdownFormatter } from './formatter/MarkdownFormatter.js';
+import { ChromeTraceExporter } from './formatter/ChromeTraceExporter.js';
+import { CsvExporter } from './formatter/CsvExporter.js';
+const program = new Command();
+program
+    .name('bsprof')
+    .description('CLI tool for parsing and analyzing BrightScript Profiler (.bsprof) files')
+    .version('1.0.0');
+// --- analyze command ---
+program
+    .command('analyze')
+    .description('Analyze a .bsprof file')
+    .argument('<mode>', 'Analysis mode: memory, cpu, full, summary')
+    .argument('<file>', 'Path to .bsprof file')
+    .option('--format <fmt>', 'Output format: text, json, markdown', 'text')
+    .option('--top <n>', 'Number of entries in ranked lists', '30')
+    .option('--sort <field>', 'Sort field (mode-dependent)')
+    .option('--filter-module <name>', 'Filter results to a specific module/thread')
+    .option('--filter-file <glob>', 'Filter results to files matching glob')
+    .option('--exclude-module <name>', 'Exclude a module')
+    .option('--threshold <bytes>', 'Only show entries exceeding threshold', '0')
+    .option('--output <path>', 'Write output to file instead of stdout')
+    .action((mode, file, opts) => {
+    const analysisMode = mode;
+    if (!['memory', 'cpu', 'full', 'summary'].includes(analysisMode)) {
+        console.error(`Unknown mode: ${mode}. Use: memory, cpu, full, summary`);
+        process.exit(1);
+    }
+    const profile = parseFile(file);
+    const options = {
+        top: parseInt(opts.top, 10),
+        sortBy: opts.sort,
+        filterModule: opts.filterModule,
+        filterFile: opts.filterFile,
+        excludeModule: opts.excludeModule,
+        threshold: parseInt(opts.threshold, 10),
+    };
+    const format = opts.format;
+    let output = '';
+    switch (analysisMode) {
+        case 'memory': {
+            const report = analyzeMemory(profile, options);
+            output = formatOutput(format, 'memory', report);
+            break;
+        }
+        case 'cpu': {
+            const report = analyzeCpu(profile, options);
+            output = formatOutput(format, 'cpu', report);
+            break;
+        }
+        case 'full': {
+            const memReport = analyzeMemory(profile, options);
+            const cpuReport = analyzeCpu(profile, options);
+            const fullReport = {
+                header: memReport.header,
+                memory: memReport,
+                cpu: cpuReport,
+            };
+            output = formatOutput(format, 'full', fullReport);
+            break;
+        }
+        case 'summary': {
+            const top = options.top ?? 10;
+            const agg = aggregate(profile, options);
+            const allFuncs = [...agg.byFunction.values()];
+            const summaryReport = {
+                header: buildHeaderInfo(profile),
+                parseStats: buildParseStats(profile),
+                topMemoryLeaks: rankFunctions(allFuncs, 'retained', top),
+                topCpuConsumers: rankFunctions(allFuncs.filter(f => f.cpuSelf > 0), 'cpuSelf', top),
+                moduleOverview: [...agg.byModule.values()].sort((a, b) => b.retainedBytes - a.retainedBytes),
+            };
+            output = formatOutput(format, 'summary', summaryReport);
+            break;
+        }
+    }
+    writeOutput(output, opts.output);
+});
+// --- compare command ---
+program
+    .command('compare')
+    .description('Compare two .bsprof files to detect regressions')
+    .argument('<file1>', 'Before profile')
+    .argument('<file2>', 'After profile')
+    .option('--format <fmt>', 'Output format: text, json, markdown', 'text')
+    .option('--top <n>', 'Number of entries in ranked lists', '30')
+    .option('--filter-module <name>', 'Filter results to a specific module/thread')
+    .option('--exclude-module <name>', 'Exclude a module')
+    .option('--output <path>', 'Write output to file instead of stdout')
+    .action((file1, file2, opts) => {
+    const before = parseFile(file1);
+    const after = parseFile(file2);
+    const options = {
+        top: parseInt(opts.top, 10),
+        filterModule: opts.filterModule,
+        excludeModule: opts.excludeModule,
+    };
+    const report = compareBsprof(before, after, file1, file2, options);
+    const format = opts.format;
+    const formatter = getFormatter(format);
+    const output = formatter.formatDiffReport(report);
+    writeOutput(output, opts.output);
+});
+// --- info command ---
+program
+    .command('info')
+    .description('Print header metadata from a .bsprof file')
+    .argument('<file>', 'Path to .bsprof file')
+    .option('--format <fmt>', 'Output format: text, json, markdown', 'text')
+    .action((file, opts) => {
+    const buf = readFileSync(file);
+    const parser = new BsprofParser(buf);
+    const { header, fileSize } = parser.parseHeaderOnly();
+    // Minimal info — we need a full parse for duration but we can show what we have
+    const headerInfo = buildHeaderInfo({
+        header,
+        strings: new Map(),
+        modules: new Map(),
+        pathElements: new Map(),
+        parseResult: { count: 0, errors: 0, memoryByPE: new Map(), cpuByPE: new Map() },
+        fileSize,
+    });
+    const format = opts.format;
+    const formatter = getFormatter(format);
+    const output = formatter.formatInfo(headerInfo, fileSize);
+    console.log(output);
+});
+// --- export command ---
+program
+    .command('export')
+    .description('Export parsed data for external tools')
+    .argument('<file>', 'Path to .bsprof file')
+    .option('--format <fmt>', 'Export format: chrome-trace, csv, json', 'json')
+    .option('--filter-module <name>', 'Filter results to a specific module/thread')
+    .option('--exclude-module <name>', 'Exclude a module')
+    .option('--output <path>', 'Write output to file instead of stdout')
+    .action((file, opts) => {
+    const profile = parseFile(file);
+    const exportFormat = opts.format;
+    const options = {
+        filterModule: opts.filterModule,
+        excludeModule: opts.excludeModule,
+    };
+    let output;
+    switch (exportFormat) {
+        case 'chrome-trace': {
+            const exporter = new ChromeTraceExporter();
+            output = exporter.export(profile);
+            break;
+        }
+        case 'csv': {
+            const exporter = new CsvExporter();
+            output = exporter.export(profile, options);
+            break;
+        }
+        case 'json': {
+            const memReport = analyzeMemory(profile, { ...options, top: Infinity });
+            output = JSON.stringify(memReport, null, 2);
+            break;
+        }
+        default: {
+            console.error(`Unknown export format: ${exportFormat}. Use: chrome-trace, csv, json`);
+            process.exit(1);
+        }
+    }
+    writeOutput(output, opts.output);
+});
+// --- helpers ---
+function parseFile(filePath) {
+    try {
+        const buf = readFileSync(filePath);
+        const parser = new BsprofParser(buf);
+        return parser.parse();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error parsing ${filePath}: ${msg}`);
+        return process.exit(1);
+    }
+}
+function getFormatter(format) {
+    switch (format) {
+        case 'json': return new JsonFormatter();
+        case 'markdown': return new MarkdownFormatter();
+        case 'text':
+        default: return new TextFormatter();
+    }
+}
+function formatOutput(format, mode, report) {
+    const formatter = getFormatter(format);
+    switch (mode) {
+        case 'memory': return formatter.formatMemoryReport(report);
+        case 'cpu': return formatter.formatCpuReport(report);
+        case 'full': return formatter.formatFullReport(report);
+        case 'summary': return formatter.formatSummaryReport(report);
+        default: return JSON.stringify(report, null, 2);
+    }
+}
+function writeOutput(output, filePath) {
+    if (filePath) {
+        writeFileSync(filePath, output, 'utf-8');
+        console.error(`Output written to ${filePath}`);
+    }
+    else {
+        console.log(output);
+    }
+}
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/lib.d.ts

@@ -0,0 +1,27 @@
+export { BsprofParser } from './parser/BsprofParser.js';
+export { BufferReader } from './parser/varint.js';
+export { analyzeMemory } from './analyzer/MemoryAnalyzer.js';
+export { analyzeCpu } from './analyzer/CpuAnalyzer.js';
+export { compareBsprof } from './analyzer/DiffAnalyzer.js';
+export { aggregate, rankFunctions } from './analyzer/Aggregator.js';
+export { buildHeaderInfo, buildParseStats } from './analyzer/common.js';
+export { TextFormatter } from './formatter/TextFormatter.js';
+export { JsonFormatter } from './formatter/JsonFormatter.js';
+export { MarkdownFormatter } from './formatter/MarkdownFormatter.js';
+export { ChromeTraceExporter } from './formatter/ChromeTraceExporter.js';
+export { CsvExporter } from './formatter/CsvExporter.js';
+export type { BsprofHeader, PathElement, ModuleEntry, MemoryRecord, CpuRecord, ParseResult, ParsedProfile, AnalysisOptions, MemorySortField, CpuSortField, ModuleStats, FileStats, FunctionStats, HeaderInfo, ParseStats, MemorySummary, MemoryReport, CpuSummary, CpuReport, FullReport, SummaryReport, FunctionDelta, DiffReport, ChromeTraceEvent, OutputFormat, ExportFormat, AnalysisMode, } from './parser/types.js';
+/**
+ * Convenience: parse a Buffer and return the full profile.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'fs';
+ * import { parseBsprof, analyzeMemory } from 'bsprof-cli';
+ *
+ * const profile = parseBsprof(readFileSync('profile.bsprof'));
+ * const report = analyzeMemory(profile, { top: 20 });
+ * ```
+ */
+export declare function parseBsprof(buffer: Buffer): import("./parser/types.js").ParsedProfile;
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.js

@@ -0,0 +1,30 @@
+import { BsprofParser } from './parser/BsprofParser.js';
+export { BsprofParser } from './parser/BsprofParser.js';
+export { BufferReader } from './parser/varint.js';
+export { analyzeMemory } from './analyzer/MemoryAnalyzer.js';
+export { analyzeCpu } from './analyzer/CpuAnalyzer.js';
+export { compareBsprof } from './analyzer/DiffAnalyzer.js';
+export { aggregate, rankFunctions } from './analyzer/Aggregator.js';
+export { buildHeaderInfo, buildParseStats } from './analyzer/common.js';
+export { TextFormatter } from './formatter/TextFormatter.js';
+export { JsonFormatter } from './formatter/JsonFormatter.js';
+export { MarkdownFormatter } from './formatter/MarkdownFormatter.js';
+export { ChromeTraceExporter } from './formatter/ChromeTraceExporter.js';
+export { CsvExporter } from './formatter/CsvExporter.js';
+/**
+ * Convenience: parse a Buffer and return the full profile.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'fs';
+ * import { parseBsprof, analyzeMemory } from 'bsprof-cli';
+ *
+ * const profile = parseBsprof(readFileSync('profile.bsprof'));
+ * const report = analyzeMemory(profile, { top: 20 });
+ * ```
+ */
+export function parseBsprof(buffer) {
+    const parser = new BsprofParser(buffer);
+    return parser.parse();
+}
+//# sourceMappingURL=lib.js.map

package/dist/parser/BsprofParser.d.ts

@@ -0,0 +1,27 @@
+import type { BsprofHeader, ParsedProfile } from './types.js';
+export declare class BsprofParser {
+    private buffer;
+    private reader;
+    private strings;
+    private modules;
+    private pathElements;
+    private header;
+    private allocSizes;
+    constructor(buffer: Buffer);
+    parse(): ParsedProfile;
+    /** Parse only the header — used by the `info` command for fast metadata reads */
+    parseHeaderOnly(): {
+        header: BsprofHeader;
+        fileSize: number;
+    };
+    private parseHeader;
+    private parseBody;
+    private readFooterTimestamp;
+    static resolveString(profile: ParsedProfile, id: number): string;
+    static resolveModuleName(profile: ParsedProfile, peId: number, depth?: number): string;
+    static resolveFileName(profile: ParsedProfile, peId: number): string;
+    static resolveFuncName(profile: ParsedProfile, peId: number): string;
+    /** Walk the path element chain to reconstruct the full call stack */
+    static resolveCallStack(profile: ParsedProfile, peId: number, maxDepth?: number): string[];
+}
+//# sourceMappingURL=BsprofParser.d.ts.map

package/dist/parser/BsprofParser.js

@@ -0,0 +1,251 @@
+import { BufferReader } from './varint.js';
+const MAGIC = 'bsprof';
+export class BsprofParser {
+    buffer;
+    reader;
+    strings = new Map();
+    modules = new Map();
+    pathElements = new Map();
+    header;
+    allocSizes = new Map();
+    constructor(buffer) {
+        this.buffer = buffer;
+        this.reader = new BufferReader(buffer);
+    }
+    parse() {
+        this.parseHeader();
+        const parseResult = this.parseBody();
+        const timestampEnd = this.readFooterTimestamp();
+        return {
+            header: this.header,
+            strings: this.strings,
+            modules: this.modules,
+            pathElements: this.pathElements,
+            parseResult,
+            timestampEnd,
+            fileSize: this.buffer.length,
+        };
+    }
+    /** Parse only the header — used by the `info` command for fast metadata reads */
+    parseHeaderOnly() {
+        this.parseHeader();
+        return { header: this.header, fileSize: this.buffer.length };
+    }
+    parseHeader() {
+        const magic = this.reader.readAscii(6);
+        if (magic !== MAGIC) {
+            throw new Error(`Not a .bsprof file (magic: "${magic}", expected "${MAGIC}")`);
+        }
+        this.reader.pos = 8; // skip 2 padding bytes after magic
+        this.header = {
+            majorVersion: this.reader.vi(),
+            minorVersion: this.reader.vi(),
+            patchLevel: this.reader.vi(),
+            headerSize: this.reader.vi(),
+            requestedSampleRatio: this.reader.readFloat32LE(),
+            actualSampleRatio: this.reader.readFloat32LE(),
+            lineSpecificData: this.reader.vi() !== 0,
+            memoryOperations: this.reader.vi() !== 0,
+            timestampStart: this.reader.vi64(),
+            targetName: this.reader.readUtf8z(),
+            supplementalInfo: this.reader.readUtf8z(),
+            targetVersion: this.reader.readUtf8z(),
+            deviceVendor: this.reader.readUtf8z(),
+            deviceModel: this.reader.readUtf8z(),
+            deviceFirmware: this.reader.readUtf8z(),
+        };
+        this.reader.pos = this.header.headerSize;
+    }
+    parseBody() {
+        const hasLine = this.header.lineSpecificData;
+        let count = 0;
+        let errors = 0;
+        const len = this.reader.length;
+        const memoryByPE = new Map();
+        const cpuByPE = new Map();
+        while (this.reader.pos < len) {
+            const startPos = this.reader.pos;
+            try {
+                const tag = this.reader.readVarint();
+                if (tag === 0n)
+                    break;
+                const type = Number(tag & 0x7n);
+                switch (type) {
+                    case 0: { // String table entry
+                        const strId = Number(tag >> 3n);
+                        const str = this.reader.readUtf8z();
+                        if (!this.strings.has(strId)) {
+                            this.strings.set(strId, str);
+                        }
+                        break;
+                    }
+                    case 1: { // Executable module entry
+                        const modId = Number(tag >> 3n);
+                        const nameStrId = this.reader.vi();
+                        if (!this.modules.has(modId)) {
+                            this.modules.set(modId, { nameStrId });
+                        }
+                        break;
+                    }
+                    case 2: { // Path element entry
+                        const peId = Number(tag >> 3n);
+                        const callingId = this.reader.vi();
+                        if (callingId === 0) {
+                            // Root path element
+                            const modId = this.reader.vi();
+                            const fileStrId = this.reader.vi();
+                            const lineNumber = this.reader.vi();
+                            const funcStrId = this.reader.vi();
+                            this.pathElements.set(peId, {
+                                callingId: 0, modId, fileStrId, funcStrId, lineNumber, root: true,
+                            });
+                        }
+                        else {
+                            // Non-root (chained) path element
+                            const lineOff = hasLine ? this.reader.vi() : 0;
+                            const fileStrId = this.reader.vi();
+                            const lineNumber = this.reader.vi();
+                            const funcStrId = this.reader.vi();
+                            this.pathElements.set(peId, {
+                                callingId, lineOff, fileStrId, funcStrId, lineNumber, root: false,
+                            });
+                        }
+                        break;
+                    }
+                    case 3: { // Memory operation entry
+                        const opType = Number((tag >> 3n) & 0x3n);
+                        const peId = Number(tag >> 5n);
+                        if (hasLine)
+                            this.reader.vi(); // line offset (consumed but unused here)
+                        const addr = this.reader.vi64();
+                        let size = 0;
+                        if (opType === 0) {
+                            size = this.reader.vi();
+                        }
+                        let rec = memoryByPE.get(peId);
+                        if (!rec) {
+                            rec = { allocCount: 0, freeCount: 0, allocBytes: 0, freeBytes: 0 };
+                            memoryByPE.set(peId, rec);
+                        }
+                        if (opType === 0) { // alloc
+                            rec.allocCount++;
+                            rec.allocBytes += size;
+                            this.allocSizes.set(addr, size);
+                        }
+                        else { // free or free_realloc
+                            rec.freeCount++;
+                            const origSize = this.allocSizes.get(addr) || 0;
+                            rec.freeBytes += origSize;
+                            this.allocSizes.delete(addr);
+                        }
+                        break;
+                    }
+                    case 4: { // CPU measurement entry
+                        const peId = Number(tag >> 3n);
+                        if (hasLine)
+                            this.reader.vi(); // line offset
+                        const cpuCycles = this.reader.vi();
+                        const wallTime = this.reader.vi();
+                        let rec = cpuByPE.get(peId);
+                        if (!rec) {
+                            rec = { cpuSelf: 0, wallSelf: 0 };
+                            cpuByPE.set(peId, rec);
+                        }
+                        rec.cpuSelf += cpuCycles;
+                        rec.wallSelf += wallTime;
+                        break;
+                    }
+                    case 5: { // Path call count entry
+                        const peId = Number(tag >> 3n);
+                        const callCount = this.reader.vi();
+                        let rec = cpuByPE.get(peId);
+                        if (!rec) {
+                            rec = { cpuSelf: 0, wallSelf: 0 };
+                            cpuByPE.set(peId, rec);
+                        }
+                        rec.callCount = (rec.callCount || 0) + callCount;
+                        break;
+                    }
+                    case 6: // reserved
+                    case 7: // reserved
+                        break;
+                    default: {
+                        errors++;
+                        if (errors > 1000) {
+                            return { count, memoryByPE, cpuByPE, errors };
+                        }
+                        break;
+                    }
+                }
+                count++;
+            }
+            catch {
+                errors++;
+                this.reader.pos = startPos + 1;
+                if (errors > 1000) {
+                    return { count, memoryByPE, cpuByPE, errors };
+                }
+            }
+        }
+        return { count, memoryByPE, cpuByPE, errors };
+    }
+    readFooterTimestamp() {
+        try {
+            if (this.reader.remaining >= 1) {
+                return this.reader.vi64();
+            }
+        }
+        catch {
+            // Footer may not always be present
+        }
+        return undefined;
+    }
+    // --- Lookup helpers exposed on the profile ---
+    static resolveString(profile, id) {
+        const s = profile.strings.get(id);
+        return s !== undefined ? s : `<str:${id}>`;
+    }
+    static resolveModuleName(profile, peId, depth = 0) {
+        if (depth > 60)
+            return '?';
+        const pe = profile.pathElements.get(peId);
+        if (!pe)
+            return '?';
+        if (pe.root) {
+            const mod = profile.modules.get(pe.modId);
+            if (!mod)
+                return `Module ${pe.modId}`;
+            const name = profile.strings.get(mod.nameStrId);
+            return (name !== undefined && name !== '') ? name : `Thread ${pe.modId}`;
+        }
+        return BsprofParser.resolveModuleName(profile, pe.callingId, depth + 1);
+    }
+    static resolveFileName(profile, peId) {
+        const pe = profile.pathElements.get(peId);
+        return pe ? BsprofParser.resolveString(profile, pe.fileStrId) : '?';
+    }
+    static resolveFuncName(profile, peId) {
+        const pe = profile.pathElements.get(peId);
+        if (!pe)
+            return '?';
+        return BsprofParser.resolveString(profile, pe.funcStrId);
+    }
+    /** Walk the path element chain to reconstruct the full call stack */
+    static resolveCallStack(profile, peId, maxDepth = 60) {
+        const stack = [];
+        let current = peId;
+        let depth = 0;
+        while (current > 0 && depth < maxDepth) {
+            const pe = profile.pathElements.get(current);
+            if (!pe)
+                break;
+            const func = BsprofParser.resolveString(profile, pe.funcStrId);
+            const file = BsprofParser.resolveString(profile, pe.fileStrId);
+            stack.push(`${func} (${file}:${pe.lineNumber})`);
+            current = pe.callingId;
+            depth++;
+        }
+        return stack;
+    }
+}
+//# sourceMappingURL=BsprofParser.js.map