Skip to content

[Feature] Document the 6-phase Stylus code validation architecture #24

@ajeelll

Description

@ajeelll

Is this related to a problem?
The Stylus code validator applies 6 phases of fixes across 50+ regex patterns. This logic exists in both Python (_fix_code() in generate_stylus_code.py) and TypeScript (validateAndFixCode() in generateStylusCode.ts). New contributors find it overwhelming and don't know how to add new fixes without breaking existing ones.

Describe the feature
Create docs/STYLUS_CODE_VALIDATION.md documenting:

  1. Overview — why validation exists, the 6 phases, the cargo check backstop
  2. Phase descriptions — what each phase fixes, with before/after examples
  3. Python vs TypeScript differences — Python has cargo check (some fixes "moved to cargo check"); TS has all fixes active
  4. How to add a new fix — step-by-step guide with naming convention (Fix 40, 41, etc.)
  5. Error guidance mapping — table of Rust error codes → fix strategies
  6. Common pitfalls — e.g., Fix 41 (underscore functions), Fix 47 (getter chains)

Which module does this relate to?

  • M1: Stylus (contracts, tests, compilation)

Example usage

## Phase 3: Storage Accessors

Fixes incorrect storage read/write patterns in sol_storage! fields.

| Fix # | Pattern | Before | After |
|-------|---------|--------|-------|
| 34 | String mapping read | `.get(k)` on string field | `.getter(k).get_string()` |
| 43 | Double setter | `.setter(k).setter().set_str()` | `.setter(k).set_str()` |
| 45 | Nested struct write | `.get(k).field.setter()` | `.setter(k).field.setter()` |

Additional context

  • Python: src/mcp/tools/generate_stylus_code.py (search for _fix_phase_)
  • TypeScript: apps/web/src/lib/tools/generateStylusCode.ts (search for Phase)
  • src/utils/compiler_verifier.py has the ERROR_GUIDANCE dict

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions