Every KaririCode component independently maintains five dev tools — leading to hundreds of near-identical, manually-drifting configurations:

composer.json          →  5 require-dev entries per component
phpunit.xml.dist       →  ~60 lines per component
phpstan.neon           →  ~25 lines per component
.php-cs-fixer.dist.php →  ~50 lines per component
rector.php             →  ~30 lines per component
psalm.xml              →  ~20 lines per component

Across 35+ components, that's 175+ redundant dependency entries and 175+ near-identical config files. Updating a single CS-Fixer rule means 35 pull requests.

composer require --dev kariricode/devkit
vendor/bin/kcode init

Devkit generates .kcode/ — a gitignored directory of configs derived directly from your composer.json. Your five dev dependencies become one, with one canonical source of truth:

your-component/
├── devkit.php               ← Optional overrides (committed to git)
├── .kcode/                  ← Generated (gitignored — run `kcode init` to recreate)
│   ├── phpunit.xml.dist
│   ├── phpstan.neon
│   ├── php-cs-fixer.php
│   ├── rector.php
│   ├── psalm.xml
│   └── build/              ← Coverage reports, caches, JUnit XML
├── composer.json
├── src/
└── tests/

  "require-dev": {
-     "phpunit/phpunit": "^12.0",
-     "phpstan/phpstan": "^2.0",
-     "friendsofphp/php-cs-fixer": "^3.64",
-     "rector/rector": "^2.0",
-     "vimeo/psalm": "^6.0"
+     "kariricode/devkit": "^1.0"
  }

composer require --dev kariricode/devkit

wget https://github.com/kariricode/devkit/releases/latest/download/kcode.phar
chmod +x kcode.phar
sudo mv kcode.phar /usr/local/bin/kcode

# Step 1 — Generate .kcode/ configs from your composer.json
vendor/bin/kcode init

# Step 2 — Remove old deps/configs (interactive prompt)
vendor/bin/kcode migrate

# Step 3 — Run the full quality pipeline
vendor/bin/kcode quality

Generates or regenerates all configs inside .kcode/ from your composer.json. Safe to run at any time — existing files are cleanly overwritten.

kcode init           # Generate configs
kcode init --config  # Also scaffold devkit.php with all available keys

✓ Project: kariricode/parser
✓ Namespace: KaririCode\Parser
✓ PHP: 8.4
✓ Generated 5 config file(s) in .kcode/
✓ .kcode/ added to .gitignore
⚠ Found 8 redundant item(s) that kcode replaces.
  Run kcode migrate to review and clean up.

Scans for redundant dev dependencies, root-level config files, and cache paths that Devkit now manages. Presents a full report before making any change.

kcode migrate                   # Interactive (default)
kcode migrate --dry-run         # Preview only — no changes applied
kcode migrate --no-interaction  # Auto-remove (for CI)

Detected items:

Runs PHPUnit with the .kcode/phpunit.xml.dist configuration.

kcode test                           # Run all test suites
kcode test --suite=Unit              # Run a single suite
kcode test --coverage                # Generate HTML coverage report
kcode test --filter=testMyMethod     # Pass any PHPUnit argument through

Runs PHPStan and Psalm in sequence.

kcode analyse

Applies PHP-CS-Fixer with the KaririCode code standard.

kcode cs:fix          # Fix all violations
kcode cs:fix --check  # Dry-run — only report (no modifications)

Runs Rector. Defaults to read-only preview mode.

kcode rector        # Preview changes (no files modified)
kcode rector --fix  # Apply changes

Full sequential pipeline in optimal order:

cs:check → phpstan → psalm → phpunit

kcode quality

✓ cs-fixer   passed (1.23s)
✓ phpstan     passed (4.56s)
✓ psalm       passed (3.21s)
✓ phpunit     passed (2.10s)

✓ All 4 tool(s) passed (11.10s total)

Applies all auto-formatting in sequence: CS-Fixer fix + Rector apply.

kcode format

Runs composer audit to check for known security vulnerabilities.

kcode security

Removes .kcode/build/ — caches, coverage reports, JUnit XML.

kcode clean

Devkit reads your composer.json to derive all defaults automatically:

Create devkit.php in your project root to override any default. Scaffold a fully-annotated file with:

kcode init --config

Example:

<?php

declare(strict_types=1);

return [
    'phpstan_level'    => 8,                      // 0–9 (default: 9)
    'psalm_level'      => 4,                      // 1–9 (default: 3)
    'exclude_dirs'     => ['src/Contract'],       // Excluded from analysis
    'test_suites'      => [
        'Unit'         => 'tests/Unit',
        'Integration'  => 'tests/Integration',
    ],
    'coverage_exclude' => ['src/Exception'],
    'cs_fixer_rules'   => [                       // Merged with KaririCode defaults
        'yoda_style'   => false,
    ],
    'rector_sets'      => [                       // Replaces defaults entirely
        'LevelSetList::UP_TO_PHP_84',
        'SetList::CODE_QUALITY',
    ],
];

After editing, run kcode init to regenerate .kcode/.

The default CS-Fixer ruleset includes:

• PSR-12 baseline with PHP 8.4 migration rules
• Strict types enforcement (declare_strict_types)
• Compiler-optimized native function invocations
• Alphabetically ordered imports
• Trailing commas in multiline arrays, arguments, and parameters

See SPEC-001 §7 for the complete rule set.

name: Quality
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: pcov
      - run: composer install --no-progress --no-scripts
      - run: vendor/bin/kcode init
      - run: vendor/bin/kcode migrate --no-interaction
      - run: vendor/bin/kcode quality

jobs:
  cs-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.4' }
      - run: composer install --no-progress --no-scripts
      - run: vendor/bin/kcode init && vendor/bin/kcode cs:fix --check

  analyse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.4' }
      - run: composer install --no-progress --no-scripts
      - run: vendor/bin/kcode init && vendor/bin/kcode analyse

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.4', coverage: pcov }
      - run: composer install --no-progress --no-scripts
      - run: vendor/bin/kcode init && vendor/bin/kcode test --coverage

# 1. Add devkit as a dev dependency
composer require --dev kariricode/devkit

# 2. Generate .kcode/ configs
vendor/bin/kcode init

# 3. Review and remove redundant files (interactive)
vendor/bin/kcode migrate

# 4. Apply composer.json changes
composer update

# 5. Verify the pipeline
vendor/bin/kcode quality

Use --dry-run to inspect what would be removed before committing.

src/
├── Contract/        Interfaces: ConfigGenerator, ToolRunner
├── Core/            Devkit façade · ProjectDetector · ProcessExecutor
├── Configuration/   Config generators (5 tools)
├── Runner/          Tool runners (6 runners + AbstractToolRunner)
├── Command/         CLI commands (10 commands + Application + AbstractCommand)
├── Exception/       Exception hierarchy
└── ValueObject/     Immutable results: ToolResult · QualityReport · MigrationReport

Command → Core (Devkit) → Contract ← Runner / Configuration

Strict unidirectional flow. No circular dependencies. Commands call the Devkit façade. Runners and generators implement contracts. Core orchestrates.

# Requirements: PHP 8.4+ · Composer 2.x · phar.readonly=0

# Full release pipeline (recommended)
make release

# Manual
composer install
php -d phar.readonly=0 bin/build-phar.php
php build/kcode.phar --version    # → KaririCode Devkit 1.0.0

# Install globally
sudo mv build/kcode.phar /usr/local/bin/kcode

See docs/BUILDING.md for full build documentation, troubleshooting, and release automation details.

git clone https://github.com/kariricode/devkit.git
cd devkit
composer install
vendor/bin/kcode init
vendor/bin/kcode quality        # Must pass before opening a PR

CI enforces code quality and a PHAR smoke test on every push and PR.

MIT License © Walmir Silva