README

Centralized coding standards, static analysis configurations, and code quality tooling for all Sine Macula repositories.

This package ships config files only - no runtime dependencies. Consuming projects install the tools themselves.

Installation

Composer (PHP-side: PHP CS Fixer, PHPStan, PHPCS)

composer require --dev sinemacula/coding-standards

npm (JS-side: Biome, Knip)

npm install --save-dev @sinemacula/coding-standards

The npm package ships only the static configs (js/, markdown/, yaml/, shell/, security/). The PHP autoloaded code lives in the Composer package.

Usage

Each consuming project creates 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',
]);

You can pass rule overrides as a second argument:

return PhpCsFixerConfig::make(
    [__DIR__ . '/src', __DIR__ . '/tests'],
    ['strict_comparison' => false],
);

PHPCS

The SineMacula coding standard is auto-discovered via 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 shared PHPStan configs are auto-included via the extra.phpstan.includes section in composer.json. Your project's phpstan.neon only needs project-specific settings:

parameters:
    level: 8
    paths:
        - src
        - tests

Laravel projects

For 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)

After installing the npm package, extend the shared Biome config from your project's biome.json (or .qlty/configs/biome.json when wired through Qlty):

{
    "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
    "root": true,
    "extends": ["@sinemacula/coding-standards/js/biome.json"],
    "files": {
        "ignoreUnknown": true,
        "includes": ["**", "!**/node_modules/**", "!**/vendor/**"]
    }
}

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)

ESLint runs alongside Biome, not in place of it. Biome keeps owning formatting and the fast syntactic lint; ESLint adds only the two things Biome structurally cannot express: this package's custom structural rules and the opt-in type-aware rules (the curated typescript-eslint set plus the type-driven custom rules). Add the linter, the typescript-eslint tooling, and this package to your dev dependencies:

npm install --save-dev eslint typescript typescript-eslint eslint-plugin-jsdoc @sinemacula/coding-standards

The package exposes two flat-config entry points:

• @sinemacula/coding-standards/js/eslint - the base layer of syntax-only custom rules; needs no tsconfig, so it stays cheap and runs anywhere Biome runs.
• @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.

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:

import sm from '@sinemacula/coding-standards/js/eslint';

export default [...sm];

Where a tsconfig exists, use the type-aware layer instead (it already carries the base rules):

import typeChecked from '@sinemacula/coding-standards/js/eslint/type-checked';

export default [...typeChecked];

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):

[plugins.definitions.eslint]
package_filters = ["@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc"]

Knip (JavaScript / TypeScript)

{
    "$schema": "https://unpkg.com/knip@6/schema.json",
    "extends": ["@sinemacula/coding-standards/js/knip.json"]
}

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>"

What's Included

Rules

These are the custom rules this package enforces on top of PSR-12. A deliberate exception can be bypassed with the native directive - // phpcs:ignore <code> for a sniff, @phpstan-ignore <identifier> for a rule, // eslint-disable-next-line <rule> for an ESLint rule.

PHPCS sniffs

PHPStan rules

ESLint rules

All rules run in the base layer except boolean-method-name, which resolves return types and so requires the opt-in 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.

The base layer also switches on a set of built-in rules: @typescript-eslint/no-explicit-any, 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 and class and forbid types in @param/@returns (types belong in the signature). The type-checked layer adds @typescript-eslint/explicit-module-boundary-types and @typescript-eslint/only-throw-error.

Requirements

• PHP ^8.3 (Composer package)
• Node.js (npm package)

Testing

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

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.