Skip to content

ADR-005-kariricode-directory.md

Latest commit

 

History

History
153 lines (112 loc) · 4.94 KB

ADR-005-kariricode-directory.md

File metadata and controls

153 lines (112 loc) · 4.94 KB

ADR-005: Centralized .kcode/ Directory Convention

Status: Accepted Date: 2025-02-28 Deciders: Walmir Silva Context: KaririCode Framework Devkit v1.0.0

Context

Quality tools traditionally place their config files in the project root:

project/
├── phpunit.xml.dist
├── phpstan.neon
├── .php-cs-fixer.dist.php
├── rector.php
├── psalm.xml
├── composer.json
├── README.md
└── src/

Five config files in the root creates visual noise and pushes domain-relevant files below the fold in directory listings. Each file also requires a .gitignore entry for its cache directory.

Decision

All devkit-generated configs and build artifacts are placed inside a single .kcode/ directory:

project/
├── devkit.php                  # Optional: project-specific overrides (committed to git)
├── .kcode/                     # Gitignored — regenerated by `kcode init`
│   ├── phpunit.xml.dist        # Generated
│   ├── phpstan.neon            # Generated
│   ├── php-cs-fixer.php        # Generated
│   ├── rector.php              # Generated
│   ├── psalm.xml               # Generated
│   └── build/                  # Caches, coverage, reports
│       ├── .phpunit.cache/
│       ├── .phpstan/
│       ├── .php-cs-fixer.cache
│       ├── .psalm/
│       ├── coverage/
│       ├── clover.xml
│       └── junit.xml
├── composer.json
├── README.md
└── src/

Gitignore Strategy

kcode init adds .kcode/ to .gitignore automatically:

# KaririCode Devkit — generated configs and build artifacts
.kcode/

The entire .kcode/ directory is gitignored because:

  1. Configs are deterministic — generated from composer.json + devkit.php. Running kcode init on any machine produces identical output.
  2. Zero CI friction — CI already runs kcode init before quality checks. No stale config drift between branches.
  3. Clean diffs — config regeneration after devkit upgrades doesn't pollute PRs.

If a project needs custom overrides, create devkit.php in the project root:

kcode init --config    # Scaffolds devkit.php with all available keys documented

The devkit.php lives at the project root (not inside .kcode/) and is committed to git normally.

Rationale

Clean Project Root

The project root now contains only domain-relevant files. The .kcode/ directory is a single entry that collapses in file explorers and IDE project trees.

Convention Over Configuration

The directory name .kcode/ is:

  • Dot-prefixed — Hidden in Unix directory listings by default.
  • Namespaced — No collision with other tools (unlike .config/ or .tools/).
  • Discoverable — Any KaririCode contributor recognizes the convention.

Relative Path Strategy

Generated configs use ../ relative paths to reference project source:

<!-- .kcode/phpunit.xml.dist -->
<directory>../tests/Unit</directory>
# .kcode/phpstan.neon
paths:
    - ../src

This works because tools are invoked with --configuration .kcode/phpunit.xml.dist, making the config file's directory the resolution base.

Build Isolation

All tool caches and generated reports go to .kcode/build/:

Tool Cache Location
PHPUnit .kcode/build/.phpunit.cache/
PHPStan .kcode/build/.phpstan/
PHP-CS-Fixer .kcode/build/.php-cs-fixer.cache
Psalm .kcode/build/.psalm/
Coverage HTML .kcode/build/coverage/
JUnit XML .kcode/build/junit.xml
Clover XML .kcode/build/clover.xml

One .gitignore entry covers all build artifacts.

Consequences

Positive

  • Clean project root — 5 fewer files visible at the top level.
  • Single gitignore entry (.kcode/) covers all generated configs and build artifacts.
  • No config drift — regenerated deterministically from composer.json on every kcode init.
  • Clean PRs — devkit version upgrades don't pollute diffs with config changes.
  • Convention is immediately recognizable across the KaririCode ecosystem.

Negative

  • CI pipelines must run kcode init before any quality step. The standard CI workflow already includes this.
  • Tool commands must specify config paths explicitly (--configuration .kcode/phpunit.xml.dist). The devkit CLI handles this transparently, but raw tool invocation requires the path.
  • IDE integrations (PHPStorm PHPUnit runner) may need manual config path setup.

Migration

Projects migrating from root-level configs:

composer require --dev kariricode/devkit
vendor/bin/kcode init       # Generates .kcode/, adds to .gitignore
vendor/bin/kcode migrate    # Interactive removal of old deps and configs

References

  • Angular CLI: .angular/ directory convention
  • Next.js: .next/ build directory
  • Rust Cargo: target/ build directory
  • ARFA 1.3 Specification, §5.1: Project Layout Conventions