clarity-check

# Clarity Check Skill Pre-deployment validation gate for Clarity smart contracts. Runs automated checks for syntax errors, deprecated keywords, incorrect sender checks, error propagation issues, and missing tests. Pairs with the existing `contract` skill for deploy operations. ## Usage This is a doc-only skill. Agents read this file to understand available checks and invoke them through the skill framework. The CLI interface below documents the planned implementation. ``` bun run clarity-check/clarity-check.ts <subcommand> [options] ``` ## Subcommands ### validate Run all automated checks against a Clarity contract file. ``` bun run clarity-check/clarity-check.ts validate --source <path-to-file.clar> [--project-dir <clarinet-project-dir>] ``` Options: - `--source` (required) — Path to the `.clar` source file to validate - `--project-dir` (optional) — Clarinet project directory for `clarinet check` integration; auto-detected from source path if omitted Output: ```json { "file": "contracts/my-contract.clar", "passed": false, "checks": [ { "name": "syntax", "status": "pass", "description": "clarinet check passes" }, { "name": "deprecated-keywords", "status": "fail", "description": "Deprecated keywords found", "findings": [ { "line": 15, "keyword": "block-height", "replacement": "stacks-block-height", "severity": "warning" } ] }, { "name": "sender-checks", "status": "warn", "description": "Sender check analysis", "findings": [ { "line": 22, "issue": "Token transfer uses contract-caller instead of tx-sender", "recommendation": "Use tx-sender for token operations to preserve human identity through proxies", "severity": "warning" } ] } ], "summary": { "total": 7, "pass": 5, "fail": 1, "warn": 1 } } ``` ### checklist Generate a human-readable pre-deployment checklist for a contract, combining automated checks with manual verification items. ``` bun run clarity-check/clarity-check.ts checklist --source <path-to-file.clar> [--project-dir <clarinet-project-dir>] ``` Options: - `--source` (required) — Path to the `.clar` source file - `--project-dir` (optional) — Clarinet project directory Output: ```json { "file": "contracts/my-contract.clar", "automated": [ {"check": "clarinet check passes", "status": "pass"}, {"check": "No deprecated keywords", "status": "fail", "details": "Found: block-height on line 15"}, {"check": "Correct sender checks", "status": "warn", "details": "1 finding"}, {"check": "Error propagation uses try!", "status": "pass"}, {"check": "No dead code or unused features", "status": "pass"}, {"check": "Events follow structured format", "status": "pass"}, {"check": "Error codes are unique", "status": "pass"} ], "manual": [ "Verify tests exist and pass (npm test)", "Check execution costs in clarinet console (::get_costs)", "Review post-conditions for all token operations", "Verify trait whitelisting if external contracts are called", "Test on testnet before mainnet deployment", "Document contract address after deployment" ] } ``` ## Checks Performed ### Automated | Check | What it detects | |-------|----------------| | Syntax | `clarinet check` errors and warnings | | Deprecated keywords | `block-height` (use `stacks-block-height`), other legacy keywords | | Sender checks | `tx-sender` vs `contract-caller` misuse in token operations | | Error propagation | `unwrap!` used where `try!` is more appropriate for recoverable errors | | Dead code | Unused private functions, unreachable branches | | Event format | Events missing `notification`/`payload` structure | | Error code uniqueness | Duplicate error code constants | | Public function returns | Functions missing `(response ok err)` return type | ### Manual (Checklist Only) | Check | Why it matters | |-------|---------------| | Tests exist and pass | Ensures behavior is verified | | Execution costs | Prevents exceeding block limits | | Post-conditions | Protects users from unexpected token transfers | | Trait whitelisting | Prevents unauthorized contract interactions | | Testnet deployment | Catches issues before mainnet | ## Notes - Requires `clarinet` CLI installed locally for syntax checking - If `clarinet` is not found, syntax check is skipped with a warning - Static analysis only — does not execute the contract or run tests - Use `clarity-test-scaffold` to generate tests, then `clarity-audit` for deep review - Complements `clarinet check` by adding Clarity-specific best practice checks that the compiler doesn't enforce