Running Dev Checks
Expert guidance for botcore's development command suite — language-aware linting, testing, building, quality gates, and static analysis.
Capabilities
- Run Language-Aware Commands -- Execute lint, test, and build using the correct tool for the detected language (Python/TypeScript/Rust)
- Check Code Quality -- Validate file sizes, test coverage, and dependency freshness against configurable thresholds
- Analyze Code Structure -- Find dead code, circular imports, unused dependencies, and generate dependency graphs
- Check Portability -- Detect hardcoded paths that break cross-platform compatibility
- Lint Skills -- Validate skill directories against the Agent Skills format specification
Routing Logic
Core Principles
1. Lefthook IS the CI Pipeline
<rules>
`pnpm check` runs the exact same steps as GitHub Actions CI. If it passes locally, CI passes remotely.
The quality gate runs: lint → build → typecheck → test:coverage + portability, file-size, orphan-files.
Never add a check to CI without adding it to lefthook's `check` group first.
Never add a check to lefthook without verifying CI runs the same command.
Drift between local and remote gates is a bug — the `check` group is the single source of truth.
</rules>
2. Three Enforcement Layers
| Layer | When | Speed | What |
|---|
| Pre-commit | git commit | ~8s | Lint staged files, portability, file-size, typecheck |
| Pre-push | git push | ~25s | Full lint, test, typecheck, portability, file-size, orphan-files |
On-demand (pnpm check) | Before release / manual | ~25s | Same as pre-push + build + test:coverage |
Pre-commit catches formatting. Pre-push catches regressions. pnpm check catches everything CI would catch.
3. Language Dispatch Is Automatic
<rules>
Dev commands read the `language`, `linter`, `test_runner`, and `formatter` from config.
The same `dev_lint()` call runs ruff for Python, biome for TypeScript, or clippy for Rust.
Never hardcode tool names in scripts — let config drive tool selection.
</rules>
2. Thresholds Are Config-Driven
<rules>
All quality thresholds come from `BotCoreConfig` with sensible defaults.
Override per-package in `[tool.botcore.packages.NAME]` for monorepos.
</rules>
| Check | Config Field | Default |
|---|
| File size warning | file_size_warn | 500 lines |
| File size error | file_size_error | 1000 lines |
| Coverage failure | coverage_threshold | 80% |
| Coverage warning | coverage_warn_threshold | 60% |
| Major version lag | deps_max_major_behind | 1 |
| Minor version lag | deps_max_minor_behind | 3 |
3. Analysis Commands Are Read-Only
<rules>
Analysis commands (dead_code, circular_imports, unused_deps, dep_graph) report findings but never modify code.
They return structured data for agents to act on — the agent decides what to fix.
</rules>
Command Overview
Core Commands (Language-Dispatched)
| Command | Python | TypeScript | Rust |
|---|
dev_lint() | ruff check | biome lint | cargo clippy |
dev_test() | pytest | vitest run | cargo test |
dev_build() | hatch build | turbo build | cargo build |
dev_skill_lint() | (universal) | (universal) | (universal) |
Quality Commands
| Command | What It Checks |
|---|
dev_check_size() | Python file line counts vs thresholds |
dev_check_coverage() | Test coverage vs threshold (runs pytest --cov) |
dev_check_deps() | Dependency versions vs PyPI latest |
Analysis Commands
| Command | What It Finds |
|---|
dev_dead_code() | Unused functions, variables, imports (via vulture) |
dev_circular_imports() | Import cycles using AST + DFS |
dev_unused_deps() | Declared but not imported dependencies |
dev_dep_graph() | Module dependency graph (JSON or DOT) |
Portability Commands
| Command | What It Detects |
|---|
dev_check_paths() | Hardcoded Windows/Unix paths, localhost URLs |
Workflow
Daily Development Flow
- Write code — make changes
- Lint —
dev_lint() catches style and syntax issues
- Test —
dev_test() runs the test suite
- Quality gates —
dev_check_size(), dev_check_coverage() validate standards
Pre-Release Analysis
- Dead code —
dev_dead_code() finds unused symbols
- Circular imports —
dev_circular_imports() detects cycles
- Unused deps —
dev_unused_deps() finds removable dependencies
- Dep freshness —
dev_check_deps() checks for staleness
- Portability —
dev_check_paths() ensures cross-platform compatibility
Checklist
