Artifact Structure Mismatch Detection

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

Originally posted by @andrew-fleming in https://github.com/OpenZeppelin/compact-tools/pull/27#discussion_r2607997472

Start by reading types/manifest.ts, Compiler.ts, parseArgs, and runCompiler.ts to trace artifact output and argument handling. Review the existing tests and README sections related to compilation and options before defining the manifest and prompt behavior. Done means structure mismatches are detected, interactive and --force flows are covered by tests, and the new behavior is documented.