sinemacula / coding-standards
Centralized coding standards, static analysis configurations, and code quality tooling for all Sine Macula repositories.
Package info
github.com/sinemacula/coding-standards
Type:phpcodesniffer-standard
pkg:composer/sinemacula/coding-standards
Requires
- php: ^8.3
- friendsofphp/php-cs-fixer: ^3.95.19
Requires (Dev)
- dealerdirect/phpcodesniffer-composer-installer: ^1.0
- infection/infection: ^0.33.2
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.1
- phpstan/phpstan-phpunit: ^2.0
- phpunit/phpunit: ^12
- slevomat/coding-standard: ^8.0
- squizlabs/php_codesniffer: ^3.13.6 || ^4.0.2
- symfony/console: ^7.4
Suggests
- phpstan/extension-installer: Auto-registers the shared PHPStan config and installed PHPStan extensions (required for the shared phpstan.neon to load).
- phpstan/phpstan-phpunit: PHPUnit-aware PHPStan rules: data-provider validation, setUp()/tearDown() parent calls, assertSame discipline, and @covers / mock target existence. Auto-registers via phpstan/extension-installer.
Provides
None
Conflicts
None
Replaces
None
- dev-master
- v1.31.2
- v1.31.1
- v1.31.0
- v1.30.2
- v1.30.1
- v1.30.0
- v1.29.0
- v1.28.0
- v1.27.1
- v1.27.0
- v1.26.0
- v1.25.0
- v1.24.1
- v1.24.0
- v1.23.2
- v1.23.1
- v1.23.0
- v1.22.0
- v1.21.0
- v1.20.2
- v1.20.1
- v1.20.0
- v1.19.1
- v1.19.0
- v1.18.0
- v1.17.0
- v1.16.0
- v1.15.0
- v1.14.0
- v1.13.0
- v1.12.3
- v1.12.2
- v1.12.1
- v1.12.0
- v1.11.0
- v1.10.0
- v1.9.2
- v1.9.1
- v1.9.0
- v1.8.4
- v1.8.3
- v1.8.2
- v1.8.1
- v1.8.0
- v1.7.2
- v1.7.1
- v1.7.0
- v1.6.0
- v1.5.1
- v1.5.0
- v1.4.0
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-fix/vue-under-qlty
- dev-fix/php-cs-fixer-symfony-8
- dev-ci/rename-dependency-updates-workflow
This package is auto-updated.
Last update: 2026-11-18 03:11:43 UTC
README
Shared coding standards, static analysis configs and the Qlty source for Sine Macula repositories.
The packages ship configuration only, with no runtime dependencies. Consuming projects install the tools themselves.
Installation
Composer (PHP CS Fixer, PHPCS, PHPStan)
composer require --dev sinemacula/coding-standards
npm (Biome, ESLint, tsconfig)
npm install --save-dev @sinemacula/coding-standards
The npm package ships only the static configs (js/, markdown/, yaml/, shell/, security/, swift/,
terraform/). The PHP code ships in the Composer package.
Qlty (Swift, Terraform)
Swift and Terraform consumers need neither package. The Qlty source supplies the shared configs and pins the tools.
Usage
Each consuming project adds thin wrapper files at its root that reference the shared configs.
PHP CS Fixer
Create a .php-cs-fixer.dist.php at your project root:
<?php use SineMacula\CodingStandards\PhpCsFixerConfig; return PhpCsFixerConfig::make([ __DIR__ . '/src', __DIR__ . '/tests', ]);
Pass rule overrides as a second argument:
return PhpCsFixerConfig::make( [__DIR__ . '/src', __DIR__ . '/tests'], ['strict_comparison' => false], );
Give the qlty plugin this package for its tool sandbox, and do not set package_file or package_filters on it:
[[plugin]] name = "php-cs-fixer" extra_packages = ["sinemacula/coding-standards@1.23.0"]
extra_packages installs into the tool sandbox only, so it does not touch your dependency graph. Setting
package_file makes qlty ignore extra_packages silently. Use an exact version: the shared Renovate preset resolves a
caret range to the newest release it already allows, so a range is reported as current and never raised. The entry
lives in your own file because the source, consumed at a tag, cannot pin the package it is published with.
The shared source runs qlty on PHP 8.5. A project that analyses on another PHP version sets its own runtime, and qlty resolves each tool sandbox for it:
[runtimes.enabled] php = "8.3"
PHPCS
The SineMacula standard is auto-discovered through the phpcodesniffer-standard Composer type. Create a phpcs.xml
at your project root:
<?xml version="1.0"?> <ruleset name="Project"> <rule ref="SineMacula"/> <file>src</file> <file>tests</file> </ruleset>
PHPStan
The base config is auto-included through extra.phpstan.includes in composer.json. Your project's phpstan.neon
only needs its paths:
parameters: paths: - src - tests
Point the qlty plugin at the Composer file that holds your analysis stack, and leave its version to the source:
[[plugin]] name = "phpstan" package_file = "composer.json"
Do not set level. qlty's phpstan driver passes --level=9 on the command line, which overrides the config file.
The base config enables checked-exception analysis: every exception a method can throw must appear in its @throws
tag, except the programming-error and infrastructure exceptions listed in php/phpstan-base.neon (the
LogicException, RuntimeException and Error families among them). Suppress a deliberate case with
@phpstan-ignore missingType.checkedException. The PHPCS standard asks for a @throws tag for each exception thrown in
a method's body, checked or not, and accepts a tag for an exception a callee propagates; PHPStan's tooWideThrowType
reports a tag for an exception nothing can throw.
argument.type is reported. The shared PHP CS Fixer rules declare strict_types, so an argument of the wrong type is
a TypeError at runtime. Narrow the value where it is read ($request->integer('limit'), Config::integer(...), a
null check) or cast it explicitly where the conversion is intended.
Laravel projects
Also install 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.
Biome (JavaScript / TypeScript)
Through Qlty, the source stages the shared config at the repository root as biome.shared.json while Biome runs.
Enable Biome 2.2.0 or later in your .qlty/qlty.toml:
[[plugin]] name = "biome" version = "2.5.6"
Then create .qlty/configs/biome.json, which extends the shared config by that relative path:
{
"$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
"root": true,
"extends": [
"./biome.shared.json"
],
"files": {
"includes": [
"**",
"!**/node_modules/**",
"!**/vendor/**"
]
}
}
The project config is required; without one, Biome runs on its own defaults. Settings in it apply over the shared
config, so project-specific files.includes and overrides go there. A project config that still extends
js/biome.json must switch to ./biome.shared.json. Leave the Biome plugin definition and its drivers as the source
sets them: a --config-path or exported_config_paths override breaks the staging. Biome before 2.2.0 resolves the
relative extends from the staged file's real location and fails to load it.
Without Qlty, install the npm package and extend @sinemacula/coding-standards/js/biome.shared.json from the
project's biome.json. The shared config leaves Biome's VCS integration off, because Qlty formats a copy of each file
outside the repository; a project that runs Biome directly can turn it on in its own biome.json.
ESLint (JavaScript / TypeScript)
ESLint runs alongside Biome. Biome owns formatting and the syntactic lint; ESLint adds this package's custom structural rules and the opt-in type-aware rules. Install:
npm install --save-dev eslint typescript typescript-eslint eslint-plugin-jsdoc yaml-eslint-parser \
@sinemacula/coding-standards
yaml-eslint-parser is imported by the base layer, so the config fails to load without it, even in a repository with
no YAML.
The package exposes three flat-config entry points:
@sinemacula/coding-standards/js/eslint- the base layer of syntax-only rules. Needs notsconfig. Covers.ts/.jsand, for the comment-width rule alone,.yml/.yaml.@sinemacula/coding-standards/js/eslint/type-checked- the base layer plus the type-aware rules. Needs atsconfig; use it in place of the base layer where one exists.@sinemacula/coding-standards/js/eslint/vue- the Vue single-file-component layer. It carries no base rules, so spread it after whichever layer the repository uses.
Create an eslint.config.js (or .qlty/configs/eslint.config.mjs when wired through Qlty) that spreads the layer
you want. Without a tsconfig:
import sm from '@sinemacula/coding-standards/js/eslint'; export default [...sm];
With a tsconfig:
import typeChecked from '@sinemacula/coding-standards/js/eslint/type-checked'; export default [...typeChecked];
Vue repositories add the Vue toolchain and spread the Vue layer after their existing one:
npm install --save-dev eslint-plugin-vue vue-eslint-parser eslint-plugin-check-file
import typeChecked from '@sinemacula/coding-standards/js/eslint/type-checked'; import vue from '@sinemacula/coding-standards/js/eslint/vue'; export default [...typeChecked, ...vue];
The Vue layer registers the single-file-component parser, resolves <script lang="ts"> through the TypeScript
parser, and requires PascalCase component filenames (UserCard.vue). It also carries the template layout rules, set to
a four-space indent, because Biome cannot format .vue markup. To match, the shared Biome config accepts PascalCase as
well as kebab-case under any components/ directory, so a component's tests and stories can share its name
(UserCard.test.ts). Its identifier naming accepts consecutive capitals, so a component whose name opens with an
acronym or a one-letter prefix (UIButton) is imported under that name.
Through Qlty, enable the eslint plugin on your package.json. Its sandbox installs only eslint, jest and
prettier from that file by default, so widen the filter or the config's imports fail to resolve:
[[plugin]] name = "eslint" package_file = "package.json" package_filters = [ "@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc", "yaml-eslint-parser", ]
With the Vue layer, add its packages to the filter, and route .vue files to ESLint. Qlty has no vue file type and
hands ESLint only JavaScript and TypeScript, so without the last two blocks no single-file component is linted:
[[plugin]] name = "eslint" package_file = "package.json" package_filters = [ "@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc", "yaml-eslint-parser", "eslint-plugin-vue", "vue-eslint-parser", "eslint-plugin-check-file", ] [file_types.vue] globs = ["*.vue", "**/*.vue"] [plugins.definitions.eslint] file_types = ["javascript", "typescript", "jsx", "tsx", "vue"]
The routing stays with the Vue layer rather than the shared source, because ESLint cannot parse a .vue file without
that layer's parser.
TypeScript (tsconfig)
Extend the shared base from your tsconfig.json:
{
"extends": "@sinemacula/coding-standards/js/tsconfig.base.json",
"compilerOptions": {
"lib": [
"ES2023",
"DOM",
"DOM.Iterable"
],
"types": [
"node"
]
},
"include": [
"src"
]
}
The base carries the strictness and module-resolution options only. Environment-specific settings stay in the
consuming repository: lib, types, Vue's jsx/jsxImportSource, paths, noEmit and include/exclude. The
target and module defaults suit bundler-built code; a non-bundler project overrides them.
The base sets noPropertyAccessFromIndexSignature, so index-signature properties are read with brackets
(config['key']). Biome cannot see types, so its useLiteralKeys rule is off and the type-checked ESLint layer's
@typescript-eslint/dot-notation enforces dot access for declared properties.
Knip (JavaScript / TypeScript)
Knip needs no shared config; its defaults find entry points from package.json and its plugins. Enable it in
.qlty/qlty.toml:
[[plugin]] name = "knip"
Add a knip.json at the project root only for what Knip cannot find on its own, such as an entry point outside its
defaults. Knip has no extends, so that file holds the project's whole Knip config.
Qlty
Reference this repository as a source in your project's .qlty/qlty.toml, pinning tag to the latest
release:
[[source]] name = "sinemacula" repository = "https://github.com/sinemacula/coding-standards" tag = "<version>"
The source enables these plugins at the versions and modes every project runs: TruffleHog, markdownlint, yamllint, actionlint, OSV-Scanner, Trivy (misconfiguration and dependency scanning), editorconfig-checker, PHPCS, PHP CS Fixer, PHPStan, Radarlint, Terraform (formatting only) and TFLint. A plugin with nothing to lint in a repository does not run there. The source also sets the PHP runtime and shared excludes, stops qlty discarding PHPCS 4.x findings as a crash, supplies the ESLint and Biome wiring for projects that enable them, and sets the zizmor version for projects that enable zizmor.
List a plugin in your own file only to change it. A version or mode you leave out is taken from the source, but a list
you set, such as drivers or extra_packages, replaces the source's. To turn a plugin off, set mode = "disabled".
The source sets the smell policy (see source.toml): smells run in comment mode, the parameter-count check is off,
and the return-statement, function-complexity and file-complexity thresholds are raised. Leave [smells] out of your
own .qlty/qlty.toml to inherit it. To change a threshold, set it there; to re-enable a check the source switches off,
also set enabled = true, because the two files are merged.
The source ignores three Radarlint rules through [[triage]]:
php:S100(function naming) wants camelCase everywhere, which conflicts with the snake_case global functionsSineMacula.NamingConventions.ValidGlobalFunctionNamerequires. PSR1 already covers methods.php:S1144(unused private method) cannot see a call from a used trait or a first-class callable such asself::method(...). PHPStan reports private methods nothing calls.php:S1172(unused parameter) flags the positional parameters a framework callback must declare to reach a later one, such as$attributein a validation closure taking($attribute, $value, $fail).
Your own [[triage]] entries are added alongside the source's.
Swift (SwiftLint and SwiftFormat)
Swift repositories consume the shared policy through Qlty. Enable the default source for the tools, this repository for the configs, and both native plugins:
config_version = "0" # SwiftLint's own `excluded:` list only applies when it walks a directory. Qlty # passes explicit file paths, so generated and third-party sources are excluded # here. exclude_patterns = [ ".build/**", "build/**", "DerivedData/**", "Carthage/**", "Pods/**", "vendor/**", "**/Generated/**", ] test_patterns = [ "**/*Tests.swift", "**/Tests/**", ] [[source]] name = "default" default = true [[source]] name = "sinemacula" repository = "https://github.com/sinemacula/coding-standards" tag = "<version>" [[plugin]] name = "swiftlint" [[plugin]] name = "swiftformat" mode = "comment"
This is the configuration the package's integration test runs. Run formatting and linting locally:
qlty fmt --all qlty check --all
SwiftLint and SwiftFormat are native macOS plugins that Qlty Cloud's Linux workers cannot run, so every Swift consumer
needs a macOS CI job that verifies formatting and runs qlty check. Qlty Cloud still provides its built-in Swift
maintainability, duplication, complexity, security and coverage analysis.
The policy targets Swift 6 and holds no application-specific paths or architecture rules. Compiler checks such as strict concurrency, warnings-as-errors, platform availability and test builds stay with the consuming project.
SwiftLint has no configuration inheritance: a .swiftlint.yml in a consuming repository replaces the shared policy
entirely. Raise a pull request here instead, or copy the shared file wholesale and edit the copy.
Terraform (Terraform and TFLint)
The Qlty source runs terraform fmt and TFLint at pinned versions with the shared .tflint.hcl. Keep
.terraform-version at the pinned Terraform release. To change the version, give the terraform plugin a version in
your own .qlty/qlty.toml and repeat drivers = ["format"]; an entry without drivers runs all of them, including a
validate driver that cannot pass without terraform init.
Validate in CI with the reusable workflow, which initialises without a backend and runs terraform validate:
jobs: terraform: uses: sinemacula/.github/.github/workflows/terraform-tests.yml@<version> permissions: contents: read
terraform fmt indents with two spaces. Add a section for it to your .editorconfig:
[*.{tf,tfvars,hcl}] indent_size = 2
A .tflint.hcl in a consuming repository replaces the shared policy. Raise a pull request here instead.
What's Included
| Path | Tool | Description |
|---|---|---|
src/PhpCsFixerConfig.php |
PHP CS Fixer | Factory class for building PHP CS Fixer configurations |
php/.php-cs-fixer.rules.php |
PHP CS Fixer | Shared rules array (PSR-12 base + org conventions) |
SineMacula/ruleset.xml |
PHPCS | Auto-discovered coding standard (PSR-12 + exclusions) |
php/phpstan-base.neon |
PHPStan | Base config (org-wide ignored errors + settings) |
js/biome.shared.json |
Biome | JavaScript / TypeScript formatter + linter rules |
js/eslint/ |
ESLint | Structural, type-aware + Vue rules; runs with Biome |
js/eslint/ (YAML block) |
ESLint | Comment width in .yml / .yaml; yamllint owns rest |
js/tsconfig.base.json |
TypeScript | Shared strictness and module-resolution options |
markdown/.markdownlint.json |
markdownlint | Markdown linting rules |
yaml/.yamllint.yaml |
yamllint | YAML linting rules |
shell/.shellcheckrc |
ShellCheck | Shell script linting rules |
security/.gitleaks.toml |
Gitleaks | Secret-detection ruleset |
security/trivy.yaml |
Trivy | Skips generated and installed trees when scanning |
security/zizmor.yml |
zizmor | SHA-pins third-party actions; two noisy audits off |
editorconfig/.editorconfig-checker.json |
editorconfig-checker | Disables only the max-line-length check |
swift/.swiftlint.yml |
SwiftLint | Shared Swift 6 lint, safety, concurrency, and metrics |
swift/.swiftformat |
SwiftFormat | Shared deterministic Swift 6 formatting policy |
terraform/.tflint.hcl |
TFLint | Bundled Terraform ruleset at the all preset |
Rules
The custom rules this package enforces on top of PSR-12. Bypass a deliberate exception with the native directive:
// phpcs:ignore <code> for a sniff, @phpstan-ignore <identifier> for a PHPStan rule,
// eslint-disable-next-line <rule> for an ESLint rule.
PHPCS sniffs
| Sniff | Enforces |
|---|---|
SineMacula.Attributes.DisallowToolingAttribute |
No IDE/tooling attributes (e.g. JetBrains\PhpStorm). |
SineMacula.Classes.RequireCombinedTraitImport |
Traits must be imported in one use statement, not one per line. |
SineMacula.Classes.RequireFinalClass |
Concrete classes must be final or abstract (@inheritable opts out). |
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. |
SineMacula.Commenting.DisallowTagDescription |
@param and @throws tags carry no description; autofixable. |
SineMacula.Commenting.MultilineMethodComment |
A method's doc comment must span multiple lines. |
SineMacula.Commenting.RequireConstantComment |
Every class/interface/enum/trait constant needs a doc comment. |
SineMacula.Commenting.RequireCopyrightTag |
Class/interface/enum/trait docblocks must carry an @copyright tag. |
SineMacula.Commenting.RequireNonPromotedParameterComment |
Plain params mixed with promoted ones need a comment. |
SineMacula.Commenting.RequireParamTag |
Each parameter needs an @param tag naming it; the type may span lines. |
SineMacula.Commenting.RequirePromotedPropertyComment |
Every constructor-promoted property needs a doc comment. |
SineMacula.Commenting.RequireThrowsTag |
Each exception thrown in a function body needs its own @throws tag. |
SineMacula.Commenting.SingleLineMemberComment |
A property, constant or enum-case doc comment sits on one line. |
SineMacula.Exceptions.DisallowBaseException |
No throwing the base \Exception; throw a domain exception. |
SineMacula.Exceptions.RequireEmptyCatchComment |
An empty catch block must comment its intentional swallow. |
SineMacula.Functions.RequireSensitiveParameter |
Secret-named params need #[\SensitiveParameter]; object types exempt. |
SineMacula.Metrics.MaxMethodCount |
A class/interface/trait/enum may declare at most 20 methods (tests exempt). |
SineMacula.Metrics.MethodLength |
A method body may have at most 50 significant lines (tests exempt). |
SineMacula.Namespaces.RequireConcernsNamespace |
Traits must live under a Concerns namespace segment. |
SineMacula.Namespaces.RequireContractsNamespace |
Interfaces must live under a Contracts namespace segment. |
SineMacula.Namespaces.RequireEnumsNamespace |
Enums must live under an Enums namespace segment. |
SineMacula.NamingConventions.BooleanMethodName |
bool methods are predicates; command verbs/@imperative exempt. |
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.Operators.DisallowCoalesceAfterConcat |
No ?? after a bare concatenation, whose fallback can never run. |
SineMacula.TypeHints.RequireConstantType |
Class/interface/enum/trait constants must declare a native type. |
SineMacula.WhiteSpace.PromotedConstructorSpacing |
Blank line above each promoted-constructor parameter. |
DisallowTagDescription exists because the function comment sniff and PHP CS Fixer disagree on a tag description's
case and full stop. A bare tag, @param int $count or @throws \RuntimeException, satisfies both, so the fixer
removes the description, continuation lines included.
RequireParamTag takes over the function comment sniff's @param variable checks, under the same codes and messages,
because that sniff reads only a tag's first line and loses the variable of a type that spans lines. A // phpcs:ignore
for those codes names SineMacula.Commenting.RequireParamTag in place of Squiz.Commenting.FunctionComment. It also
reads a literal type holding a dot ('a.b', 1.5) and a $this type correctly. PHP CS Fixer adds a second @param
for a callable type that names its own parameters, so leave a callable type's parameters unnamed.
Slevomat's fully qualified annotation sniff treats a local type alias used inside another alias's definition as a
class: in @phpstan-type Rows list<Row> it reports Row and its fixer rewrites it to \App\Row. The same happens to
an alias brought in with @phpstan-import-type, and a suppression inside the docblock does not reach it. Until a fixed
release ships, write a local alias's shape out in full (@phpstan-type Rows list<array{id: string}>) and use an
imported alias directly in @param, @return or @var. See REPORTS.md.
Two sniffs take properties that exempt framework code whose names and shapes are fixed by convention:
BooleanMethodNametakesignoredClassSuffixes. Methods of a named class, interface, trait or enum ending in one are not checked, which suits a Laravel policy, whose ability methods (view,update,before) the Gate resolves by name. An anonymous class is never exempt.RequireReadonlyPublicPropertytakesignoredParentClasses, whose subclasses are exempt, andignoredInterfaceProperties, which maps an interface to a comma-separated list of property names exempt in any class whose ownimplementsclause names it, such as a queued job'striesandtimeout.ignoredParentClassPropertiesdoes the same for the parent a class's ownextendsclause names, for jobs that extend a base implementing the contract; a class matching both gets both lists. Only the listed properties are exempt. Parents and interfaces match case-insensitively on their short name, soShouldQueueand\Illuminate\Contracts\Queue\ShouldQueueboth match whether the clause imports the name or writes it fully qualified; an import aliased withasmatches only its alias.
<rule ref="SineMacula.NamingConventions.BooleanMethodName"> <properties> <property name="ignoredClassSuffixes" type="array"> <element value="Policy"/> </property> </properties> </rule> <rule ref="SineMacula.Classes.RequireReadonlyPublicProperty"> <properties> <property name="ignoredInterfaceProperties" type="array"> <element key="ShouldQueue" value="tries,timeout,backoff,maxExceptions,queue,connection,delay"/> </property> <property name="ignoredParentClassProperties" type="array"> <element key="Job" value="tries,timeout,backoff,maxExceptions,queue,connection,delay"/> </property> </properties> </rule>
PHPStan rules
| Identifier | Enforces |
|---|---|
sineMacula.mutableStaticProperty |
Runtime-written static properties; @managed-static opts out; tests exempt. |
sineMacula.readonlyClass |
A final class with only readonly properties must be readonly. |
sineMacula.redundantStaticReference |
In a final class, new static, static:: and instanceof static are self. |
sineMacula.redundantStaticReturnType |
In a final class, a static return type or @return must be self. |
ESLint rules
All rules run in the base layer except boolean-method-name, which resolves return types and so needs the
type-checked layer. comment-line-wrap alone also runs over .yml/.yaml.
| Rule | Enforces |
|---|---|
@sinemacula/no-interface-prefix |
Interface and type-alias names must not use the Hungarian I prefix. |
@sinemacula/require-readonly-public-property |
Public class properties (declared or promoted) must be readonly. |
@sinemacula/valid-enum-member-name |
Enum members must be declared in SCREAMING_SNAKE_CASE. |
@sinemacula/boolean-method-name |
Boolean-returning methods need an is/has/can prefix; @imperative exempt. |
@sinemacula/no-mutable-static |
No mutable exported bindings or mutable static class fields; test code exempt. |
@sinemacula/max-methods-per-class |
A single class may declare at most 20 methods; test code exempt. |
@sinemacula/no-base-error |
Throw a domain-specific Error subclass, never the base Error; test code exempt. |
@sinemacula/require-copyright |
Every file must carry a documentation comment with @copyright and @author. |
@sinemacula/require-file-description |
The same comment must open with a prose summary above those tags. |
@sinemacula/align-doc-tags |
@author and @copyright values line up at a single column; autofixable. |
@sinemacula/single-line-property-doc |
A data member's documentation comment sits on one line; autofixable. |
@sinemacula/multiline-function-doc |
A method's documentation comment spans multiple lines; autofixable. |
@sinemacula/comment-line-wrap |
Standalone comment prose wrapped to 80 chars, YAML included; premature wraps too. |
Options:
boolean-method-name:additionalPrefixes,additionalPredicates,additionalCommandVerbs(string arrays).require-readonly-public-property:ignoredParentClasses.max-methods-per-class:max.no-base-error:allow.require-copyright,require-file-description:tags. A project that narrows one should narrow the other to match.align-doc-tags:tagsandcolumn, counted from the@; the default of 14 gives@authorsix spaces and@copyrightthree.comment-line-wrap:maxLength(default 80).
single-line-property-doc and multiline-function-doc set a member's comment shape by its kind. Data members
(interface property signatures, enum members, data class fields) take one line; methods, interface method signatures
and class fields holding a function take several. A data comment is not required, only held to one line where present.
A free function may use either shape.
require-copyright and require-file-description split the file header between them. Both find the header by the
tags it carries, so a module documented at its export below the imports counts. Only the block's first non-blank line
is read, to check it is prose and not a tag. A file with no header at all is reported by require-copyright alone.
comment-line-wrap is the counterpart of the SineMacula.Commenting.CommentLineLength sniff. It fills standalone
// and # runs and multi-line docblock prose greedily, reporting and autofixing both overflowing and prematurely
wrapped lines. It leaves alone: Markdown headings, docblock tag lines, tool directives (eslint, biome-ignore,
@ts-, Stryker, c8/v8/istanbul ignore, @vite-ignore, yamllint, yaml-language-server, renovate: and
the like), fenced code, indented code or command blocks, a doc tag whose value opens a multi-line bracketed type
(array{...}, <...>, \Closure(...)), tables, separators, a line whose overflow is a single unbreakable token,
trailing comments after code and compact single-line docblocks. A # comment fills one column further than a // one.
Like the PHP sniff, it starts a new paragraph at a // or # line opening with a capital letter, unless the line above
ends mid-sentence, so a title or one-line note is not merged into the sentence below.
Over YAML, comment-line-wrap is the only rule enabled, because yamllint's line-length cannot tell a comment from a
value and has no autofix. Only standalone comments are reached: a comment inside a block scalar such as run: | is
content, and a comment trailing a value is not standalone. YAML quoting, key order and indentation stay with yamllint.
The base layer also enables @typescript-eslint/no-explicit-any, curly (all), max-lines-per-function (50) and
max-depth (4), plus eslint-plugin-jsdoc rules requiring a documentation comment on every declared function,
method, class, interface member and class field, a description on every @param and @returns, and a blank line
above every documentation block. jsdoc/no-types runs over TypeScript files only, where the signature already holds
the type. The type-checked layer adds @typescript-eslint/await-thenable, consistent-type-imports, dot-notation
(with allowIndexSignaturePropertyAccess), explicit-module-boundary-types, no-floating-promises,
no-misused-promises and only-throw-error.
Test files (*.test.*, *.spec.*, and anything under __tests__/, tests/ or test-support/) are exempt from
max-lines-per-function and max-depth only. Their helpers, factories and builders still need documentation; a test
case passed as an arrow to it(...) does not.
Swift policy
SwiftLint keeps its default rule set and adds opt-in rules for correctness, concurrency, safety, performance and readability. Analyzer-only rules are left out, because they need an Xcode compiler log that Qlty's lint driver cannot supply.
Additions include checks for force-unwrapping, discarded throwing tasks, invalid concurrency annotations, unsafe optional modelling, empty XCTest methods, unbalanced access control, inefficient collection operations, oversized closures and non-private SwiftUI state. A discarded throwing task is an error, because it can lose a failure; most other findings are warnings.
| Metric | Warning | Error |
|---|---|---|
| Line length | 120 | 160 |
| File length | 500 | 800 |
| Type body length | 300 | 500 |
| Function body length | 50 | 80 |
| Closure body length | 50 | 80 |
| Cyclomatic complexity | 10 | 20 |
| Function parameters | 6 | 8 |
SwiftFormat owns whitespace, wrapping, imports and other mechanically correctable layout. It matches SwiftLint on
120-column wrapping, import ordering and no trailing commas, and alone enforces four-space indentation. Formatter rules
that can alter ownership, control flow, explicit Sendable conformance or public API shape are disabled.
The policy carries over the documentation rules of the PHP and TypeScript standards:
file_headerrequires a copyright header. It checks only that the tag is present, so the holder, year and format are the project's choice, and SwiftFormat's--header ignoreleaves an existing header alone.missing_docsrequires documentation onopenandpublicdeclarations.line_lengthapplies to comments. SwiftFormat wraps//comments at 120 but leaves///doc comments alone, so this is what bounds them.
Methods that only throw
A method that exists only to refuse, such as a __serialize() that throws so a value holding a secret cannot reach a
queue payload or cache, returns nothing on any path. Declare it never:
/** * @throws \LogicException * * @return never */ public function __serialize(): never { throw new LogicException('A token must not be serialised.'); }
never is a subtype of every return type, so it always satisfies an inherited signature, magic methods included. The
exception is a method a subclass is meant to return from, because a child cannot widen never. Keep the declared type
and throw anyway; no directive is needed:
/** * @throws \LogicException * * @return array<int, string> */ public function build(): array { throw new LogicException('Not implemented.'); }
Squiz.Commenting.FunctionComment.InvalidNoReturn is excluded because it looks for a return token and so faults the
guard above. PHPStan's return.missing reports a method that can reach its end without returning its documented type.
Spelling out the contained type of a documented traversable can introduce mixed, which the mixed-type ban reports.
In a function's docblock, suppress it with @phpcsSuppress SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint: a
// phpcs:ignore line cannot reach a type further down a multi-line docblock, and above the signature it detaches the
docblock. A property or constant's single-line docblock does not allow that tag, so put the // phpcs:ignore line
directly above the docblock.
Requirements
- PHP ^8.3 (Composer package)
- Node.js (npm package)
- macOS and Qlty CLI (SwiftLint and SwiftFormat policy)
Testing
composer test # PHPUnit suite for the custom sniffs and PHPStan rules composer test:coverage # suite with Clover coverage output composer test:mutation # Infection mutation gate on the diff (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 npm run test:js # Vitest suite for the ESLint rules npm run lint:js # ESLint over this package's own rules bash scripts/test-<tool>-policy.sh # exported policy integration tests (knip, shared, swift, terraform, trivy, vue, zizmor)
The Swift policy test needs macOS.
Changelog
See CHANGELOG.md.
Contributing
See CONTRIBUTING.md.
Security
See SECURITY.md for how to report a vulnerability.
License
Licensed under the Apache License, Version 2.0.