---
id: PLN-0011
ticket: compiler-analyze-compile-build-pipeline-split
title: Migrate compiler callsites and tests to explicit build, compile, and analyze entrypoints
status: done
created: 2026-03-30
completed: 2026-03-30
tags:
  - compiler
  - pipeline
  - migration
  - tests
---

## Objective

Migrate existing compiler callsites and test coverage away from `run` so the codebase consumes the DEC-0007 entrypoints explicitly and preserves current filesystem build behavior under `build`.

## Background

The current public caller in `prometeu-build-pipeline` is `Compile.main`, which constructs `BuilderPipelineConfig` and calls `BuilderPipelineService.INSTANCE.run(...)`.

The test suite also includes service-level and integration coverage that still assumes a monolithic `run` entrypoint or a filesystem-default context built inside the pipeline service.

DEC-0007 requires the default behavior to survive as `build`, with filesystem context composed outside the pipeline itself.

## Scope

### Included
- Replace production and test callsites that invoke the old `run` entrypoint.
- Preserve current CLI/default build behavior under explicit `build`.
- Add regression tests for side-effect boundaries between `analyze`, `compile`, and `build`.

### Excluded
- The core service refactor itself.
- Language/frontend-specific editor or LSP consumers that do not yet exist in this codebase.
- Spec writing beyond what is covered in PLN-0009.

## Execution Steps

### Step 1 - Migrate the default CLI/build caller

**What:** Update the current compiler entrypoint so it performs an explicit `build` call rather than a generic `run`.
**How:** Refactor `Compile.main` and any supporting composition helpers so the default filesystem-oriented config/context is assembled before invoking `build`.
Keep the effective behavior identical to the current default run mode.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/Compile.java`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/messages/BuilderPipelineConfig.java`

### Step 2 - Replace legacy service consumers in tests

**What:** Update all service-level and integration tests that still call `BuilderPipelineService.INSTANCE.run(...)`.
**How:** Rewrite tests to target the explicit entrypoint they actually mean:
1. end-to-end artifact production tests use `build`,
2. in-memory executable tests use `compile`,
3. analysis-only tests use `analyze`.
Where the old tests only asserted canonical stage order or successful artifact write, preserve the same behavior under the new API names.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/integration/MainProjectPipelineIntegrationTest.java`
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/workspaces/BuilderPipelineServiceOrderTest.java`
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/workspaces/**/*.java`

### Step 3 - Add regression coverage for side-effect boundaries

**What:** Add explicit regression tests that enforce the no-write guarantees and terminal-stage boundaries required by DEC-0007.
**How:** Add tests that prove:
1. `analyze` does not execute backend artifact stages,
2. `compile` does not write `build/program.pbx`,
3. `build` writes the artifact and preserves current filesystem behavior,
4. removal of `run` does not reduce PBS-facing executable correctness.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/integration/`
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/workspaces/`

## Test Requirements

### Unit Tests

- Update any unit tests that instantiate the service or reason about stage execution to use explicit entrypoints.
- Add focused assertions for entrypoint-specific side effects and outputs.

### Integration Tests

- Preserve the existing artifact-producing integration behavior under `build`.
- Add at least one integration path that exercises `compile` and asserts artifact absence on disk.
- Add at least one analysis path that exercises `analyze` and verifies the minimum snapshot contract.

### Manual Verification

- Confirm there are no remaining production uses of `BuilderPipelineService.INSTANCE.run(...)`.
- Confirm the default CLI path still writes the expected artifact to the same build location.
- Confirm integration coverage still protects the PBS executable path.

## Acceptance Criteria

- [ ] No production callsite still invokes public `run`.
- [ ] Existing default filesystem behavior is preserved under explicit `build`.
- [ ] Tests explicitly distinguish `analyze`, `compile`, and `build`.
- [ ] Regression coverage exists for the no-write boundary of `compile` and the no-backend boundary of `analyze`.
- [ ] The migrated test suite still protects PBS-facing executable correctness.

## Dependencies

- PLN-0010 must land first because the new public entrypoints and result contracts must exist before callsite migration.
- PLN-0009 should land before or alongside this plan so naming and contracts match the normative docs.

## Risks

- Test migration can accidentally preserve old semantics by mechanically renaming `run` without asserting the new side-effect boundaries.
- If the CLI/default caller keeps assembling filesystem behavior inside the pipeline service, DEC-0007 will be implemented only nominally.
- Weak regression coverage here would allow `compile` and `build` to drift again after the refactor.