Bazel Monorepo Build Analyzer

A specialized skill for analyzing Bazel monorepo build performance using Zhongkui (钟馗), a local build analysis tool that identifies build hotspots through profile analysis, diff analysis, and dependency correlation.

What This Skill Does

This skill helps you work with the Zhongkui tool to:

Key Capabilities

1. **Profile-Based Analysis**: Parse standard Bazel profile files generated with `--profile` flag

2. **Pure Local Operation**: Works entirely offline without BEP infrastructure

3. **Smart Attribution**: Distributes build time only to packages that caused changes (no double-counting)

4. **Dependency Tracking**: Uses `bazel query` for accurate target-to-package mapping

5. **Impact Prediction**: Static analysis to predict build impact before building

Instructions

Understanding the Architecture

When working with Zhongkui code, understand the modular structure:

1. **`src/profile/`** - Bazel profile JSON parsing and action extraction

2. **`src/bazel/`** - Bazel query integration for target-to-package mapping

3. **`src/diff/`** - File change analysis and package mapping

4. **`src/dependency/`** - Action-to-package correlation and time distribution

5. **`src/hotspot/`** - Report generation

6. **`src/utils/`** - Shared utilities (logging, etc.)

**Data Flow**: ProfileAnalyzer → DiffAnalyzer → BazelQuery → DependencyAnalyzer → HotspotReporter

Working with Bazel Build System

The project uses **Bazel with rules_js**. Key commands:

```bash

Build the project

bazel build //src:zhongkui

bazel build //... # All targets

Run the CLI

bazel run //src:zhongkui -- [args]

Setup VSCode IntelliSense (run when dependencies change)

./setup-vscode.sh

Linting and type checking (legacy npm scripts)

npm run lint

npm run lint:fix

npm run typecheck

```

**Key Files**:

Running Analysis Commands

**Method 1: Analyze Existing Profile**

```bash

bazel build --profile=profile.json //src/...

bazel run //src:zhongkui -- analyze -p profile.json -t "//src/..." -r /path/to/repo

```

**Method 2: Run and Analyze (Recommended)**

```bash

bazel run //src:zhongkui -- run-and-analyze -c "bazel build //src/..."

```

**Method 3: Predict Impact (Fastest, No Build)**

```bash

bazel run //src:zhongkui -- predict-impact -c "bazel build //src/..."

```

**Advanced Example**:

```bash

bazel run //src:zhongkui -- run-and-analyze \

-c "bazel test //app:* --config=ci --keep_going" \

--keep-profile \

--base-branch origin/main

```

**Output Files**:

Key Implementation Concepts

**Profile Parsing**:

**Bazel Query Integration** (`BazelQuery` class):

**Attribution Algorithm** (Two-Tier Process):

1. **Direct Attribution**: Actions in changed packages get full duration

2. **Transitive Attribution**: Actions in dependent packages recorded but duration attributed to changed packages only

3. **Pure Attribution**: Total attributed time = actual build time (no double-counting)

**External Repository Support**:

Development Guidelines

**When Adding Features**:

1. Follow modular architecture - new functionality should fit into existing modules

2. Profile parsing must handle Chrome Tracing format correctly

3. Always scope `bazel query` commands to target patterns for performance

4. Maintain pure attribution logic - no double-counting of build time

5. Add unit tests for core algorithms (dependency analysis, time distribution)

**Key Types** (in `src/types.ts`):

**Testing Strategy**:

Common Tasks

**Adding New Analysis Features**:

1. Identify which module owns the logic (profile/diff/dependency/hotspot)

2. Update types in `src/types.ts` if needed

3. Implement feature following pure attribution principles

4. Ensure Bazel query scoping is correct

5. Update report generation in `src/hotspot/`

**Debugging Profile Parsing Issues**:

1. Check Chrome Tracing format compliance

2. Verify action event extraction (`cat: "action"`, `ph: "X"`)

3. Validate target regex patterns

4. Check timestamp conversion (microseconds → milliseconds)

**Optimizing Performance**:

1. Review Bazel query caching in `BazelQuery` class

2. Scope queries to target patterns to avoid full monorepo analysis

3. Profile large monorepo scenarios

4. Consider incremental analysis for repeated runs

Future Implementation Areas

Production readiness TODOs:

1. **Bazel Build Integration**: Add proper test targets and execution

2. **BUILD File Detection**: Replace stub package detection with actual BUILD parsing

3. **Performance Optimization**: Add caching and incremental analysis for large profiles

4. **Profile Validation**: Validate profile completeness and data quality

5. **Output Format Options**: Support additional formats for data product integrations

Important Notes

Usage Examples

**Analyze recent build performance**:

```bash

bazel run //src:zhongkui -- run-and-analyze -c "bazel build //app/..."

```

**Predict impact of current changes**:

```bash

bazel run //src:zhongkui -- predict-impact -c "bazel build //..." --base-branch origin/main

```

**Setup development environment**:

```bash

./setup-vscode.sh

bazel build //...

npm run typecheck

```

Constraints