Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ trace-engine-cli --help

| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `-f, --format` | `'toon' \| 'md'` | `'toon'` | Output serialization format (`toon` or `md`) |
| `-f, --format` | `'toon' \| 'md' \| 'json'` | `'toon'` | Output serialization format |
| `--time-range` | `string` | — | Filter window relative to trace start (e.g. `"3500,4200"`, `"3.5s,4.2s"`, `"100ms-500ms"`) |
| `--absolute-timestamps` | `boolean` | `false` | Treat time ranges as raw absolute trace timestamps rather than relative to trace start |
| `--trace-engine`| `string` | — | Path to a custom DevTools trace engine bundle |
Expand Down Expand Up @@ -513,6 +513,14 @@ trace-engine-cli scan fixtures/ --name TracingStartedInBrowser --fields args.dat
### Markdown (`--format md`)
Generates standard GitHub Flavored Markdown (GFM) tables and summary headings, ideal for terminal viewing or pasting into PR descriptions.

### JSON (`--format json`)
Prints the command result as JSON for scripts and automations. The default
overview omits its drill-down footer in this format.

```bash
trace-engine-cli overview trace.json.gz --format json | jq '.mainThreadBreakdown.scriptingMs'
```

---

## Bundling Local DevTools Trace Engine
Expand Down
36 changes: 19 additions & 17 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,11 @@ import { extractScheduling } from './engine/extractors/scheduling.js';
import { extractShifts } from './engine/extractors/shifts.js';
import { extractTasks } from './engine/extractors/tasks.js';
import { loadTraceFromFile } from './engine/loader.js';
import { formatResult } from './formatters/index.js';
import { type FormatOptions, formatResult } from './formatters/index.js';
import { parseTimeRange, parseTimeValue, resolveTimeRange } from './utils/filter.js';

const DEFAULT_OUTPUT_FORMAT: FormatOptions['format'] = 'toon';

/**
* Splits a comma-separated argument into trimmed, non-empty tokens.
*/
Expand All @@ -52,9 +54,9 @@ export async function runCli(argv: string[]): Promise<void> {
.option('format', {
alias: 'f',
type: 'string',
choices: ['toon', 'md'] as const,
default: 'toon',
describe: 'Output format (toon or md)',
choices: ['toon', 'md', 'json'] satisfies FormatOptions['format'][],
default: DEFAULT_OUTPUT_FORMAT,
describe: 'Output format (toon, md, or json)',
})
.option('trace-engine', {
type: 'string',
Expand Down Expand Up @@ -95,7 +97,7 @@ export async function runCli(argv: string[]): Promise<void> {
const isDefaultCmd = !args._.includes('overview');
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'overview',
includeHint: isDefaultCmd,
}),
Expand Down Expand Up @@ -139,7 +141,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'insights',
}),
);
Expand Down Expand Up @@ -191,7 +193,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'tasks',
}),
);
Expand Down Expand Up @@ -237,7 +239,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'find',
}),
);
Expand Down Expand Up @@ -283,7 +285,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'profile',
}),
);
Expand Down Expand Up @@ -341,7 +343,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'diff',
}),
);
Expand Down Expand Up @@ -370,7 +372,7 @@ export async function runCli(argv: string[]): Promise<void> {
const result = extractScheduling(loaded, { timeRange });
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'scheduling',
}),
);
Expand Down Expand Up @@ -421,7 +423,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'network',
}),
);
Expand Down Expand Up @@ -450,7 +452,7 @@ export async function runCli(argv: string[]): Promise<void> {
const result = extractInteractions(loaded, { timeRange });
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'interactions',
}),
);
Expand Down Expand Up @@ -488,7 +490,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'shifts',
}),
);
Expand Down Expand Up @@ -554,7 +556,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'events',
}),
);
Expand All @@ -577,7 +579,7 @@ export async function runCli(argv: string[]): Promise<void> {
const result = extractNavigations(loaded);
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'navigations',
}),
);
Expand Down Expand Up @@ -642,7 +644,7 @@ export async function runCli(argv: string[]): Promise<void> {
});
console.log(
formatResult(result, {
format: args.format as 'toon' | 'md',
format: args.format,
type: 'scan',
}),
);
Expand Down
4 changes: 3 additions & 1 deletion src/formatters/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import { formatMarkdown } from './markdown.js';
import { formatToon } from './toon.js';

export interface FormatOptions {
format: 'toon' | 'md';
format: 'toon' | 'md' | 'json';
type?:
| 'overview'
| 'insights'
Expand Down Expand Up @@ -72,6 +72,8 @@ const NEXT_STEPS_HINT_MD = `
`.trim();

export function formatResult(data: unknown, options: FormatOptions): string {
if (options.format === 'json') return JSON.stringify(data, null, 2);

let output = '';
if (options.format === 'md') {
output = formatMarkdown(data, options.type);
Expand Down
10 changes: 10 additions & 0 deletions test/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,16 @@ async function captureCliOutput(args: string[]): Promise<string> {
}

describe('CLI Dispatcher', () => {
test('emits parseable JSON from the default overview command', async () => {
const fixture = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json');
const args = ['node', 'trace-engine-cli', fixture, '--format', 'json'];
const output = await captureCliOutput(args);
const result: unknown = JSON.parse(output);

assert.ok(result && typeof result === 'object' && 'mainUrl' in result);
assert.equal(result.mainUrl, 'https://example.com/test');
});

test('runs overview command by default for a trace file', async () => {
const fixturePath = path.resolve(import.meta.dirname, 'fixtures/basic-trace.json');
const output = await captureCliOutput(['node', 'trace-engine-cli', fixturePath]);
Expand Down