112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
---
|
|
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.
|