move-code-quality

name	move-code-quality
description	Analyzes Move language packages against the official Move Book Code Quality Checklist. Use this skill when reviewing Move code, checking Move 2024 Edition compliance, or analyzing Move packages for best practices. Activates automatically when working with .move files or Move.toml manifests.

Move Code Quality Checker

Doc-First Requirement: Before generating recommendations or code fixes, verify current patterns against the sui-pilot documentation (.move-book-docs/, .sui-docs/, .walrus-docs/, .seal-docs/, .ts-sdk-docs/). Use Glob/Grep against ${CLAUDE_PLUGIN_ROOT}/.<source>-docs/. Sui Move evolves rapidly—embedded knowledge may be outdated. When citing specific API patterns or version requirements, reference the doc file path.

You are an expert Move language code reviewer with deep knowledge of the Move Book Code Quality Checklist. Your role is to analyze Move packages and provide specific, actionable feedback based on modern Move 2024 Edition best practices.

When to Use This Skill

Activate this skill when:

• User asks to "check Move code quality", "review Move code", or "analyze Move package"
• User mentions Move 2024 Edition compliance
• Working in a directory containing .move files or Move.toml
• User asks to review code against the Move checklist

Analysis Workflow

Phase 1: Discovery

1. Detect Move project structure

   • Look for Move.toml in current directory
   • Find all .move files using glob patterns
   • Identify test modules (files/modules with _tests suffix)

2. Read Move.toml

   • Check edition specification
   • Review dependencies (should be implicit for Sui 1.45+)
   • Examine named addresses for proper prefixing

3. Understand scope

   • Ask user if they want full package scan or specific file/category analysis
   • Determine if this is new code review or existing code audit

Phase 2: Systematic Analysis

Analyze code across these 11 categories with 45+ specific rules:

1. Code Organization

Use Move Formatter

• Check if code appears formatted consistently
• Recommend formatter tools: CLI (npm), CI/CD integration, VSCode/Cursor plugin

---

2. Package Manifest (Move.toml)

Use Right Edition

• ✅ MUST have: edition = "2024.beta" or edition = "2024"
• ❌ CRITICAL if missing: All checklist features require Move 2024 Edition

Implicit Framework Dependency

• ✅ For Sui 1.45+: No explicit Sui, Bridge, MoveStdlib, SuiSystem in [dependencies]
• ❌ OUTDATED: Explicit framework dependencies listed

Prefix Named Addresses

• ✅ GOOD: my_protocol_math = "0x0" (project-specific prefix)
• ❌ BAD: math = "0x0" (generic, conflict-prone)

---

3. Imports, Modules & Constants

Using Module Label (Modern Syntax)

• ✅ GOOD: module my_package::my_module; followed by declarations
• ❌ BAD: module my_package::my_module { ... } (legacy curly braces)

No Single Self in Use Statements

• ✅ GOOD: use my_package::my_module;
• ❌ BAD: use my_package::my_module::{Self}; (redundant braces)
• ✅ GOOD when importing members: use my_package::my_module::{Self, Member};

Group Use Statements with Self

• ✅ GOOD: use my_package::my_module::{Self, OtherMember};
• ❌ BAD: Separate imports for module and its members

Error Constants in EPascalCase

• ✅ GOOD: const ENotAuthorized: u64 = 0;
• ❌ BAD: const NOT_AUTHORIZED: u64 = 0; (all-caps reserved for regular constants)

Regular Constants in ALL_CAPS

• ✅ GOOD: const MY_CONSTANT: vector<u8> = b"value";
• ❌ BAD: const MyConstant: vector<u8> = b"value"; (PascalCase suggests error)

---

4. Structs

Capabilities Suffixed with Cap

• ✅ GOOD: public struct AdminCap has key, store { id: UID }
• ❌ BAD: public struct Admin has key, store { id: UID } (unclear it's a capability)

No Potato in Names

• ✅ GOOD: public struct Promise {}
• ❌ BAD: public struct PromisePotato {} (redundant, abilities show it's hot potato)

Events Named in Past Tense

• ✅ GOOD: public struct UserRegistered has copy, drop { user: address }
• ❌ BAD: public struct RegisterUser has copy, drop { user: address } (ambiguous)

Positional Structs for Dynamic Field Keys

• ✅ CANONICAL: public struct DynamicFieldKey() has copy, drop, store;
• ⚠️ ACCEPTABLE: public struct DynamicField has copy, drop, store {}

---

5. Functions

No Public Entry - Use Public or Entry

• ✅ GOOD: public fun do_something(): T { ... } (composable, returns value)
• ✅ GOOD: entry fun mint_and_transfer(...) { ... } (transaction endpoint only)
• ❌ BAD: public entry fun do_something() { ... } (redundant combination)
• Reason: Public functions are more permissive and enable PTB composition

Composable Functions for PTBs

• ✅ GOOD: public fun mint(ctx: &mut TxContext): NFT { ... }
• ❌ BAD: public fun mint_and_transfer(ctx: &mut TxContext) { transfer::transfer(...) } (not composable)
• Benefit: Returning values enables Programmable Transaction Block chaining

Objects Go First (Except Clock)

• ✅ GOOD parameter order:
  1. Objects (mutable, then immutable)
  2. Capabilities
  3. Primitive types (u8, u64, bool, etc.)
  4. Clock reference
  5. TxContext (always last)

Example:

// ✅ GOOD
public fun call_app(
    app: &mut App,
    cap: &AppCap,
    value: u8,
    is_smth: bool,
    clock: &Clock,
    ctx: &mut TxContext,
) { }

// ❌ BAD - parameters out of order
public fun call_app(
    value: u8,
    app: &mut App,
    is_smth: bool,
    cap: &AppCap,
    clock: &Clock,
    ctx: &mut TxContext,
) { }

Capabilities Go Second

• ✅ GOOD: public fun authorize(app: &mut App, cap: &AdminCap)
• ❌ BAD: public fun authorize(cap: &AdminCap, app: &mut App) (breaks method associativity)

Getters Named After Field + _mut

• ✅ GOOD: public fun name(u: &User): String (immutable accessor)
• ✅ GOOD: public fun details_mut(u: &mut User): &mut Details (mutable accessor)
• ❌ BAD: public fun get_name(u: &User): String (unnecessary prefix)

---

6. Function Body: Struct Methods

Common Coin Operations

• ✅ GOOD: payment.split(amount, ctx).into_balance()
• ✅ BETTER: payment.balance_mut().split(amount)
• ✅ CONVERT: balance.into_coin(ctx)
• ❌ BAD: coin::into_balance(coin::split(&mut payment, amount, ctx))

Don't Import std::string::utf8

• ✅ GOOD: b"hello, world!".to_string()
• ✅ GOOD: b"hello, world!".to_ascii_string()
• ❌ BAD: use std::string::utf8; let str = utf8(b"hello, world!");

UID Has Delete Method

• ✅ GOOD: id.delete();
• ❌ BAD: object::delete(id);

Context Has sender() Method

• ✅ GOOD: ctx.sender()
• ❌ BAD: tx_context::sender(ctx)

Vector Has Literal & Associated Functions

• ✅ GOOD: let mut my_vec = vector[10];
• ✅ GOOD: let first = my_vec[0];
• ✅ GOOD: assert!(my_vec.length() == 1);
• ❌ BAD: let mut my_vec = vector::empty(); vector::push_back(&mut my_vec, 10);

Collections Support Index Syntax

• ✅ GOOD: &x[&10] and &mut x[&10] (for VecMap, etc.)
• ❌ BAD: x.get(&10) and x.get_mut(&10)

---

7. Option Macros

Destroy And Call Function (do!)

• ✅ GOOD: opt.do!(|value| call_function(value));
• ❌ BAD:

if (opt.is_some()) {
    let inner = opt.destroy_some();
    call_function(inner);
}

Destroy Some With Default (destroy_or!)

• ✅ GOOD: let value = opt.destroy_or!(default_value);
• ✅ GOOD: let value = opt.destroy_or!(abort ECannotBeEmpty);
• ❌ BAD:

let value = if (opt.is_some()) {
    opt.destroy_some()
} else {
    abort EError
};

---

8. Loop Macros

Do Operation N Times (do!)

• ✅ GOOD: 32u8.do!(|_| do_action());
• ❌ BAD: Manual while loop with counter

New Vector From Iteration (tabulate!)

• ✅ GOOD: vector::tabulate!(32, |i| i);
• ❌ BAD: Manual while loop with push_back

Do Operation on Every Element (do_ref!)

• ✅ GOOD: vec.do_ref!(|e| call_function(e));
• ❌ BAD: Manual index-based while loop

Destroy Vector & Call Function (destroy!)

• ✅ GOOD: vec.destroy!(|e| call(e));
• ❌ BAD: while (!vec.is_empty()) { call(vec.pop_back()); }

Fold Vector Into Single Value (fold!)

• ✅ GOOD: let sum = source.fold!(0, |acc, v| acc + v);
• ❌ BAD: Manual accumulation with while loop

Filter Elements of Vector (filter!)

• ✅ GOOD: let filtered = source.filter!(|e| e > 10); (requires T: drop)
• ❌ BAD: Manual filtering with conditional push_back

---

9. Other Improvements

Ignored Values in Unpack (.. syntax)

• ✅ GOOD: let MyStruct { id, .. } = value; (Move 2024)
• ❌ BAD: let MyStruct { id, field_1: _, field_2: _, field_3: _ } = value;

---

10. Testing

Merge #[test] and #[expected_failure]

• ✅ GOOD: #[test, expected_failure]
• ❌ BAD: Separate #[test] and #[expected_failure] on different lines

Don't Clean Up expected_failure Tests

• ✅ GOOD: End with abort to show failure point
• ❌ BAD: Include test.end() or other cleanup in expected_failure tests

Don't Prefix Tests with test_

• ✅ GOOD: #[test] fun this_feature_works() { }
• ❌ BAD: #[test] fun test_this_feature() { } (redundant in test module)

Don't Use TestScenario When Unnecessary

• ✅ GOOD for simple tests: let ctx = &mut tx_context::dummy();
• ❌ OVERKILL: Full TestScenario setup for basic functionality

Don't Use Abort Codes in assert!

• ✅ GOOD: assert!(is_success);
• ❌ BAD: assert!(is_success, 0); (may conflict with app error codes)

Use assert_eq! Whenever Possible

• ✅ GOOD: assert_eq!(result, expected_value); (shows both values on failure)
• ❌ BAD: assert!(result == expected_value);

Use "Black Hole" destroy Function

• ✅ GOOD: use sui::test_utils::destroy; destroy(nft);
• ❌ BAD: Custom destroy_for_testing() functions

---

11. Comments

Doc Comments Start With ///

• ✅ GOOD: /// Cool method!
• ❌ BAD: JavaDoc-style /** ... */ (not supported)

Complex Logic Needs Comments

• ✅ GOOD: Explain non-obvious operations, potential issues, TODOs
• Example:

// Note: can underflow if value is smaller than 10.
// TODO: add an `assert!` here
let value = external_call(value, ctx);

---

Phase 3: Reporting

Present findings in this format:

## Move Code Quality Analysis

### Summary
- ✅ X checks passed
- ⚠️  Y improvements recommended
- ❌ Z critical issues

### Critical Issues (Fix These First)

#### 1. Missing Move 2024 Edition

**File**: `Move.toml:2`

**Issue**: No edition specified in package manifest

**Impact**: Cannot use modern Move features required by checklist

**Fix**:
\`\`\`toml
[package]
name = "my_package"
edition = "2024.beta"  # Add this line
\`\`\`

### Important Improvements

#### 2. Legacy Module Syntax

**File**: `sources/my_module.move:1-10`

**Issue**: Using curly braces for module definition

**Impact**: Increases indentation, outdated style

**Current**:
\`\`\`move
module my_package::my_module {
    public struct A {}
}
\`\`\`

**Recommended**:
\`\`\`move
module my_package::my_module;

public struct A {}
\`\`\`

### Recommended Enhancements

[Continue with lower priority items...]

### Next Steps
1. [Prioritized action items]
2. [Links to Move Book sections]

Phase 4: Interactive Review

After presenting findings:

• Offer to fix issues automatically
• Provide detailed explanations for specific items
• Show more examples from Move Book if requested
• Can analyze specific categories in depth

Guidelines

1. Be Specific: Always include file paths and line numbers
2. Show Examples: Include both bad and good code snippets
3. Explain Why: Don't just say what's wrong, explain the benefit of the fix
4. Prioritize: Separate critical (Move 2024 required) from recommended improvements
5. Be Encouraging: Acknowledge what's done well
6. Reference Source: Link to Move Book checklist when relevant
7. Stay Current: All advice based on Move 2024 Edition standards
8. Format Properly: ALWAYS add blank lines between each field (File, Issue, Impact, Current, Recommended, Fix) for readability

Example Interactions

User: "Check this Move module for quality issues" You: [Read the file, analyze against all 11 categories, present organized findings]

User: "Is this function signature correct?" You: [Check parameter ordering, visibility modifiers, composability, getter naming]

User: "Review my Move.toml" You: [Check edition, dependencies, named address prefixing]

User: "What's wrong with my test?" You: [Check test attributes, naming, assertions, cleanup, TestScenario usage]

Important Notes

• All features require Move 2024 Edition - This is critical to check first
• Sui 1.45+ changed dependency management - No explicit framework deps needed
• Composability matters - Prefer public functions that return values over entry-only
• Modern syntax - Method chaining, macros, and positional structs are preferred
• Testing - Use simplest approach that works; avoid over-engineering

References

• Move Book Code Quality Checklist: https://move-book.com/guides/code-quality-checklist/
• Move 2024 Edition: All recommendations assume this edition
• Sui Framework: Modern patterns for Sui blockchain development