@erclx/canon 4.114.0 → 4.115.0

package/tooling/php/configs/scripts/verify.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+NESTED="${VERIFY_NESTED:-false}"
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
+  exit 1
+}
+log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+log_skip() { echo -e "${GREY}│ - $1${NC}"; }
+
+pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+  command -v php >/dev/null 2>&1 || log_error "php is not installed"
+  command -v composer >/dev/null 2>&1 || log_error "composer is not installed"
+}
+
+check_package() {
+  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
+}
+
+check_vendor() {
+  [ -x vendor/bin/phpunit ] || log_error "No vendor/bin/phpunit here. Run 'composer install'"
+}
+
+has_script() {
+  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
+}
+
+# A subfolder synced with --skip base declares none of base's scripts, since
+# the repository root owns them. Each base phase runs only where its script is
+# declared, so this script passes on its own in that subfolder.
+run_base_phase() {
+  local title=$1
+  local script=$2
+  local err_msg=$3
+  local pass_msg=$4
+
+  log_step "$title"
+  if ! has_script "$script"; then
+    log_skip "Skipped: $script is not declared here, so the repository root runs it"
+    return
+  fi
+  run_check "bun run $script" "$err_msg"
+  log_info "$pass_msg"
+}
+
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  local output
+  if ! output=$(eval "$cmd" 2>&1); then
+    echo "$output" | pipe_output
+    log_error "$err_msg"
+  fi
+  echo "$output" | pipe_output
+}
+
+main() {
+  check_dependencies
+  check_package
+  check_vendor
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
+  run_check "bun run typecheck" "Typecheck failed"
+  log_info "Typecheck passed"
+
+  log_step "Lint"
+  run_check "bun run lint" "Lint failed"
+  log_info "Lint passed"
+
+  run_base_phase "Formatting" "format" "Format failed" "Format applied"
+  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
+  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
+  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
+
+  log_step "Unit tests"
+  run_check "bun run test:run" "Unit tests failed"
+  log_info "Unit tests passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/php/manifest.toml

@@ -0,0 +1,15 @@
+[stack]
+name = "php"
+extends = "base"
+runtime = "composer"
+scaffold = "mkdir {{name}} && cd {{name}} && composer init -n --name example/{{name}} --autoload src/"
+
+[scripts]
+"lint" = "vendor/bin/php-cs-fixer check --diff"
+"lint:fix" = "vendor/bin/php-cs-fixer fix"
+"typecheck" = "vendor/bin/phpstan analyse --no-progress"
+"test" = "vendor/bin/phpunit"
+"test:run" = "vendor/bin/phpunit --testdox"
+
+[gitignore]
+"# PHP" = ["vendor/", ".php-cs-fixer.cache", ".phpunit.cache/", ".phpunit.result.cache"]

package/tooling/php/reference.md

@@ -0,0 +1,74 @@
+# Tooling PHP reference
+
+> Extends: `base`. Apply base stack first.
+
+## Overview
+
+The php stack covers Composer projects on PHP 8.3 or later, formatted by PHP CS Fixer, analysed by PHPStan, and tested by PHPUnit. It ships the three tools' configs, a PHP-aware `verify.sh`, and a copy-once smoke test.
+
+## Scaffold checklist
+
+1. Scaffold with `composer init -n --name <vendor>/<name> --autoload src/`. The package name and namespace are the project's own identity, so this stack never ships a `composer.json`.
+2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`.
+3. Install base tooling: `canon tooling sync base . --write`
+4. Install php tooling: `canon tooling sync php . --write`
+5. Install the dev tools: `composer require --dev friendsofphp/php-cs-fixer phpstan/phpstan phpunit/phpunit`. The manifest declares no `[dependencies.dev]`, because manifest injection runs `bun add -D`, which cannot install a Composer package. This step stays manual.
+6. Run `bun run lint:fix` then `bun run check`.
+
+Use PHP 8.3 or later, since PHPUnit 12 requires it.
+
+Keep both `src/` and `tests/` in place. All three tools read both paths and fail when either is missing. The scaffold creates `src/`, but git does not commit an empty folder, so a fresh clone with no source yet fails `lint` and `typecheck` until the first class lands there.
+
+The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run check` passes on a fresh scaffold. Delete or replace it with real tests.
+
+## PHP CS Fixer
+
+- Scan `src` and `tests`.
+- Allow risky rules.
+- Apply `@PER-CS`, plus `declare_strict_types`, `strict_comparison`, `no_unused_imports`, and `ordered_imports`.
+- Write the cache to `.php-cs-fixer.cache` beside the config.
+
+## PHPStan
+
+- Set `level: max`.
+- Analyse `src` and `tests`.
+
+## PHPUnit
+
+- Bootstrap from `vendor/autoload.php` and validate against the vendored schema.
+- Set `colors`, `failOnWarning`, and `failOnRisky`.
+- Run one `unit` suite over `tests`, with `src` as the source.
+
+## verify.sh
+
+- Stop and name `composer install` when `vendor/bin/phpunit` is missing.
+- Run Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`), plus the four base phases wherever the folder declares their scripts.
+
+## Gitignore
+
+- `# PHP`: `vendor/`, `.php-cs-fixer.cache`, `.phpunit.cache/`, `.phpunit.result.cache`
+
+## CI
+
+- Install PHP with `shivammathur/setup-php` and `tools: composer`.
+- Run `composer install`, then `bun run typecheck`, `bun run lint`, and `bun run test:run`.
+
+## Anti-patterns
+
+- Do not ship `composer.json` or `composer.lock` from tooling. Both belong to the project, and a golden copy would overwrite its package name on every sync.
+- Do not add a `phpstan-baseline.neon` to reach `level: max`. Fix the finding or lower the level in the project.
+- Do not ship a `Dockerfile`, `.dockerignore`, or `compose.yaml` under tooling. Those are deployment choices and belong in the project itself.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run lint` | Run `php-cs-fixer check --diff`. |
+| `bun run lint:fix` | Auto-fix with `php-cs-fixer fix`. |
+| `bun run typecheck` | Run `phpstan analyse`. |
+| `bun run test` | Run `phpunit`. |
+| `bun run test:run` | Run `phpunit --testdox` (used by `verify`). |
+
+## CI docs (extend)
+
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``.

package/tooling/php/seeds/.cspell/tech-stack.txt

@@ -0,0 +1,5 @@
+analyse
+friendsofphp
+phpstan
+phpunit
+testdox

package/tooling/php/seeds/tests/SmokeTest.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+final class SmokeTest extends TestCase
+{
+    public function testSmoke(): void
+    {
+        $this->assertSame(2, 1 + 1);
+    }
+}