@sinemacula/coding-standards 1.17.0 → 1.19.0

package/README.md

@@ -2,6 +2,8 @@
 
 [![Latest Stable Version](https://img.shields.io/packagist/v/sinemacula/coding-standards.svg)](https://packagist.org/packages/sinemacula/coding-standards)
 [![npm Version](https://img.shields.io/npm/v/@sinemacula/coding-standards.svg)](https://www.npmjs.com/package/@sinemacula/coding-standards)
+[![Build Status](https://github.com/sinemacula/coding-standards/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/sinemacula/coding-standards/actions/workflows/tests.yml)
+[![Quality Gates](https://github.com/sinemacula/coding-standards/actions/workflows/quality-gates.yml/badge.svg?branch=master)](https://github.com/sinemacula/coding-standards/actions/workflows/quality-gates.yml)
 [![Maintainability](https://qlty.sh/gh/sinemacula/projects/coding-standards/maintainability.svg)](https://qlty.sh/gh/sinemacula/projects/coding-standards)
 [![Code Coverage](https://qlty.sh/gh/sinemacula/projects/coding-standards/coverage.svg)](https://qlty.sh/gh/sinemacula/projects/coding-standards)
 [![Total Downloads](https://img.shields.io/packagist/dt/sinemacula/coding-standards.svg)](https://packagist.org/packages/sinemacula/coding-standards)
@@ -86,8 +88,8 @@ parameters:
 
 For Laravel projects, also install
 [`sinemacula/coding-standards-laravel`](https://github.com/sinemacula/coding-standards-laravel) and reference its
-`SineMaculaLaravel` PHPCS standard (which includes this one) in place of `SineMacula`. It adds the
-Laravel-specific sniffs and PHPStan rules; see that package's README for setup.
+`SineMaculaLaravel` PHPCS standard (which includes this one) in place of `SineMacula`. It adds the Laravel-specific
+sniffs and PHPStan rules; see that package's README for setup.
 
 ### Biome (JavaScript / TypeScript)
 
@@ -112,9 +114,8 @@ After installing the npm package, extend the shared Biome config from your proje
 }
 ```
 
-`extends` paths are resolved through normal Node module lookup, so the package only needs to be installed (no path
-math against `node_modules/` required). Project-specific `files.includes` and `files.excludes` stay in the consumer
-config.
+`extends` paths are resolved through normal Node module lookup, so the package only needs to be installed (no path math
+against `node_modules/` required). Project-specific `files.includes` and `files.excludes` stay in the consumer config.
 
 ### ESLint (JavaScript / TypeScript)
 
@@ -134,9 +135,9 @@ The package exposes three flat-config entry points:
 - `@sinemacula/coding-standards/js/eslint/type-checked` - the opt-in type-aware layer. It includes the base layer and
   adds the cross-file / type-driven rules, so it needs a consumer `tsconfig`; use it in place of the base layer where
   one exists.
-- `@sinemacula/coding-standards/js/eslint/vue` - the opt-in Vue layer for single-file components. Unlike the
-  type-aware layer it carries no base rules of its own, so spread it *alongside* whichever layer the repository
-  already uses rather than in place of one.
+- `@sinemacula/coding-standards/js/eslint/vue` - the opt-in Vue layer for single-file components. Unlike the type-aware
+  layer it carries no base rules of its own, so spread it *alongside* whichever layer the repository already uses rather
+  than in place of one.
 
 Create an `eslint.config.js` (or `.qlty/configs/eslint.config.js` when wired through Qlty) that spreads the layer you
 want. Without a `tsconfig`, use the base layer:
@@ -169,23 +170,23 @@ export default [...typeChecked, ...vue];
 ```
 
 The Vue layer registers the single-file-component parser (without it `.vue` files are not linted at all), resolves
-`<script lang="ts">` blocks through the TypeScript parser, and holds component filenames to kebab-case. It also
-carries the template layout rules, which is the one place ESLint takes on formatting: Biome does not understand
-single-file components, so `.vue` markup would otherwise go unformatted entirely. Those rules are aligned to the
-shared four-space indent.
+`<script lang="ts">` blocks through the TypeScript parser, and holds component filenames to kebab-case. It also carries
+the template layout rules, which is the one place ESLint takes on formatting: Biome does not understand single-file
+components, so `.vue` markup would otherwise go unformatted entirely. Those rules are aligned to the shared four-space
+indent.
 
 When wiring ESLint through Qlty, the shared eslint plugin sandbox installs only `eslint`, `jest`, and `prettier` by
-default, so the flat config's imports of this package and `typescript-eslint` fail to resolve. Widen the install
-filter in your `.qlty/qlty.toml` so the sandbox carries them (this repository's `source.toml` exports the same
-override, but source-exported plugin definitions do not reliably propagate, so mirror it consumer-side):
+default, so the flat config's imports of this package and `typescript-eslint` fail to resolve. Widen the install filter
+in your `.qlty/qlty.toml` so the sandbox carries them (this repository's `source.toml` exports the same override, but
+source-exported plugin definitions do not reliably propagate, so mirror it consumer-side):
 
 ```toml
 [plugins.definitions.eslint]
 package_filters = ["@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc"]
 ```
 
-Repositories enabling the Vue layer widen the same filter further, since its plugins have to resolve inside that
-sandbox too:
+Repositories enabling the Vue layer widen the same filter further, since its plugins have to resolve inside that sandbox
+too:
 
 ```toml
 [plugins.definitions.eslint]
@@ -204,17 +205,25 @@ package (as above) and extend the base from your `tsconfig.json`:
 {
     "extends": "@sinemacula/coding-standards/js/tsconfig.base.json",
     "compilerOptions": {
-        "lib": ["ES2023", "DOM", "DOM.Iterable"],
-        "types": ["node"]
+        "lib": [
+            "ES2023",
+            "DOM",
+            "DOM.Iterable"
+        ],
+        "types": [
+            "node"
+        ]
     },
-    "include": ["src"]
+    "include": [
+        "src"
+    ]
 }
 ```
 
-The base carries only the environment-independent options: the full strictness set and the module/resolution
-discipline. Everything environment-specific stays in the consuming repo and layers on top - `lib` (DOM for the browser,
-none for a Node service), `types`, Vue's `jsx`/`jsxImportSource`, `paths`, `noEmit`, and the `include`/`exclude` globs.
-The `target` and `module` defaults suit bundler-built apps and libraries; a non-bundler project overrides them.
+The base carries only the environment-independent options: the full strictness set and the module/resolution discipline.
+Everything environment-specific stays in the consuming repo and layers on top - `lib` (DOM for the browser, none for a
+Node service), `types`, Vue's `jsx`/`jsxImportSource`, `paths`, `noEmit`, and the `include`/`exclude` globs. The`target`
+and `module` defaults suit bundler-built apps and libraries; a non-bundler project overrides them.
 
 The base sets `noPropertyAccessFromIndexSignature`, so a property that comes from an index signature is accessed with
 brackets (`config['key']`), not a dot. Biome cannot see types and so cannot tell that access apart from a normal one,
@@ -273,6 +282,7 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 |------------------------------------------------------------|-----------------------------------------------------------------------------|
 | `SineMacula.Attributes.DisallowToolingAttribute`           | No IDE/tooling attributes (e.g. `JetBrains\PhpStorm`).                      |
 | `SineMacula.Classes.RequireFinalClass`                     | Concrete classes must be `final` or `abstract` (`@inheritable` opts out).   |
+| `SineMacula.Classes.RequireReadonlyClass`                  | A class with only `readonly` properties (no statics) must be `readonly`.    |
 | `SineMacula.Classes.RequireReadonlyPublicProperty`         | Public properties (declared or promoted) must be `readonly`.                |
 | `SineMacula.Commenting.CommentLineLength`                  | Standalone comment prose wrapped to 80 chars; premature wraps also fixed.   |
 | `SineMacula.Commenting.ConsistentEnumCaseComments`         | Enum case docs are all-or-nothing within an enum.                           |
@@ -294,6 +304,7 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 | `SineMacula.NamingConventions.DisallowInterfacePrefix`     | Interface names must not use the Hungarian `I` prefix.                      |
 | `SineMacula.NamingConventions.ValidEnumCaseName`           | Enum cases must be `SCREAMING_SNAKE_CASE`.                                  |
 | `SineMacula.NamingConventions.ValidGlobalFunctionName`     | Global functions must be declared in `snake_case`.                          |
+| `SineMacula.TypeHints.DisallowFullyQualifiedConstantType`  | Constant types must be imported, not inline fully-qualified names.          |
 | `SineMacula.TypeHints.RequireConstantType`                 | Class/interface/enum/trait constants must declare a native type.            |
 | `SineMacula.WhiteSpace.PromotedConstructorSpacing`         | Blank line above each promoted-constructor parameter.                       |
 
@@ -325,28 +336,28 @@ type-checked layer.
 
 `boolean-method-name` takes `additionalPrefixes`, `additionalPredicates` and `additionalCommandVerbs` (string arrays)
 to widen the accepted vocabulary from a consumer config. `max-methods-per-class` takes `max`, `no-base-error` takes
-`allow`, and `require-copyright` takes `tags` to adjust their defaults. `align-doc-tags` takes `tags` and `column`,
-the column counting from the `@`, so the default of 14 gives `@author` six spaces and `@copyright` three.
-Together `single-line-property-doc` and `multiline-function-doc` set a member's comment shape by its kind: data
-members (interface property signatures, enum members and data class fields) take one line, while methods, interface
-method signatures and class fields holding a function take several. A data comment is never required, only held to
-one line where present; a free function keeps the freedom of either shape.
+`allow`, and `require-copyright` takes `tags` to adjust their defaults. `align-doc-tags` takes `tags` and `column`, the
+column counting from the `@`, so the default of 14 gives `@author` six spaces and `@copyright` three. Together
+`single-line-property-doc` and `multiline-function-doc` set a member's comment shape by its kind: data members
+(interface property signatures, enum members and data class fields) take one line, while methods, interface method
+signatures and class fields holding a function take several. A data comment is never required, only held to one line
+where present; a free function keeps the freedom of either shape.
 
 `comment-line-wrap` takes `maxLength` (default 80) and is the syntax-only counterpart of the PHP
 `SineMacula.Commenting.CommentLineLength` sniff. It fills standalone `//` runs and multi-line docblock prose greedily,
 reporting an overflowing line and a prematurely wrapped line on their own footings and autofixing both. Markdown
 headings, docblock tag lines, machine-parsed tool directives (`eslint`, `biome-ignore`, `@ts-`, `Stryker`, `c8`/`v8`/
-`istanbul ignore`, `@vite-ignore` and the like), fenced code, an indented code or command block, a doc-tag whose
-value opens a multi-line bracketed type (an `array{...}` shape, a `<...>` generic or a `\Closure(...)` signature),
-tables, separators, a line whose overflow is a single unbreakable token such as a long name or URL, trailing comments
-after code and compact single-line docblocks are left untouched.
+`istanbul ignore`, `@vite-ignore` and the like), fenced code, an indented code or command block, a doc-tag whose value
+opens a multi-line bracketed type (an `array{...}` shape, a `<...>` generic or a `\Closure(...)` signature), tables,
+separators, a line whose overflow is a single unbreakable token such as a long name or URL, trailing comments after code
+and compact single-line docblocks are left untouched.
 
 The base layer also switches on a set of built-in rules: `@typescript-eslint/no-explicit-any`, `curly` (a brace on every
 control statement, as PSR-12 already requires on the PHP side), `max-lines-per-function` (50 lines, test code exempt)
-and `max-depth` (4), plus `eslint-plugin-jsdoc` rules that require a documentation comment
-on every declared function, method, class, interface member and class field, forbid types in `@param`/`@returns` (the
-tags themselves are welcome, types belong in the signature) and keep a blank line above every documentation block,
-single-line blocks included. The type-checked layer adds `@typescript-eslint/explicit-module-boundary-types` and
+and `max-depth` (4), plus `eslint-plugin-jsdoc` rules that require a documentation comment on every declared function,
+method, class, interface member and class field, forbid types in `@param`/`@returns` (the tags themselves are welcome,
+types belong in the signature) and keep a blank line above every documentation block, single-line blocks included. The
+type-checked layer adds `@typescript-eslint/explicit-module-boundary-types` and
 `@typescript-eslint/only-throw-error`.
 
 ## Requirements
@@ -357,12 +368,14 @@ single-line blocks included. The type-checked layer adds `@typescript-eslint/exp
 ## Testing
 
 ```bash
-composer test           # PHPUnit suite for the custom sniffs and PHPStan rule
-composer test:coverage  # suite with Clover coverage output
-composer analyse        # PHPStan static analysis
-composer check          # static analysis and lint via qlty
-composer format         # format via qlty
-composer smells         # duplication / complexity smells via qlty
+composer test                # PHPUnit suite for the custom sniffs and PHPStan rule
+composer test:coverage       # suite with Clover coverage output
+composer test:mutation       # Infection mutation gate (min MSI 90)
+composer test:mutation:full  # full mutation suite without thresholds
+composer analyse             # PHPStan static analysis
+composer check               # static analysis and lint via qlty
+composer format              # format via qlty
+composer smells              # duplication / complexity smells via qlty
 ```
 
 ## Changelog

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sinemacula/coding-standards",
-    "version": "1.17.0",
+    "version": "1.19.0",
     "description": "Centralized coding standards, static analysis configurations, and code quality tooling for all Sine Macula repositories.",
     "license": "Apache-2.0",
     "author": "Ben Carey <bdmc@sinemacula.co.uk>",