Artifact Structure Mismatch Detection

[0xisk]

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

1. 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"]
   }

2. Structure mismatch detection: On compile, read the manifest and compare with current options.

3. 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)
   

4. Non-interactive mode: Add --force flag to auto-confirm deletion (for CI/CD).

5. 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)

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

🔗 Similar Issues

Related Issues

• OpenZeppelin/compact-contracts#185
• OpenZeppelin/compact-tools#32
• OpenZeppelin/compact-contracts#275
• OpenZeppelin/compact-tools#30

🔗 Related PRs

OpenZeppelin/compact-contracts#284 - fix(gh-actions): release PR requisted changes [merged]
OpenZeppelin/compact-contracts#285 - Update Compact Tooling and Tests to 0.26.0, Update CHANGELOG and README [merged]
OpenZeppelin/compact-contracts#309 - Update contracts package name [merged]
OpenZeppelin/compact-contracts#317 - Fix prep release and release [merged]

👤 Suggested Assignees

• 0xisk
• emnul
• andrew-fleming
• AndrewWestberg

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false