KaririCode Devkit

Unified quality toolchain for the KaririCode Framework ecosystem.

One dependency. One CLI. Zero config drift across 35+ components.

Installation · Quick Start · CLI Reference · Configuration · CI Integration

The Problem

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.

The Solution

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"
}

Requirements

Requirement	Version
PHP	8.4 or higher
Composer	2.x

Installation

As a Composer dependency (recommended)

composer require --dev kariricode/devkit

As a standalone PHAR

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

Quick Start

# 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

CLI Reference

`kcode init`

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.

`kcode migrate`

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:

Category	Items
`require-dev` packages	`phpunit/phpunit`, `phpstan/phpstan`, `phpstan` extensions, `php-cs-fixer`, `rector/rector`, `vimeo/psalm`
Root config files	`phpunit.xml(.dist)`, `phpstan.neon(.dist)`, `.php-cs-fixer(.dist).php`, `rector.php`, `psalm.xml(.dist)`
Root cache paths	`.phpunit.cache`, `.phpunit.result.cache`, `.phpstan`, `.php-cs-fixer.cache`, `.psalm`

`kcode test`

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

`kcode analyse`

Runs PHPStan and Psalm in sequence.

kcode analyse

`kcode cs:fix`

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)

`kcode rector`

Runs Rector. Defaults to read-only preview mode.

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

`kcode quality`

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)

`kcode format`

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

kcode format

`kcode security`

Runs composer audit to check for known security vulnerabilities.

kcode security

`kcode clean`

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

kcode clean

Configuration

Auto-detection

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

Detected Field	Source
Project name	`name`
Root namespace	`autoload.psr-4` (first key)
PHP version	`require.php`
Source directories	`autoload.psr-4` values
Test directories	`autoload-dev.psr-4` values
Test suites	Standard subdirs: `Unit/`, `Integration/`, `Conformance/`, `Functional/`

Project overrides via `devkit.php`

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

kcode init --config

Example:

<?phpdeclare(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/.

Override reference

Key	Type	Default	Merge strategy
`project_name`	`string`	From `composer.json`	Replace
`namespace`	`string`	From PSR-4 autoload	Replace
`php_version`	`string`	From `require.php`	Replace
`phpstan_level`	`int`	`9`	Replace
`psalm_level`	`int`	`3`	Replace
`source_dirs`	`list<string>`	From PSR-4 autoload	Replace
`test_dirs`	`list<string>`	From PSR-4 autoload-dev	Replace
`exclude_dirs`	`list<string>`	`['src/Contract']`	Replace
`test_suites`	`array<string, string>`	Auto-detected	Replace
`coverage_exclude`	`list<string>`	`['src/Exception']`	Replace
`cs_fixer_rules`	`array<string, mixed>`	KaririCode standard	Merge (your rules win)
`rector_sets`	`list<string>`	KaririCode standard	Replace
`tools`	`array<string, string>`	—	Informational

File ownership

File	Location	Committed	Managed by
`devkit.php`	Project root	✅ Yes	Developer
`.kcode/`	Generated dir	❌ No (gitignored)	`kcode init`

KaririCode coding standard

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.

CI Integration

GitHub Actions — unified pipeline

name: Qualityon: [push, pull_request]jobs:
quality:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2with:
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

GitHub Actions — parallel jobs

jobs:
cs-check:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2with: { php-version: '8.4' }
- run: composer install --no-progress --no-scripts
- run: vendor/bin/kcode init && vendor/bin/kcode cs:fix --checkanalyse:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2with: { php-version: '8.4' }
- run: composer install --no-progress --no-scripts
- run: vendor/bin/kcode init && vendor/bin/kcode analysetest:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2with: { php-version: '8.4', coverage: pcov }
- run: composer install --no-progress --no-scripts
- run: vendor/bin/kcode init && vendor/bin/kcode test --coverage

Migrating from Root-Level Configs

# 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.

Architecture

Component layout

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

Dependency flow

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.

Key design decisions

Decision	Rationale	ADR
Native PHAR builder	Avoids Box 4.x / PHP 8.4 incompatibility	—
Zero external runtime dependencies	Sub-millisecond boot, no version conflicts	ADR-002
Config generation over bundling	Eliminates drift across 35+ components	ADR-003
Three-tier binary resolution	PHAR → vendor → global fallback	ADR-004
`.kcode/` directory	Clean project root, single gitignore entry	ADR-005
Immutable value objects	Thread-safe, ARFA 1.3 compliant	ADR-006

Specifications

Spec	Covers
SPEC-001	Project detection, config merging, defaults
SPEC-002	CLI interface, argument parsing, output format
SPEC-003	Runner contract, process execution, result handling

Project Stats

Metric	Value
PHP source files	38
Total source lines	~2,900
External runtime dependencies	0
Quality tools supported	6 (PHPUnit, PHPStan, PHP-CS-Fixer, Rector, Psalm, Composer Audit)
CLI commands	10
PHPStan level	9 (0 errors)
Test suite	41 tests · 81 assertions
PHP version	8.4+
ARFA compliance	1.3

Building `kcode.phar`

# 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.

Contributing

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.

License

Part of the KaririCode Framework ecosystem.

kariricode.org · GitHub · Packagist

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.github/workflows		.github/workflows
bin		bin
build		build
docs		docs
src		src
tests/Unit		tests/Unit
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
box.json		box.json
composer.json		composer.json
phpunit.xml		phpunit.xml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

KaririCode Devkit

The Problem

The Solution

Requirements

Installation

As a Composer dependency (recommended)

As a standalone PHAR

Quick Start

CLI Reference

kcode init

kcode migrate

kcode test

kcode analyse

kcode cs:fix

kcode rector

kcode quality

kcode format

kcode security

kcode clean