@houwert/conductor 0.28.0 → 0.29.1

package/dist/commands/profile-gc.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGcEvents = parseGcEvents;
+exports.summariseGc = summariseGc;
+exports.deviceLogcatTimestamp = deviceLogcatTimestamp;
+exports.collectGcSince = collectGcSince;
+/**
+ * Android GC-pause scraping.
+ *
+ * ART logs every collection it considers noteworthy to logcat under the `art`
+ * tag; the pause figures in those lines are the stop-the-world portions, which
+ * is what shows up as a dropped frame. Scraped rather than sampled because
+ * there is no dumpsys surface for pause times.
+ */
+const device_js_1 = require("../android/device.js");
+const stats_js_1 = require("../stats.js");
+function toMs(value) {
+    const m = value.match(/^([\d.]+)(us|ms|s)$/);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    if (m[2] === 'us')
+        return n / 1000;
+    if (m[2] === 's')
+        return n * 1000;
+    return n;
+}
+function toBytes(value) {
+    if (!value)
+        return undefined;
+    const m = value.match(/^([\d.]+)(B|KB|MB|GB)$/i);
+    if (!m)
+        return undefined;
+    const mult = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3 }[m[2].toLowerCase()];
+    return Math.round(Number(m[1]) * mult);
+}
+/**
+ * Parse ART GC lines out of raw logcat. Tolerates the pause list being one or
+ * several values and the units varying between us and ms.
+ */
+function parseGcEvents(logcat) {
+    const events = [];
+    const re = /([A-Za-z][A-Za-z ]*?) GC freed (?:[\d.]+)\(([\d.]+[KMG]?B)\) AllocSpace objects.*?, (?:[\d.]+% free, )?([\d.]+[KMG]?B)\/([\d.]+[KMG]?B), paused ([\d.]+(?:us|ms|s)(?:,\s*[\d.]+(?:us|ms|s))*) total ([\d.]+(?:us|ms|s))/g;
+    for (const m of logcat.matchAll(re)) {
+        events.push({
+            kind: m[1].trim(),
+            freedBytes: toBytes(m[2]),
+            heapUsedBytes: toBytes(m[3]),
+            heapTotalBytes: toBytes(m[4]),
+            pausesMs: m[5].split(',').map((p) => toMs(p.trim())),
+            totalMs: toMs(m[6]),
+        });
+    }
+    return events;
+}
+function summariseGc(events) {
+    const pauses = events.flatMap((e) => e.pausesMs);
+    const byKind = new Map();
+    for (const e of events) {
+        const slot = byKind.get(e.kind) ?? { count: 0, totalPauseMs: 0 };
+        slot.count++;
+        slot.totalPauseMs += e.pausesMs.reduce((a, b) => a + b, 0);
+        byKind.set(e.kind, slot);
+    }
+    return {
+        events: events.length,
+        totalPauseMs: (0, stats_js_1.round)(pauses.reduce((a, b) => a + b, 0)),
+        pause: (0, stats_js_1.describe)(pauses),
+        duration: (0, stats_js_1.describe)(events.map((e) => e.totalMs)),
+        byKind: [...byKind.entries()]
+            .map(([kind, v]) => ({ kind, count: v.count, totalPauseMs: (0, stats_js_1.round)(v.totalPauseMs) }))
+            .sort((a, b) => b.totalPauseMs - a.totalPauseMs),
+    };
+}
+/**
+ * logcat's `-T` filter wants the device's own clock, which can drift from the
+ * host's, so ask the device what time it thinks it is.
+ */
+async function deviceLogcatTimestamp(deviceId) {
+    const res = await (0, device_js_1.adbShell)(deviceId, ['date', '+%m-%d %H:%M:%S.000']);
+    return res.success ? res.stdout.trim() : undefined;
+}
+async function collectGcSince(deviceId, since) {
+    const args = ['logcat', '-d'];
+    if (since)
+        args.push('-T', since);
+    args.push('art:I', '*:S');
+    const res = await (0, device_js_1.adbShell)(deviceId, args);
+    return res.success ? parseGcEvents(res.stdout) : [];
+}

package/dist/commands/profile-js.js

@@ -0,0 +1,366 @@
+"use strict";
+/**
+ * Hermes sampling profiler over the Metro CDP connection.
+ *
+ * `Profiler.start` / `Profiler.stop` return a Chrome `.cpuprofile`, so the raw
+ * file drops straight into Chrome DevTools (or `hermes-profile-transformer` for
+ * a Chrome trace), while the ranked self/total table is what an agent reads.
+ *
+ * `start`/`stop` hand the CDP socket to a detached holder process rather than
+ * closing it between the two commands: whether Hermes keeps sampling across a
+ * dropped debugger session is not contractual, and a holder makes it moot.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCpuProfile = analyzeCpuProfile;
+exports.profileJsRecord = profileJsRecord;
+exports.profileJsStart = profileJsStart;
+exports.profileJsStop = profileJsStop;
+exports.profileJsHold = profileJsHold;
+const child_process_1 = require("child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const output_js_1 = require("../output.js");
+const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const metro_cdp_js_1 = require("../drivers/metro-cdp.js");
+const stats_js_1 = require("../stats.js");
+/** Hermes marks its own frames with brackets; anything else is app code. */
+function classifyFrame(name) {
+    if (/^\[GC\b/i.test(name) || /garbage collector/i.test(name))
+        return 'gc';
+    if (name === '[root]' || name === '(root)' || name === '(program)' || name === '(idle)') {
+        return 'idle';
+    }
+    return name.startsWith('[') || name.startsWith('(') ? 'idle' : 'named';
+}
+function shortFile(url) {
+    const u = url ?? '';
+    return u.includes('/') ? u.slice(u.lastIndexOf('/') + 1) : u;
+}
+function frameKey(frame) {
+    const line = frame.lineNumber !== undefined ? `:${frame.lineNumber + 1}` : '';
+    return `${frame.functionName || '(anonymous)'} ${shortFile(frame.url)}${line}`;
+}
+/**
+ * Self time is the sample's own node; total time credits every function on the
+ * stack once per sample, so a recursive function is not counted twice for the
+ * same sample.
+ */
+function analyzeCpuProfile(profile, top) {
+    const byId = new Map();
+    const parentOf = new Map();
+    for (const node of profile.nodes) {
+        byId.set(node.id, node);
+        for (const child of node.children ?? [])
+            parentOf.set(child, node.id);
+    }
+    const samples = profile.samples ?? [];
+    const deltas = profile.timeDeltas ?? [];
+    const self = new Map();
+    const total = new Map();
+    const hits = new Map();
+    const label = new Map();
+    const add = (map, key, v) => {
+        map.set(key, (map.get(key) ?? 0) + v);
+    };
+    for (let i = 0; i < samples.length; i++) {
+        const node = byId.get(samples[i]);
+        if (!node)
+            continue;
+        const deltaUs = deltas[i] ?? 0;
+        const key = frameKey(node.callFrame);
+        label.set(key, node.callFrame);
+        add(self, key, deltaUs);
+        add(hits, key, 1);
+        const seen = new Set();
+        let cursor = node.id;
+        while (cursor !== undefined) {
+            const cur = byId.get(cursor);
+            if (!cur)
+                break;
+            const k = frameKey(cur.callFrame);
+            label.set(k, cur.callFrame);
+            if (!seen.has(k)) {
+                seen.add(k);
+                add(total, k, deltaUs);
+            }
+            cursor = parentOf.get(cursor);
+        }
+    }
+    const totalUs = [...self.values()].reduce((a, b) => a + b, 0);
+    // Split before ranking: a top-30 list assembled from 5% of the samples is
+    // noise dressed as a finding, and the reader cannot tell without this.
+    const buckets = { gc: 0, idle: 0, named: 0 };
+    for (const [key, us] of self.entries()) {
+        buckets[classifyFrame(label.get(key).functionName || '(anonymous)')] += us;
+    }
+    const share = (v) => (totalUs > 0 ? (0, stats_js_1.round)((v / totalUs) * 100, 1) : 0);
+    const attribution = {
+        namedJsPercent: share(buckets.named),
+        gcPercent: share(buckets.gc),
+        idlePercent: share(buckets.idle),
+    };
+    const notes = [];
+    if (totalUs > 0 && attribution.namedJsPercent < 25) {
+        notes.push({
+            code: 'low-attribution',
+            message: `Only ${attribution.namedJsPercent}% of sampled time landed in a named JS function ` +
+                `(${attribution.idlePercent}% with an empty JS stack, ${attribution.gcPercent}% in GC). ` +
+                `The ranking below is built on what little is left and should not be trusted. ` +
+                `A large empty-stack share means the JS thread was idle when sampled — which is itself ` +
+                `a result: the bottleneck is not JS. A large GC share is a memory finding; follow it ` +
+                `with \`profile memory --track\` rather than a function ranking.`,
+            namedJsPercent: attribution.namedJsPercent,
+            gcPercent: attribution.gcPercent,
+            idlePercent: attribution.idlePercent,
+        });
+    }
+    const ranked = [...self.entries()]
+        .map(([key, selfUs]) => {
+        const frame = label.get(key);
+        const file = shortFile(frame.url) || '(unknown)';
+        return {
+            name: frame.functionName || '(anonymous)',
+            location: frame.lineNumber !== undefined ? `${file}:${frame.lineNumber + 1}` : file,
+            selfMs: (0, stats_js_1.round)(selfUs / 1000),
+            totalMs: (0, stats_js_1.round)((total.get(key) ?? 0) / 1000),
+            selfPercent: totalUs > 0 ? (0, stats_js_1.round)((selfUs / totalUs) * 100) : 0,
+            samples: hits.get(key) ?? 0,
+        };
+    })
+        .sort((a, b) => b.selfMs - a.selfMs);
+    const sortedDeltas = deltas.filter((d) => d > 0).sort((a, b) => a - b);
+    return {
+        durationMs: (0, stats_js_1.round)((profile.endTime - profile.startTime) / 1000),
+        sampleCount: samples.length,
+        medianSampleIntervalMs: sortedDeltas.length > 0 ? (0, stats_js_1.round)(sortedDeltas[Math.floor(sortedDeltas.length / 2)] / 1000) : 0,
+        attribution,
+        top: ranked.slice(0, top),
+        omitted: Math.max(0, ranked.length - top),
+        notes,
+    };
+}
+async function connect(sessionName, cdpOpts) {
+    const platform = await (0, bootstrap_js_1.detectPlatform)(sessionName).catch(() => undefined);
+    const deviceId = sessionName !== 'default' ? sessionName : undefined;
+    const port = await (0, metro_cdp_js_1.resolveMetroPort)({ port: cdpOpts.port, deviceId, platform });
+    const client = new metro_cdp_js_1.MetroCdpClient();
+    await client.connect({ port, deviceId, platform, targetIndex: cdpOpts.targetIndex });
+    return client;
+}
+async function startSampling(client) {
+    // React Native's Fusebox CDP backend answers `Profiler.enable` with
+    // -32601 Unsupported method, but implements `Profiler.start` perfectly well.
+    // Enabling is a courtesy to backends that require it, never a precondition.
+    await client.send('Profiler.enable').catch(() => undefined);
+    await client.send('Profiler.start');
+}
+async function stopSampling(client) {
+    const res = await client.send('Profiler.stop');
+    if (!res?.profile?.nodes) {
+        throw new Error('Profiler.stop returned no profile — the runtime may not be Hermes, or sampling never started');
+    }
+    return res.profile;
+}
+function defaultOut() {
+    return node_path_1.default.join(node_os_1.default.tmpdir(), `js-${new Date().toISOString().replace(/[:.]/g, '-')}.cpuprofile`);
+}
+async function writeProfile(out, profile) {
+    await node_fs_1.promises.mkdir(node_path_1.default.dirname(out), { recursive: true });
+    await node_fs_1.promises.writeFile(out, JSON.stringify(profile));
+}
+function printSummary(summary, out) {
+    console.log(`profile js — ${summary.durationMs}ms, ${summary.sampleCount} samples ` +
+        `(~${summary.medianSampleIntervalMs}ms apart)`);
+    const a = summary.attribution;
+    console.log(`  sampled time:  ${a.namedJsPercent}% named JS  ${a.gcPercent}% GC  ` +
+        `${a.idlePercent}% empty JS stack`);
+    console.log(`\n  ${'self'.padStart(9)} ${'total'.padStart(9)}  ${'%'.padStart(5)}  function`);
+    for (const f of summary.top) {
+        console.log(`  ${`${f.selfMs}ms`.padStart(9)} ${`${f.totalMs}ms`.padStart(9)}  ` +
+            `${f.selfPercent.toFixed(1).padStart(5)}  ${f.name}  ${f.location}`);
+    }
+    if (summary.omitted > 0)
+        console.log(`  ... ${summary.omitted} more (raise --top)`);
+    for (const note of summary.notes)
+        console.log(`\n  note [${note.code}]: ${note.message}`);
+    console.log(`\n  raw profile → ${out}`);
+    console.log('  open it in Chrome DevTools (Performance → Load profile), or convert with ' +
+        '`npx hermes-profile-transformer`.');
+}
+async function profileJsRecord(opts, sessionName, jsOpts) {
+    const out = jsOpts.out ?? defaultOut();
+    let client;
+    try {
+        client = await connect(sessionName, jsOpts);
+        await startSampling(client);
+        await new Promise((r) => setTimeout(r, (jsOpts.durationSec ?? 10) * 1000));
+        const profile = await stopSampling(client);
+        await writeProfile(out, profile);
+        const summary = analyzeCpuProfile(profile, jsOpts.top ?? 20);
+        if (opts.json)
+            (0, output_js_1.printData)({ status: 'ok', out, ...summary }, opts);
+        else
+            printSummary(summary, out);
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`profile js record — ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+    finally {
+        client?.close();
+    }
+}
+// ── start / stop via a detached holder ────────────────────────────────────────
+function stateDir() {
+    return node_path_1.default.join(node_os_1.default.homedir(), '.conductor', 'js-profiles');
+}
+const paths = (session) => ({
+    state: node_path_1.default.join(stateDir(), `${session}.json`),
+    stop: node_path_1.default.join(stateDir(), `${session}.stop`),
+    done: node_path_1.default.join(stateDir(), `${session}.done`),
+});
+async function readJson(file) {
+    try {
+        return JSON.parse(await node_fs_1.promises.readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function profileJsStart(opts, sessionName, jsOpts) {
+    const p = paths(sessionName);
+    await node_fs_1.promises.mkdir(stateDir(), { recursive: true });
+    const existing = await readJson(p.state);
+    if (existing) {
+        (0, output_js_1.printError)(`profile js start — already sampling (holder pid ${existing.pid}, since ${existing.startedAt}). ` +
+            'Run `conductor profile js stop` first.', opts);
+        return 1;
+    }
+    const out = jsOpts.out ?? defaultOut();
+    await node_fs_1.promises.rm(p.stop, { force: true });
+    await node_fs_1.promises.rm(p.done, { force: true });
+    const args = [process.argv[1], 'profile', 'js', '_hold', '--out', out];
+    if (sessionName !== 'default')
+        args.push('--device', sessionName);
+    if (jsOpts.port !== undefined)
+        args.push('--port', String(jsOpts.port));
+    if (jsOpts.targetIndex !== undefined)
+        args.push('--target', String(jsOpts.targetIndex));
+    const child = (0, child_process_1.spawn)(process.execPath, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+    // The holder writes the state file once sampling is actually running, so a
+    // failure to attach surfaces here rather than at `stop`.
+    const deadline = Date.now() + 15000;
+    while (Date.now() < deadline) {
+        const state = await readJson(p.state);
+        if (state) {
+            if (opts.json)
+                (0, output_js_1.printData)({ status: 'ok', ...state }, opts);
+            else
+                (0, output_js_1.printSuccess)(`profile js start — sampling (holder pid ${state.pid})`, opts);
+            return 0;
+        }
+        const done = await readJson(p.done);
+        if (done?.error) {
+            (0, output_js_1.printError)(`profile js start — ${done.error}`, opts);
+            await node_fs_1.promises.rm(p.done, { force: true });
+            return 1;
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    (0, output_js_1.printError)('profile js start — holder did not report back within 15s', opts);
+    return 1;
+}
+async function profileJsStop(opts, sessionName, jsOpts) {
+    const p = paths(sessionName);
+    const state = await readJson(p.state);
+    if (!state) {
+        (0, output_js_1.printError)('profile js stop — not sampling (run `conductor profile js start` first)', opts);
+        return 1;
+    }
+    await node_fs_1.promises.writeFile(p.stop, '');
+    const deadline = Date.now() + 30000;
+    while (Date.now() < deadline) {
+        const done = await readJson(p.done);
+        if (done) {
+            await node_fs_1.promises.rm(p.done, { force: true });
+            await node_fs_1.promises.rm(p.state, { force: true });
+            if (done.error) {
+                (0, output_js_1.printError)(`profile js stop — ${done.error}`, opts);
+                return 1;
+            }
+            const profile = await readJson(done.out);
+            if (!profile) {
+                (0, output_js_1.printError)(`profile js stop — could not read ${done.out}`, opts);
+                return 1;
+            }
+            const summary = analyzeCpuProfile(profile, jsOpts.top ?? 20);
+            if (opts.json)
+                (0, output_js_1.printData)({ status: 'ok', out: done.out, ...summary }, opts);
+            else
+                printSummary(summary, done.out);
+            return 0;
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    (0, output_js_1.printError)('profile js stop — holder did not finish within 30s', opts);
+    return 1;
+}
+/**
+ * Internal: hold the CDP socket open for the duration of a start/stop pair.
+ * Not part of the public CLI surface.
+ */
+async function profileJsHold(sessionName, jsOpts) {
+    const p = paths(sessionName);
+    await node_fs_1.promises.mkdir(stateDir(), { recursive: true });
+    const out = jsOpts.out ?? defaultOut();
+    let client;
+    try {
+        client = await connect(sessionName, jsOpts);
+        await startSampling(client);
+        await node_fs_1.promises.writeFile(p.state, JSON.stringify({ pid: process.pid, session: sessionName, out, startedAt: new Date().toISOString() }, null, 2));
+    }
+    catch (err) {
+        await node_fs_1.promises.writeFile(p.done, JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        client?.close();
+        return 1;
+    }
+    // Safety valve: never hold a debugger session open indefinitely.
+    const deadline = Date.now() + 15 * 60000;
+    let stopped = false;
+    while (Date.now() < deadline) {
+        const stopRequested = await node_fs_1.promises
+            .stat(p.stop)
+            .then(() => true)
+            .catch(() => false);
+        if (stopRequested) {
+            stopped = true;
+            break;
+        }
+        if (!client.isConnected())
+            break;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    try {
+        if (!client.isConnected())
+            throw new Error('the app disconnected from Metro while sampling');
+        const profile = await stopSampling(client);
+        await writeProfile(out, profile);
+        await node_fs_1.promises.writeFile(p.done, JSON.stringify({ out, stoppedByRequest: stopped }));
+        return 0;
+    }
+    catch (err) {
+        await node_fs_1.promises.writeFile(p.done, JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    finally {
+        client?.close();
+        await node_fs_1.promises.rm(p.stop, { force: true });
+        await node_fs_1.promises.rm(p.state, { force: true });
+    }
+}