Problem
When switching between --hierarchical and flattened (default) artifact structures, stale artifacts from the previous structure remain in the output directory:
# First compile (flattened)
compact-compiler
# artifacts/AccessControl/
# artifacts/Token/
# Later, switch to hierarchical
compact-compiler --hierarchical
# artifacts/AccessControl/ ← STALE
# artifacts/Token/ ← STALE
# artifacts/access/AccessControl/ ← current
# artifacts/token/Token/ ← current
This can cause:
- Import confusion (wrong artifact path)
- Inflated artifact directory size
- Test failures from stale artifacts
Proposed Solution
-
Artifact manifest file (.compact-manifest.json) in the output directory:
{
"structure": "flattened",
"toolchainVersion": "0.26.0",
"createdAt": "2025-12-11T15:30:00Z",
"artifacts": ["AccessControl", "Token"]
}
-
Structure mismatch detection: On compile, read the manifest and compare with current options.
-
Interactive prompt when structure differs:
⚠ [COMPILE] Existing artifacts use "flattened" structure.
⚠ [COMPILE] You are compiling with "hierarchical" structure.
? Delete existing artifacts and recompile? (y/N)
-
Non-interactive mode: Add --force flag to auto-confirm deletion (for CI/CD).
-
Same structure = no prompt: If structure matches, proceed normally (overwrite in-place).
Implementation
| Component |
Changes |
types/manifest.ts |
New ArtifactManifest interface |
Compiler.ts |
Read/write manifest, detect mismatch |
parseArgs |
Add --force flag |
runCompiler.ts |
Handle interactive prompt (readline) |
| Tests |
Manifest read/write, mismatch detection, prompt behavior |
| README |
Document new behavior and --force flag |
Originally posted by @andrew-fleming in #27 (comment)
Problem
When switching between
--hierarchicaland flattened (default) artifact structures, stale artifacts from the previous structure remain in the output directory:This can cause:
Proposed Solution
Artifact manifest file (
.compact-manifest.json) in the output directory:{ "structure": "flattened", "toolchainVersion": "0.26.0", "createdAt": "2025-12-11T15:30:00Z", "artifacts": ["AccessControl", "Token"] }Structure mismatch detection: On compile, read the manifest and compare with current options.
Interactive prompt when structure differs:
Non-interactive mode: Add
--forceflag to auto-confirm deletion (for CI/CD).Same structure = no prompt: If structure matches, proceed normally (overwrite in-place).
Implementation
types/manifest.tsArtifactManifestinterfaceCompiler.tsparseArgs--forceflagrunCompiler.ts--forceflagOriginally posted by @andrew-fleming in #27 (comment)