Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 48 additions & 8 deletions .github/workflows/static-analysis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ on:
pull_request:
branches: [main]
workflow_dispatch:
# The whole-package mutation run (every src file) is weekly; pull requests mutate only
# the files they change, so they finish in minutes.
schedule:
- cron: '23 6 * * 1'

permissions:
contents: read
Expand Down Expand Up @@ -64,28 +68,64 @@ jobs:
mutation:
name: Mutation testing (Pest)
runs-on: ubuntu-latest
# About 2,800 mutations since phase 2; sequential runs took over 20 minutes.
timeout-minutes: 45
# A pull request mutates only the src/ files it changes; the weekly and dispatched runs
# mutate everything with a longer limit.
timeout-minutes: ${{ github.event_name == 'pull_request' && 15 || 60 }}

steps:
- name: Checkout
uses: actions/checkout@v7
with:
fetch-depth: 0

- name: Setup PHP
uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
with:
php-version: '8.5'
extensions: dom, curl, libxml, mbstring, zip, fileinfo, pdo, sqlite3, pdo_sqlite
# Pest mutation testing needs a coverage driver.
coverage: xdebug
# Pest mutation testing needs a coverage driver; PCOV is several times faster than Xdebug.
coverage: pcov

- name: Install dependencies
run: composer update --prefer-stable --no-interaction --no-progress

# Pest caches each mutant's result by the code and tests it depends on; restoring it means
# a re-run (a fix pushed to the same pull request) only tests what changed.
- name: Restore the mutation cache
uses: actions/cache@v6
with:
path: /tmp/pest-mutate-cache
key: pest-mutate-${{ github.head_ref || github.ref_name }}-${{ github.sha }}
restore-keys: |
pest-mutate-${{ github.head_ref || github.ref_name }}-
pest-mutate-main-

- name: Choose what to mutate
id: scope
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
files=$(git diff --name-only --diff-filter=AMR "$BASE_SHA"...HEAD -- 'src/*.php' | paste -sd, -)
echo "paths=$files" >> "$GITHUB_OUTPUT"
echo "Mutating: ${files:-nothing (no src/ changes)}"
else
echo "paths=" >> "$GITHUB_OUTPUT"
echo "Mutating: everything"
fi

- name: Mutation testing (minimum score 70)
# Pest's own mutator, not Infection: Infection has no Pest adapter, reads Pest's
# version as PHPUnit's, writes a config PHPUnit 12 rejects, and cannot map Pest's
# generated test classes to its JUnit report.
# --parallel: each worker gets its own faked disk (Storage::fake appends the
# ParallelTesting token), so the runtime JSON files never collide.
run: vendor/bin/pest --mutate --everything --parallel --min=70
# generated test classes to its JUnit report. The schema matrix (group `matrix`)
# covers almost every line, so it is left out, and group `shared-app` writes into the
# testbench application every process shares; the Tests workflow runs both.
if: github.event_name != 'pull_request' || steps.scope.outputs.paths != ''
env:
MUTATE_PATHS: ${{ steps.scope.outputs.paths }}
run: |
if [ -n "$MUTATE_PATHS" ]; then
vendor/bin/pest --mutate --path="$MUTATE_PATHS" --parallel --processes=8 --exclude-group=matrix,shared-app --ignore-min-score-on-zero-mutations --min=70
else
vendor/bin/pest --mutate --everything --parallel --processes=8 --exclude-group=matrix,shared-app --min=70
fi
27 changes: 27 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -78,3 +78,30 @@

- name: Run the database group
run: vendor/bin/pest --group=database

# §13: the full product of the schema switches (576 shapes) on SQLite, weekly and on demand.
# Pull requests run the pairwise set (10 shapes) inside the jobs above.
matrix-full:
name: Schema switches · full product
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
timeout-minutes: 20
env:
LARANAIL_SETTINGS_MATRIX: full
COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.GITHUB_TOKEN }}"}}'
steps:
- uses: actions/checkout@v7

- name: Setup PHP 8.4
uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
with:
php-version: '8.4'
extensions: dom, curl, libxml, mbstring, zip, fileinfo, pdo, sqlite3, pdo_sqlite
coverage: none
tools: composer:v2

- name: Install dependencies
run: composer update --prefer-dist --no-interaction --no-progress

- name: Run the full switch matrix
run: vendor/bin/pest --group=matrix
Comment on lines +85 to +107
111 changes: 0 additions & 111 deletions 2026_11_09_165225_create_settings_user_settings_table.php

This file was deleted.

45 changes: 45 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Schema switches (design phase 2b, §4.0): `identity.mode` (`slug_uid`, `slug_per_row`,
`uid_only`), `ids.type` (`bigint`, `uuid`, `ulid`; follows `laranail.db-tools.id_type` unless
set) with matching category keys, `ids.owner_key` (`string`, `typed`), `stores.<name>.mode`
(`polymorphic`, `dedicated` with an `owner_id` foreign key, `owner.*` and a polymorphic
`fallback` store for global values), `stores.<name>.soft_deletes` (forget trashes; the next
write restores through the version check, never as a conflict) and `categories.soft_deletes`,
`translations.mode` (`lang`, `json`; `NewCategory` `translations`, `Category::$titles` and
`titleIn()`), and `tables.definitions`. New enums `IdentityMode`, `IdType`, `OwnerKeyType`,
`StoreMode`, `TranslationsMode`.
- The schema-shape file (`database/settings-schema.php`, `schema.path`): `install` records the
shape its migrations produce and `make-store` adds its store; the migrations and the runtime
read the record, not live configuration (`SchemaShape`, `StoreSchema`,
`SchemaShapeRepository`).
- `doctor` drift detection: configuration against the schema file, the file's shape version
against this release, unrecorded database stores, and the live tables against the recorded
shape (missing or unexpected columns, wrong `id` type). `doctor --fix` syncs definitions.
- The optional `settings_definitions` table (D-6, `definitions.table`) with its migration,
`laranail::settings.sync-definitions` (code and config definitions as `is_system` rows; stale
ones removed; runtime rows never touched; gated by `manage_definitions`, audited), and the
`database` definition source for keys no code covers, with rules filtered through
`definitions.allowed_rules`. `definitions.sources` selects `code`, `config` and `database`.
- `$settings->audit()`: an immutable audit query (`for()`, `global()`, `store()`, `key()`,
`action()`, `outcome()`, `since()`, `until()`, then `get()`, `cursor()` or `paginate()` returning
an `AuditPage`), gated by `view_audit`; `Actions\QueryAudit`, `Data\AuditFilter`.
- A plain `set()` retries once after a concurrent change, re-reading the row under a row lock
(`writes.retry_on_conflict`, default on; logged). `SettingWrite::$expectedVersion` makes a
write conditional on a version and is never retried (`SettingWriter::setExpecting()`).
- The `prune` ability (and audit action): `Actions\PruneOrphans` and `Actions\PruneAudit` need it
when called with an actor, and both prunes are audited.
- `readiness.flush_on`: schema readiness is forgotten on tenancy events (stancl/tenancy and
spatie/laravel-multitenancy by default), since db-tools has no tenant hook of its own.
- The §13 switch matrix: a pairwise set of 10 shapes covering all 141 value pairs (both
asserted) on SQLite, MySQL and PostgreSQL, and the full 576-shape product weekly
(`LARANAIL_SETTINGS_MATRIX=full`, CI job `matrix-full`).

### Changed

- The migration stubs read the recorded schema shape (or configuration, when nothing is
recorded) instead of individual config keys, and run on the store's recorded connection.
- `laranail::settings.install` publishes a fourth migration (`create_settings_definitions_table`,
a no-op while the table is off), records the schema file and syncs definitions.
- `laranail::settings.prune-audit` now writes an audit entry for the prune itself.
- The `Settings` contract gains `audit()`. A third-party implementation of the contract must add
it (pre-1.0; `SettingsManager` and the fake implement it).

- The database layer (design phase 2, default schema): the `database` driver
(`DriverType::Database`) over the query builder, with version-checked writes that raise
`ConcurrentModification`, inserts in a savepoint, and database errors surfaced as
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Contributions are welcome via pull requests.
|---|---|
| `composer test` | the Pest suite (Arch, Unit, Feature) |
| `composer test-coverage` | the suite with line coverage, failing below 90 % |
| `composer mutate` | Pest mutation testing, failing below a 70 % score |
| `composer mutate` | Pest mutation testing of the whole package, failing below a 70 % score (slow; CI runs it weekly). For your change only: `vendor/bin/pest --mutate --path=src/Changed.php,src/Other.php --min=70`, which is what pull requests run |
| `composer lint` | Pint (shared laranail config), PHPStan at level max, Rector dry run; never changes files |
| `composer composer-audit` | known-vulnerable dependencies |

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ The hosted docs live at <https://opensource.simtabi.com/documentation/laranail/s
- [Access control](docs/tools/access-control.md) — actors, abilities, authorizers, guarded locks, sensitive reads and step-up verification.
- [Audit and logging](docs/tools/audit-and-logging.md) — the audit trail, its sinks and the operational log.
- [Runtime configuration](docs/tools/runtime-configuration.md) — stores, definitions and access changed in code for one request.
- [Schema switches](docs/tools/schema-switches.md) — identity, key types, dedicated stores, soft deletes, JSON translations, the definitions table and the schema file.
- [Audit queries](docs/tools/audit-queries.md) — reading the audit trail from PHP, gated by `view_audit`.

### Recipes

Expand Down
Loading
Loading