Skip to content
Draft
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
71 changes: 71 additions & 0 deletions notes/00-goal-and-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Goal & Design — shipmonk coding-standard rewrite

## High-level goal

Rewrite https://github.com/shipmonk-rnd/coding-standard **from scratch**, WITHOUT depending on:
- `slevomat/coding-standard`
- `squizlabs/php_codesniffer` (PHP_CodeSniffer / phpcs)

## Core design principle — "permissive formatter"

The coding standard must NOT enforce exactly one way to write code. For any formatting
choice where multiple styles are reasonable, **allow all of them**, and only reformat when
the code uses a style that is *not* in the allowed set.

### Canonical example — array formatting

Both of these are equally allowed and neither is rewritten into the other:

```php
$a = [1, 2];
```

```php
$a = [
1,
2,
];
```

Contrast with typical formatters (Prettier, gofmt, php-cs-fixer in fixed mode) which pick
ONE canonical form and rewrite everything to it. We want a formatter whose "fixed point"
is a *set* of acceptable forms, not a single normal form.

### Implications / open questions this raises

- The tool is closer to a **linter with autofix** than a pure formatter — but the "lint
rules" are about formatting, and violations are auto-fixable.
- Idempotency: running twice must not change already-allowed code. (Same as any formatter.)
- Stability: given allowed input, output == input (no churn). This is the whole point.
- When code IS out of spec, which allowed form do we rewrite it to? (Need a "preferred"
form per rule, used only when reformatting is forced.)
- Config surface: each rule needs to express "these forms are allowed" rather than
"this is the one true form".

## Key architectural question (undecided)

**AST-based vs raw-token-based formatter?**

- Token-based (like phpcs): operates on the token stream, preserves original formatting by
default, edits are localized. Good fit for "only change what's wrong". Historically what
phpcs/slevomat do — which is exactly what we're replacing, so understand *why* before
copying.
- AST/CST-based (like Prettier, Biome, Roslyn): parse to a tree, then pretty-print. Pretty-
printing inherently imposes ONE canonical form, which fights our core principle unless we
use a lossless CST that preserves original trivia/whitespace and only rewrites subtrees
that violate rules.
- Middle ground: **lossless CST** (concrete syntax tree preserving all trivia) — this is
what modern formatters (Biome/Rome, Roslyn, oxc, tree-sitter tools) use. Lets us reason
structurally AND preserve original formatting where it's already acceptable.

This is the thing the formatter-architecture research (oxc, Ruff, dprint, + others) must
inform. See 10-*.md research notes.

## Research plan

Research modern formatters, focusing on: IR/data model (AST vs CST vs token), how they
decide line breaks (the "Wadler/Prettier IR" doc-builder algebra vs hand-rolled), how they
preserve or normalize existing formatting, and whether any support "multiple allowed forms".

Targets: oxc formatter, Ruff formatter, dprint, plus Biome, Prettier, gofmt, rustfmt,
Roslyn/CSharpier, tree-sitter/Topiary. See notes 10..19.
95 changes: 95 additions & 0 deletions notes/01-existing-standard-analysis.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Analysis of the existing shipmonk/coding-standard

Repo: `repos/coding-standard`. It is a **thin curation layer**, not an engine:
- `ShipMonkCodingStandard/ruleset.xml` (464 lines) selects ~150 rules from bundled
standards (Generic / PEAR / PSR1 / PSR2 / PSR12 / Squiz — all shipped by
`squizlabs/php_codesniffer`) plus a large set of `SlevomatCodingStandard.*` rules.
- 7 custom sniffs live in `ShipMonkCodingStandard/Sniffs/`.
- Everything runs on the **PHP_CodeSniffer engine** (token stream + `Sniff` API + `Fixer`).

So "rewrite from scratch without phpcs/slevomat" means: **build our own engine AND
reimplement the subset of rules we want to keep.** The ruleset.xml is the spec of intent.

## The current engine model (what we're replacing)

phpcs is **token-stream based**. A sniff declares token types via `register()`, and
`process()` is called at each matching token; fixes mutate tokens via a `Fixer`
(`replaceToken`, `addContent`, etc.). Example — `OpenParenthesisSpacingSniff`:

```php
public function register(): array { return [T_IF, T_ELSEIF, T_CATCH]; }
public function process(File $file, $ptr): void {
$opener = $tokens[$ptr]['parenthesis_opener'];
$next = $tokens[$opener + 1];
if ($next['code'] !== T_WHITESPACE || $next['content'] === "\n") return;
$fix = $file->addFixableError('Expected 0 spaces after opening bracket', ...);
if ($fix) $file->fixer->replaceToken($opener + 1, ltrim($next['content'], " \t"));
}
```

KEY OBSERVATION: this model is **already localized-edit and preservation-friendly**. It
strips only horizontal whitespace and deliberately *preserves* a following newline. phpcs
does NOT reprint the file; each sniff touches only the tokens it cares about. So the
"only reformat what's wrong, leave the rest alone" behavior we want is *native* to the
token model — it's what phpcs already does. The pain with phpcs/slevomat isn't the
approach, it's: heavyweight/awkward sniff API, XML config, slow, token metadata quirks,
no real tree, hard to write cross-cutting rules, and the dependency we want to drop.

This is a strong data point for the AST-vs-token question (note 20): the incumbent is
token-based and its localized-edit behavior is exactly our goal.

## Rule taxonomy — TWO very different concerns are bundled together

The ruleset mixes two fundamentally different kinds of rule. The rewrite MUST decide
scope for each; the "permissive formatter" design only applies to the first kind.

### A. Formatting / whitespace / layout rules (the "permissive formatter" target)
Whitespace, indentation, spacing, blank lines, line breaks, bracket placement, trailing
commas. Examples from the ruleset:
- Generic.WhiteSpace.ScopeIndent, DisallowTabIndent, IncrementDecrementSpacing
- Generic.Formatting.SpaceAfterCast / SpaceAfterNot / MultipleStatementAlignment
- Generic.Functions.OpeningFunctionBraceBsdAllman
- PSR12.Operators.OperatorSpacing; Squiz.WhiteSpace.* (Operator/Object/Cast/Semicolon/…)
- Squiz.Strings.ConcatenationSpacing; Squiz.Arrays.ArrayBracketSpacing
- Slevomat.Arrays.SingleLineArrayWhitespace / MultiLineArrayEndBracketPlacement /
TrailingArrayComma; Slevomat.Functions.RequireTrailingCommaIn* (+ onlySingleLine)
- Slevomat.Classes.*Spacing, EmptyLinesAroundClassBraces, MethodSpacing, PropertySpacing
- Slevomat.TypeHints.*Spacing, DNFTypeHintFormat; Namespaces.UseSpacing/NamespaceSpacing
- ShipMonk custom: DoubleArrowSpacing, CatchSpacing, MultilineConditionSpacing,
MultilineTernary, OpenParenthesisSpacing, DisallowOneLineDocComment
- NOTE the existing standard ALREADY embraces permissiveness in places:
`DisallowTrailingCommaInCall onlySingleLine=true` + `RequireTrailingCommaInCall` =
"single-line: no trailing comma; multi-line: require it" — i.e. layout-dependent rules,
exactly the multi-form idea. `allowMultiLine`/`ignoreNewlines`/`allowMultiline` flags
recur throughout — the incumbent is already semi-permissive by hand.

### B. Lint / code-quality / static-analysis rules (NOT formatting)
These are about code correctness/style-of-logic, not whitespace. A "permissive formatter"
says nothing about them. Many overlap with what PHPStan already does.
- Unused/import hygiene: Slevomat.Namespaces.UnusedUses, UselessAlias,
ReferenceUsedNamesOnly, AlphabeticallySortedUses; Variables.UnusedVariable,
UselessVariable, DuplicateAssignmentToVariable
- Code smells: Slevomat.ControlStructures.UselessTernaryOperator,
RequireNullCoalesce*, DisallowYodaComparison; Operators.DisallowEqualOperators
- Type hints presence: Slevomat.TypeHints.ParameterTypeHint/ReturnTypeHint/PropertyTypeHint
- Comments/annotations: DocComment* content rules, ForbiddenAnnotations/Comments,
UselessFunctionDocComment, naming conventions, class structure ordering
- Generic.CodeAnalysis.*, Squiz.PHP.NonExecutableCode, one-class-per-file, etc.

### SCOPING DECISION NEEDED (for the user)
The new tool could be:
1. **Pure formatter** — only concern A. Punt all of concern B to PHPStan (which shipmonk
already uses heavily and which does B better). Smallest, cleanest, best fits the
"permissive formatter" vision. Recommended default.
2. **Formatter + linter** — reimplement a curated subset of B too, to remain a drop-in
replacement for today's standard. Much larger; B rules don't benefit from the
permissive design and mostly duplicate PHPStan.

My strong lean: **scope the from-scratch tool to concern A (formatting)**, and separately
decide which of the B rules (if any) are worth keeping vs delegating to PHPStan. Confirm
with the user before committing — this decision drives the entire architecture.

## Test data format worth copying
Each sniff has `tests/Data/<Rule>/...` with `X.php` (input) + `X.php.fixed` (expected
output) pairs. This golden-file fixture style is a good, simple regression harness to keep
for the new formatter (input → format → compare to `.fixed`).
68 changes: 68 additions & 0 deletions notes/02-no-width-based-rules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# DECISION: avoid all / almost all width-based rules (user, 2026-07-17)

This is the most architecture-shaping decision so far. Read alongside `20` and `21`.

## What it means
No (or almost no) rule keys off the printed **line width** / column count. We do NOT have a
"max line length" that triggers wrapping. We never decide flat-vs-expanded because a line
is "too long".

## Why it's central to the permissive vision
A width-based formatter (Prettier, oxc, Ruff, Biome, dprint, csharpier, gofmt…) MUST choose
flat-vs-expanded for the user: the column threshold forces exactly one form. A permissive
formatter says "you chose flat or expanded; both are allowed; I preserve your choice."
**Removing width IS what makes multiple allowed forms possible** — they are the same idea.
`$a = [1, 2]` vs the multi-line array are both legal precisely because no width rule adjudicates.

## Consequence for the researched engines (big)
The **core engine** of every formatter we studied — the Wadler/Prettier "Doc" algebra
(`group`/`indent`/soft·hard·`line`/`if_break`/`fill`) + the two-phase printer whose whole
job is measuring `fits` against `line_width` — exists to make width-driven break decisions.
**Without width rules we do not need it.** This confirms the user's hypothesis that maybe
none of oxc/ruff/dprint's core is applicable. It largely isn't.

### What DOES survive from the research (the non-width parts)
- **Lossless data model**: tree + trivia (CST, or AST+trivia+source) to reproduce untouched
code byte-exact and reason structurally. (biome/mago/ruff)
- **Comment handling**: leading/dangling/trailing classification, print-once invariant. (ruff/biome)
- **Source-signal detection as TRIGGERS, not width**: "newline after opener" / "trailing
comma present" → decide/preserve a form. (dprint/ruff/mago) — but used as structural
triggers, never as width fallback.
- **Re-parse + tree-diff verification gate**. (csharpier)
- **`fmt:off`/ignore + verbatim passthrough**, golden-file fixtures.

### What we DROP
- The `fits`/width-measurement printer, `best_fitting`, width-driven `group` breaking.
- The idea of a single canonical reprint. We do not reprint by default; we preserve.

## Revised architecture (supersedes `20` §3 option C lean)
Shift from a pretty-printer toward a **tree/token localized-edit model** — a modernized,
structured phpcs:
1. Parse to a **lossless tree** (structure + trivia + recoverable source).
2. Run **rules** that inspect the tree. Each rule either:
- normalizes **local whitespace** within whatever form the user chose (spaces around
operators, after commas, indentation depth, blank-line counts), OR
- checks a **structural / count-based** property and, only if violated, rewrites that
construct's layout via a simple mechanical transform (e.g. "≥2 params ⇒ multiline":
put each param on its own line at indent+1; "single-line ⇒ no trailing comma").
None of these measure columns.
3. **Splice** only the touched spans back into the original text (localized edits, à la
phpcs `Fixer`, or nikic/PHP-Parser's format-preserving printer which reprints only
changed nodes). Everything untouched stays byte-identical → zero churn.
4. **Verify** by re-parsing output and structurally diffing against input (semantics
unchanged; only whitespace/allowed-token-moves differ).

## Rules that FORCE a form change are fine — they're just not width-based
The incumbent already has non-width triggers we keep:
- `RequireMultiLineMethodSignature minParametersCount=2` — **count-based**, not width.
- `RequireTrailingCommaInCall` + `DisallowTrailingCommaInCall onlySingleLine=true` —
layout-consistency: multiline ⇒ trailing comma; single-line ⇒ none.
- `SingleLineArrayWhitespace`, `MultiLineArrayEndBracketPlacement` — normalize whichever
form is used.
When such a rule forces expansion, generating the expanded layout is a mechanical
per-construct transform (elements → own lines at indent+1), NOT a width-fitting search.

## Open sub-question
"almost all" — are there ANY width-adjacent rules we keep? e.g. do we still want an
*advisory* max-line-length **report** (not an autofix)? Probably out of scope for a pure
formatter; PHPStan/editor can warn. Confirm, but default = no width anywhere.
91 changes: 91 additions & 0 deletions notes/03-core-invariant-and-array-forms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Core invariant + allowed-form examples (user-provided)

## THE core invariant (derived from user's array examples, 2026-07-17)

> **Vertical layout is the author's choice and is PRESERVED. Horizontal whitespace is
> NORMALIZED by rules.**

- **Vertical** = where line breaks go and where blank lines go (whether a construct is on
one line or many, how elements are grouped across lines, blank lines between them).
The formatter does NOT impose this. It preserves what the author wrote.
- **Horizontal** = spaces/tabs *within* a line (space after comma, spacing around
operators, no space just inside `[`/`(`, indentation of a line). The formatter DOES
normalize this to the single allowed spacing.

**Permissiveness is NARROW and surgical — the tool still enforces a LOT.** The only thing
relaxed is the *vertical arrangement*: where line breaks and blank lines fall, how many
elements sit on a line, row grouping. Everything else is strictly enforced and
deterministic — comma placement (one space after, none before; trailing comma iff
multiline), indentation (each line snapped to its nesting depth, spaces not tabs), bracket
spacing, spacing around operators/keywords/`=>`, etc. So the rule *count* is large; the
permissiveness is a single, well-defined carve-out, not a general "anything goes".

NOTE — indentation enforcement specifically requires the **structural/depth layer**: to
force "one level deeper than the statement" we must know each token's nesting depth, which
needs bracket-matching / parent links (the CST-lite in `30`), not a flat token list. This
is the rule class a naive token-only tool gets wrong.

This single principle implies almost everything else:
- It implies **no width-based rules** (a max-line-length would override the author's
vertical choice → contradiction). Width-free is a *consequence* of this invariant.
- It implies **multiple allowed forms** (the author's vertical layout is accepted as-is).
- It implies a **localized-edit / trivia-aware engine**: we edit horizontal whitespace
trivia in place and leave line-structure trivia alone — we do NOT re-render constructs
through a layout engine (that would destroy the preserved vertical layout).
- Exceptions are **structural triggers**, not layout preferences: e.g. "multiline ⇒
require trailing comma", "single-line ⇒ forbid trailing comma", count-based "≥N params ⇒
multiline". These constrain vertical layout only at the edges; they don't reflow.

This is MORE permissive than every formatter researched (dprint/mago/Prettier expand to
one-element-per-line; we don't). Confirms none of their layout engines apply — only their
trivia/CST data model + comment handling + verification ideas do (see `02`).

## Array — allowed forms (all VALID, none rewritten into another)

```php
// 1. single line, no trailing comma, one space after comma, no space inside brackets
$a = [1, 2];

// 2. fully expanded, one element per line, trailing comma
$a = [
1,
2,
];

// 3. expanded, MULTIPLE elements per line (author's row grouping preserved), trailing comma
$a = [
1, 2,
3, 4,
];

// 4. expanded, rows grouped with BLANK LINES between groups (preserved), trailing comma
$a = [
1, 2,

3, 4,
5, 6,
];
```

### What the formatter WOULD still normalize inside these (horizontal only)
- exactly one space after each `,` (so `1,2` → `1, 2`); no space before `,`
- no space just inside `[` / `]` on single-line (`[ 1, 2 ]` → `[1, 2]`)
- indentation of each continuation line = one level deeper than the line with `$a`
(spaces, per existing tab-width=4 / DisallowTabIndent)
- closing `]` on its own line aligned with the statement (for multiline forms)
- trailing comma: present iff multiline (structural trigger, not layout)
- collapse runs of >1 blank line? OPEN QUESTION — example 4 has a single blank line;
need to decide if 2+ blank lines inside a collection are clamped to 1 (most tools do)
or preserved. Likely clamp to 1 for consistency with blank-line rules elsewhere.

### What it must NOT do
- must NOT move elements to one-per-line, or join rows, or change how many elements are
on a line, or remove the author's blank-line grouping. That vertical structure is the
author's and is preserved.

## To generalize (D7 content, later)
Enumerate the same "allowed vertical forms + normalized horizontal whitespace + structural
triggers" for: call arguments, parameter lists, match arms, array destructuring, chained
method calls, binary/logical operator chains, ternaries, `use` import lists, attributes,
class member layout. Each follows the SAME invariant; the only per-construct specifics are
the structural triggers (e.g. trailing comma applicability, count-based multiline).
Loading