# @affectively/trace-lint

[Parent README](../README.md) | [Source README](./src/README.md)

Extensible linting framework for Chrome/DevTools trace files (`.json` and `.json.gz`).

It is designed for repeated runtime diagnostics and CI gating with a three-layer governance model:

- `constraint`: non-negotiable failures (system truths).
- `boundary`: team-held discipline and runtime guardrails.
- `expectation`: directional pressure and optimization goals.

## Installation

```bash
npm install @affectively/trace-lint
# or
bun add @affectively/trace-lint
```

## CLI Usage

```bash
trace-lint ./Trace-20260226T221208.json.gz
```

Lint the newest trace in `~/Downloads` automatically:

```bash
trace-lint --latest
```

Lint the newest trace from a specific directory:

```bash
trace-lint --latest --trace-dir ~/Downloads
```

Capture a new trace from a URL for a fixed window, then lint it:

```bash
trace-lint --capture-url https://example.com --capture-seconds 10
```

Capture to a specific folder as plain `.json` (no gzip):

```bash
trace-lint --capture-url https://example.com --capture-seconds 8 --capture-dir ~/Downloads --capture-json
```

Filter to one rule and fail CI on warnings:

```bash
trace-lint ./trace.json.gz \
  --rule repeated-async-task-loop \
  --fail-on warn
```

JSON output:

```bash
trace-lint ./trace.json.gz --json > trace-lint-report.json
```

Agent-mitigation JSON output (includes objective/actions/verification per finding):

```bash
trace-lint ./trace.json.gz --json --detail-mode agent > trace-lint-agent-report.json
```

Forensics output for deeper automation/debugging:

```bash
trace-lint ./trace.json.gz --json --detail-mode forensics > trace-lint-forensics.json
```

Run through the repo script:

```bash
bun run trace:lint ./trace.json.gz --fail-on warn
```

Latest-trace script shortcut:

```bash
bun run trace:lint:latest --fail-on warn
```

Capture-and-lint script shortcut:

```bash
bun run trace:lint:capture --capture-url https://example.com --capture-seconds 10 --fail-on warn
```

Nx target equivalents:

```bash
bun nx run trace-lint:run -- ./trace.json.gz --fail-on warn
bun nx run trace-lint:latest -- --fail-on warn
bun nx run trace-lint:capture -- --capture-url https://example.com --capture-seconds 10 --fail-on warn
```

Jank-focused run with strict dropped-frame policy:

```bash
trace-lint ./trace.json.gz \
  --allowed-dropped-frames 0 \
  --frame-budget-ms 16.7 \
  --max-frame-overrun-ratio 0.03 \
  --long-task-threshold-ms 50 \
  --max-main-thread-long-tasks 0 \
  --fail-on warn
```

## API Usage

```ts
import { loadTraceFile, runTraceLint, defaultTraceLintRules } from '@affectively/trace-lint';
import type { TraceLintRule } from '@affectively/trace-lint';

const customRule: TraceLintRule = {
  id: 'my-custom-rule',
  layer: 'expectation',
  description: 'Example custom rule',
  defaultSeverity: 'info',
  check: ({ stats }) => {
    const timerFires = stats.eventNameCounts.get('TimerFire') ?? 0;
    if (timerFires < 200) return [];
    return [
      {
        ruleId: 'my-custom-rule',
        layer: 'expectation',
        severity: 'info',
        message: `High TimerFire activity: ${timerFires}`,
      },
    ];
  },
};

const trace = loadTraceFile('./trace.json.gz');
const composed = runTraceLint(trace, undefined, [
  ...defaultTraceLintRules,
  customRule,
]);
console.log(composed.findings.length);
```

## Built-In Rules

- `no-dropped-frames` (`constraint`) - fails when dropped frames exceed allowed threshold.
- `frame-budget-jank` (`boundary`) - checks BeginFrame cadence overrun ratio.
- `main-thread-long-task-jank` (`boundary`) - checks long `RunTask` volume on renderer main.
- `renderer-main-boundary-bleed` (`boundary`) - flags heavy parse/layout/script work on renderer main.
- `parse-compile-budget` (`expectation`) - tracks total parse+compile cost against budget.
- `repeated-async-task-loop` (`boundary`) - recurring async schedule loops.
- `repeated-resource-request-loop` (`expectation`) - stable request polling loops.
- `timer-fire-loop` (`boundary`) - regular timer cadence loops.

## CI Integration

This repository includes a reusable workflow at:

- [`/.github/workflows/trace-lint.yml`](../../.github/workflows/trace-lint.yml)

It supports `workflow_call`, manual dispatch, and PR-triggered linting for trace-like files.

## Development

```bash
cd open-source/trace-lint
bun run type-check
bun run build
```