125 lines
6.7 KiB
Markdown
125 lines
6.7 KiB
Markdown
---
|
|
id: PLN-0010
|
|
ticket: compiler-analyze-compile-build-pipeline-split
|
|
title: Refactor BuilderPipelineService into explicit analyze, compile, and build entrypoints
|
|
status: done
|
|
created: 2026-03-30
|
|
completed: 2026-03-30
|
|
tags:
|
|
- compiler
|
|
- pipeline
|
|
- implementation
|
|
- api
|
|
---
|
|
|
|
## Objective
|
|
|
|
Implement the canonical pipeline entrypoints from DEC-0007 in `prometeu-build-pipeline`, replacing the monolithic public `run` surface with explicit `analyze`, `compile`, and `build` operations.
|
|
|
|
## Background
|
|
|
|
The current `BuilderPipelineService` exposes one public `run(config, logs)` entrypoint and internally constructs a filesystem-anchored `BuilderPipelineContext`.
|
|
|
|
DEC-0007 requires:
|
|
1. one canonical pipeline with fixed stage ordering,
|
|
2. `analyze`, `compile`, and `build` as explicit public entrypoints,
|
|
3. stable result contracts rather than leaking `BuilderPipelineContext`,
|
|
4. filesystem-default context construction outside the pipeline itself.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Refactor `BuilderPipelineService` public API to explicit entrypoints.
|
|
- Introduce stable result models for `analyze`, `compile`, and `build`.
|
|
- Refactor context/config construction so filesystem-default composition is no longer hardcoded inside the pipeline service.
|
|
- Keep the canonical stage ordering unchanged.
|
|
|
|
### Excluded
|
|
- Updating downstream callsites and tests outside the core pipeline module.
|
|
- Editor/LSP-specific consumers beyond the generic context/config model.
|
|
- Housekeeping deletion of historical docs or discussion artifacts.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Introduce explicit result contracts
|
|
|
|
**What:** Add stable result types for each public entrypoint so the service no longer exposes `BuilderPipelineContext` as the external contract.
|
|
**How:** Define result models with the minimum DEC-0007 requirements:
|
|
1. `AnalysisSnapshot` or equivalent for `analyze`,
|
|
2. an in-memory compile result carrying validated executable artifacts for `compile`,
|
|
3. a build result carrying the persisted artifact location and compile payload for `build`.
|
|
Keep internal mutable pipeline state in `BuilderPipelineContext`, but add explicit adapters from context to public result objects.
|
|
**File(s):**
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/BuilderPipelineContext.java`
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/messages/`
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/`
|
|
|
|
### Step 2 - Split service entrypoints by terminal stage
|
|
|
|
**What:** Refactor `BuilderPipelineService` so each public entrypoint stops at the DEC-0007 terminal stage.
|
|
**How:** Replace the public `run` flow with explicit methods that execute the same canonical stage list through bounded terminal stages:
|
|
1. `analyze` stops after `FrontendPhasePipelineStage`,
|
|
2. `compile` stops after `VerifyBytecodePipelineStage`,
|
|
3. `build` stops after `WriteBytecodeArtifactPipelineStage`.
|
|
Use one shared stage execution helper so the implementation does not fork stage order or error handling logic across entrypoints.
|
|
**File(s):**
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java`
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/PipelineStage.java`
|
|
|
|
### Step 3 - Externalize context construction
|
|
|
|
**What:** Remove the implicit filesystem-default context construction from inside the pipeline service.
|
|
**How:** Refactor `BuilderPipelineContext.compilerContext(...)` and surrounding config flow so entrypoints receive the context/config composition required for their caller.
|
|
Preserve filesystem support, but move its construction into explicit factories or caller-side composition helpers rather than hardcoding it as the only pipeline-owned mode.
|
|
**File(s):**
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/BuilderPipelineContext.java`
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/messages/BuilderPipelineConfig.java`
|
|
- `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/utilities/SourceProviderFactory.java`
|
|
|
|
### Step 4 - Keep canonical stage behavior intact
|
|
|
|
**What:** Ensure the refactor preserves the semantic order and gating behavior of the current executable pipeline.
|
|
**How:** Keep the stage order fixed, preserve current error propagation, and ensure `compile` still covers lowering, optimization, emission, link precheck, and verification before any build-specific artifact write occurs.
|
|
**File(s):**
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java`
|
|
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/*.java`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- Add service-level tests proving each entrypoint stops at its required terminal stage.
|
|
- Add tests proving `analyze` produces the minimum snapshot contract and does not populate backend artifact outputs.
|
|
- Add tests proving `compile` returns validated in-memory artifacts without writing to disk.
|
|
- Add tests proving `build` extends `compile` only with artifact persistence.
|
|
|
|
### Integration Tests
|
|
|
|
- Preserve or replace the existing end-to-end pipeline integration coverage with explicit `build`-based integration tests.
|
|
- Add an integration test that exercises `compile` against a real project root and asserts no artifact file is written.
|
|
|
|
### Manual Verification
|
|
|
|
- Inspect the public API of `BuilderPipelineService` to confirm `run` is gone.
|
|
- Verify the default filesystem composition is not hardcoded as the only context path inside the service.
|
|
- Verify stage order remains unchanged from DEC-0007.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `BuilderPipelineService` exposes explicit `analyze`, `compile`, and `build` entrypoints and no longer exposes public `run`.
|
|
- [ ] Public result types exist and `BuilderPipelineContext` is no longer the external contract.
|
|
- [ ] `analyze`, `compile`, and `build` stop exactly at the DEC-0007 terminal stages.
|
|
- [ ] Filesystem-default behavior is still supported but is composed outside the pipeline core.
|
|
- [ ] The canonical executable path preserves current PBS-facing correctness through emit, link, and verify.
|
|
|
|
## Dependencies
|
|
|
|
- PLN-0009 should land first or in parallel if the spec wording is stable.
|
|
- No downstream callsite migration should begin until the new entrypoints and result models exist.
|
|
|
|
## Risks
|
|
|
|
- Refactoring context ownership without a clear composition boundary can accidentally leave filesystem behavior embedded in the service.
|
|
- Result models that mirror the mutable context too closely will leak internal implementation details back into the public API.
|
|
- If stage slicing is duplicated per method instead of shared, drift between `compile` and `build` can reappear immediately.
|