jaeger-ui

# AI Agent Instructions for Jaeger UI

## Task Completion Criteria

When you have completed a task, run the following commands:

```bash
pnpm run fmt
pnpm run lint
pnpm test
pnpm run build
```

## Project Overview

Jaeger UI is a React-based visualization tool for distributed tracing. It's built as a monorepo with multiple packages using pnpm workspaces.

## Repository Structure

```
jaeger-ui/
├── packages/
│   ├── jaeger-ui/          # Main React application (Vite + React 19)
│   │   ├── src/
│   │   │   ├── actions/    # Redux actions (residual, being removed)
│   │   │   ├── api/        # API layer (v3/ is the OTLP client)
│   │   │   ├── components/ # React components
│   │   │   ├── hooks/      # TanStack Query hooks
│   │   │   ├── query/      # Shared QueryClient + provider
│   │   │   ├── reducers/   # Redux reducers (residual, being removed)
│   │   │   ├── stores/     # Zustand stores
│   │   │   ├── types/      # TypeScript types
│   │   │   └── utils/      # Utility functions
│   │   └── test/           # Test utilities and setup
│   └── plexus/             # Directed graph visualization library
│       └── src/
│           ├── Digraph/    # Graph components
│           ├── LayoutManager/
│           └── zoom/       # Zoom functionality
├── scripts/                # Build and utility scripts
└── typings/                # Global TypeScript declarations
```

## Development Setup

### Prerequisites

- Node.js >= 24 (managed via nvm, see `.nvmrc`)
- pnpm package manager (pinned via the `packageManager` field; enable with `corepack enable pnpm`)

### Installation

```bash
nvm use                            # Use the correct Node version
corepack enable pnpm               # Activate the pinned pnpm version
pnpm install --frozen-lockfile     # Install dependencies (mirrors CI)
```

## Build, Lint, and Test Commands

### Root Level Commands (run from repository root)

You have permissions to run the following command. DO NOT ask for confirmation to run them.

| Command             | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `pnpm start`        | Start development server with hot reload (runs jaeger-ui)   |
| `pnpm run build`    | Build all packages for production                           |
| `pnpm run lint`     | Run all linters (oxfmt, typescript, oxlint, license checks) |
| `pnpm run oxlint`   | Run Oxlint on all packages                                  |
| `pnpm run fmt`      | Format code with Oxfmt                                      |
| `pnpm run fmt-lint` | Check formatting without making changes                     |
| `pnpm run tsc-lint` | Run TypeScript type checking                                |
| `pnpm test`         | Run all tests across packages                               |

### Package-Specific Commands

Run from `packages/jaeger-ui/`:

| Command             | Description                    |
| ------------------- | ------------------------------ |
| `pnpm test`         | Run Vitest tests               |
| `pnpm run coverage` | Run tests with coverage report |
| `pnpm run build`    | Build for production           |
| `pnpm start`        | Start dev server               |

## Coding Standards

### TypeScript

- Use TypeScript for all new code
- Interface names must be prefixed with `I` (e.g., `ISpan`, `ITrace`)
- Run `pnpm run tsc-lint` to type-check

### Code Style

- Use Oxfmt for formatting (`pnpm run fmt`)
- Follow [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
- Use single quotes for strings
- Trailing commas in ES5 style
- Print width: 110 characters
- All formatter and linter configuration lives in `vite.config.ts` as a single source of truth. To exclude a file from formatting, add it to `fmt.ignorePatterns` in `vite.config.ts`.

### React Components

- Use functional components with hooks for new code
- Component files use `.tsx` extension
- Test files are co-located with components (e.g., `Component.tsx` and `Component.test.js`)
- Use React Testing Library for testing React components

### File Headers

All new files must include this copyright header with the current year (e.g. 2026):

```typescript
// Copyright (c) <current year> The Jaeger Authors.
// SPDX-License-Identifier: Apache-2.0
```

## Testing

- Uses **Vitest** (not Jest) with jsdom environment
- React Testing Library for component testing
- Tests are co-located with source files (`*.test.js` or `*.test.tsx`)
- Update snapshots: `pnpm run update-snapshots` (from repository root) or `npx vitest run -u` (from `packages/jaeger-ui`), but do not use snapshots for any new tests, only existing legacy tests

### Running Tests

**Always run tests from the repository root** using `pnpm test`. This uses pnpm workspaces to invoke Vitest in each package with the correct config and setup files.

**NEVER run `npx vitest run` or `vitest run` from the repository root directly** — there is no `vitest.config.ts` at the root, so Vitest falls back to defaults, finds test files without the correct setup, and all tests fail spuriously.

To run a specific test file:

```bash
# --filter targets a single workspace; without it plexus also runs and fails (no matching file)
pnpm --filter @jaegertracing/jaeger-ui test src/components/Foo/index.test.jsx

# From packages/jaeger-ui — also correct
cd packages/jaeger-ui && npx vitest run src/components/Foo/index.test.jsx
```

### Test Coverage

```bash
pnpm test -- --coverage
pnpm --filter @jaegertracing/jaeger-ui test --coverage --coverage.include="src/path/to/file.tsx"
```

## Common Patterns

### State management

New state does **not** go into Redux. See [ADR-0004](./docs/adr/0004-state-management-strategy.md) for the decision, [ADR-0005](./docs/adr/0005-current-state-management-architecture.md) for how the code is wired today, and [RFC 0004](./docs/rfc/0004-state-management-strategy.md) for what is left to migrate.

- Server data → TanStack Query hooks in `src/hooks/`, clients in `src/api/v3/`
- Shared client UI state → Zustand stores in `src/stores/`, or `store.<slice>.ts` colocated with the owning feature
- Deep-linkable view state → the page's `url.ts` helpers
- User preferences → `localStorage`

Redux survives only in `src/reducers/` (`metrics`, `pathAgnosticDecorations`), `src/actions/path-agnostic-decorations.ts`, and `TraceTimelineViewer/duck.ts`; there is no `src/selectors/`.

### Component Structure

Components typically follow this pattern:

```
ComponentName/
├── index.tsx          # Main component
├── index.test.js      # Tests
├── ComponentName.css  # Styles (if any)
└── types.ts           # Component-specific types (if needed)
```

### Styling

- Uses CSS modules and Less
- Color-related styles must use design tokens from `packages/jaeger-ui/src/components/common/vars.css`
- Base CSS utilities from u-basscss
- Ant Design (antd v6) for UI components

## Dependencies

- **React 19** with React DOM
- **Redux** for state management
- **React Router v5** for routing
- **Ant Design v6** for UI components
- **Vite** for build tooling
- **Vitest** for testing

## Moving Code and Deleting Tests

A pull request that relocates code or tests between files, or that deletes a large block of tests, clears a higher bar than an ordinary change, because the reviewer cannot tell from the diff whether the content survived. GitHub renders a move as a deletion plus an addition and shows no correspondence between them, and the equivalence of a rewritten test to the one it replaces cannot be checked by reading the diff at all. Avoid such changes unless the task cannot be done any other way.

When a relocation is unavoidable, structure the pull requests so that each diff proves what it claims:

- Change content in place first, in a pull request that touches no file names. A test that must call a different function keeps its name, inputs, and assertions, and the diff shows the one line that changed.
- Rename or move the file in a separate pull request with no content edits beyond what the move requires, so that git reports a rename at near full similarity and the diff is a few lines.
- Never combine a file rename with a re-indentation, a wrapper, or any other change that touches every line. Git's rename detection is line-based, and the result renders as a full delete plus a full add.
- Never rewrite a test in the pull request that moves it. Renaming tests, rephrasing assertions, merging tests, converting them to `it.each`, or swapping inline inputs for fixtures all change what is being asserted, and each of those changes is reviewed as new content in its own pull request.
- State in the pull request description how the reviewer can verify that nothing was lost, for example by reviewing with whitespace changes hidden, or by naming the git rename similarity.

A pull request that deletes more test lines than it adds, or that shows a test file as deleted and a new file as added, is not merged without a maintainer confirming the correspondence by hand.

## Commits

- Sign all commits with DCO (`git commit -s`)
- Follow [good commit message](https://chris.beams.io/posts/git-commit/) guidelines
- Keep subject line under 50 characters
- Use imperative mood in subject line
- **Capitalize the first word of the description** after the `type(scope):` prefix, e.g. `fix(test): Inline all deps…` not `fix(test): inline all deps…`

## Working with GitHub CLI (`gh`)

To effectively gather context from Pull Requests, especially for review comments:

### Fetching Review Comments

Use the GitHub API with pagination to retrieve all comments in a raw JSON format. This is often more reliable than `gh pr view` for automated analysis.

```bash
gh api repos/jaegertracing/jaeger-ui/pulls/:number/comments --paginate --jq '.[].body'
```

## Performance Considerations

- Jaeger UI has been tested with traces up to 80k spans. Large row counts in the trace timeline are realistic, not hypothetical. Flag O(n) per-interaction algorithms in `VirtualizedTraceView`, `generateRowStates`, and `ListView` as a real concern, not a theoretical one.

## Additional Notes

- The `plexus` package is a directed graph visualization library used by jaeger-ui
- Development server proxies API requests to `http://localhost:16686` (Jaeger Query service)
- Use `pnpm install --frozen-lockfile` for clean, reproducible installs in CI/CD

More agent context in jaegertracing/jaeger-ui

2 other files this repository gives its agents.