prometeu-studio/discussion/workflow/plans/PLN-0011-migrate-callsites-and-tests-to-build-compile-analyze.md

id	ticket	title	status	created	completed	tags
PLN-0011	compiler-analyze-compile-build-pipeline-split	Migrate compiler callsites and tests to explicit build, compile, and analyze entrypoints	review	2026-03-30		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.