@valkyrjaio/ci-eslint 26.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-present Melech Mizrachi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+<p align="center"><a href="https://valkyrja.io" target="_blank">
+    <img src="https://raw.githubusercontent.com/valkyrjaio/art/refs/heads/master/long-banner/orange/typescript.png" width="100%">
+</a></p>
+
+# Valkyrja ESLint (TypeScript)
+
+Shared ESLint configuration for the Valkyrja TypeScript repositories.
+
+The package holds the copyright header that every Valkyrja TypeScript file
+carries, and the ESLint rule that enforces it. A repository supplies only its own
+package identifier. The header text lives here, in one place.
+
+<p>
+    <a href="https://www.npmjs.com/package/@valkyrjaio/ci-eslint"><img src="https://img.shields.io/npm/v/@valkyrjaio/ci-eslint.svg" alt="Latest Version on npm"></a>
+    <a href="https://www.npmjs.com/package/@valkyrjaio/ci-eslint"><img src="https://img.shields.io/node/v/@valkyrjaio/ci-eslint.svg" alt="Supported Node.js Version"></a>
+    <a href="https://github.com/valkyrjaio/ci-eslint-ts/blob/26.x/LICENSE.md"><img src="https://img.shields.io/github/license/valkyrjaio/ci-eslint-ts.svg" alt="License"></a>
+    <a href="https://github.com/valkyrjaio/ci-eslint-ts/actions/workflows/ci.yml?query=branch%3A26.x"><img src="https://github.com/valkyrjaio/ci-eslint-ts/actions/workflows/ci.yml/badge.svg?branch=26.x" alt="CI Status"></a>
+</p>
+
+## Installation
+
+```bash
+npm install --save-dev @valkyrjaio/ci-eslint
+```
+
+Install it in the repository's `.github/ci/eslint/` directory, next to `eslint`
+itself.
+
+## Usage
+
+Give `getRule` the repository's own package identifier, and register the rule
+that it returns:
+
+```js
+import { CopyrightHeaderFactory } from '@valkyrjaio/ci-eslint';
+
+export default tseslint.config(eslint.configs.recommended, {
+    plugins: {
+        local: { rules: { 'copyright-header': CopyrightHeaderFactory.getRule('Valkyrja Framework') } },
+    },
+    rules: {
+        'local/copyright-header': 'error',
+    },
+});
+```
+
+`COPYRIGHT_HEADER.md` in the [`.github`][copyright header url] repository maps
+every repository to its identifier. `valkyrja-ts` takes `Valkyrja Framework`,
+`sindri-ts` takes `Sindri`, `valkyrja-starter-app-ts` takes
+`Valkyrja Application`, and `project-template-ts` takes `Project Template`.
+
+## The API
+
+| Member                                    | Returns                                             |
+| :---------------------------------------- | :-------------------------------------------------- |
+| `CopyrightHeaderFactory.getRule(name)`    | the ESLint rule that requires the header            |
+| `CopyrightHeaderFactory.getHeader(name)`  | the full block comment, and the blank line below it |
+| `CopyrightHeaderFactory.getComment(name)` | the text between the two comment delimiters         |
+
+Each member takes the package identifier, and each one rejects a value that
+names no package.
+
+## Why the package name is guarded
+
+Warning: the rule is fixable. It rewrites the header of every file it reads, and
+it then reports each file as correct, because the file and the configuration now
+agree. A wrong package identifier therefore corrupts a repository behind a green
+gate.
+
+The PHP port shipped that defect. A function that took an assembled header was
+changed to take a package name, one caller was not updated, and the formatter
+wrote `This file is part of the ⟨whole five-line header⟩ package.` into every
+file. Every check passed.
+
+`getHeader` therefore rejects a name before it builds any text. It rejects a name
+that spans more than one line, a name that carries the header's opening sentence,
+and a name that holds no characters.
+
+```js
+// Wrong — the caller passes a built header, and the rule would rewrite every file.
+CopyrightHeaderFactory.getRule(existingHeaderText); // throws EslintInvalidPackageNameException
+
+// Right — the caller passes the identifier for this repository.
+CopyrightHeaderFactory.getRule('Valkyrja Framework');
+```
+
+## Versioning and Release Process
+
+This package follows [semantic versioning][semantic versioning url] with a major
+release every year, and support for each major version for 2 years from the date
+of release.
+
+For more information see our
+[Versioning and Release Process documentation][Versioning and Release Process url].
+
+### Supported Versions
+
+Bug fixes are provided until 3 months after the next major release. Security
+fixes are provided for 2 years after the initial release.
+
+| Version | Node | Release        | Bug Fixes Until | Security Fixes Until |
+| :------ | :--- | :------------- | :-------------- | :------------------- |
+| 26      | 22+  | March 31, 2026 | Q2 2027         | Q1 2028              |
+
+## Contributing
+
+See [`CONTRIBUTING.md`][contributing url] for the submission process and
+[`VOCABULARY.md`][vocabulary url] for the terminology used across Valkyrja.
+
+## Security Issues
+
+If you discover a security vulnerability, please follow our
+[disclosure procedure][security vulnerabilities url].
+
+## License
+
+This package is open-source software licensed under the
+[MIT license][MIT license url]. See [`LICENSE.md`](./LICENSE.md).
+
+[Valkyrja url]: https://valkyrja.io
+[copyright header url]: https://github.com/valkyrjaio/.github/blob/master/COPYRIGHT_HEADER.md
+[vocabulary url]: https://github.com/valkyrjaio/.github/blob/master/VOCABULARY.md
+[contributing url]: https://github.com/valkyrjaio/.github/blob/master/CONTRIBUTING.md
+[security vulnerabilities url]: https://github.com/valkyrjaio/.github/blob/master/SECURITY.md
+[Versioning and Release Process url]: https://github.com/valkyrjaio/architecture/blob/master/VERSIONING.md
+[semantic versioning url]: https://semver.org/
+[MIT license url]: https://opensource.org/licenses/MIT

package/dist/Eslint/Constant/EslintInfo.d.ts

@@ -0,0 +1,5 @@
+export declare class EslintInfo {
+    static readonly VERSION: "26.0.0";
+    static readonly VERSION_BUILD_DATE_TIME: "August 2 2026 20:32:26 MST";
+}
+//# sourceMappingURL=EslintInfo.d.ts.map

package/dist/Eslint/Constant/EslintInfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EslintInfo.d.ts","sourceRoot":"","sources":["../../../src/Eslint/Constant/EslintInfo.ts"],"names":[],"mappings":"AAQA,qBAAa,UAAU;IACnB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAG,QAAQ,CAAU;IAC5C,MAAM,CAAC,QAAQ,CAAC,uBAAuB,EAAG,4BAA4B,CAAU;CACnF"}

package/dist/Eslint/Constant/EslintInfo.js

@@ -0,0 +1,12 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+export class EslintInfo {
+    static VERSION = '26.0.0';
+    static VERSION_BUILD_DATE_TIME = 'August 2 2026 20:32:26 MST';
+}
+//# sourceMappingURL=EslintInfo.js.map

package/dist/Eslint/Constant/EslintInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EslintInfo.js","sourceRoot":"","sources":["../../../src/Eslint/Constant/EslintInfo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,UAAU;IACnB,MAAM,CAAU,OAAO,GAAG,QAAiB,CAAC;IAC5C,MAAM,CAAU,uBAAuB,GAAG,4BAAqC,CAAC"}

package/dist/Eslint/Factory/CopyrightHeaderFactory.d.ts

@@ -0,0 +1,35 @@
+import type { Rule } from 'eslint';
+/**
+ * Builds the copyright header, and the ESLint rule that enforces it.
+ *
+ * Every Valkyrja TypeScript repository takes its header from this factory and supplies only its
+ * own package identifier, so the text lives in one place.
+ */
+export declare class CopyrightHeaderFactory {
+    /**
+     * Gets the text that sits between the two block comment delimiters.
+     *
+     * The rule compares the first comment of a file against this, so a file whose header body is
+     * wrong fails too, and not only a file that carries no header at all.
+     */
+    static getComment(packageName: string): string;
+    /**
+     * Gets the full header block, and the empty line that separates it from the code below it.
+     */
+    static getHeader(packageName: string): string;
+    /**
+     * Gets the ESLint rule that requires the header at the top of each linted file.
+     */
+    static getRule(packageName: string): Rule.RuleModule;
+    /**
+     * Rejects a value that names no package.
+     *
+     * Warning: the rule rewrites the header of every file it reads, and it then reports the file
+     * as correct, because the file and the configuration agree. A wrong package name therefore
+     * corrupts a repository behind a green gate, so this guard runs before any text is built.
+     * The same defect landed in the PHP port, where a caller passed the assembled header to an
+     * argument that had become the package name.
+     */
+    private static validatePackageName;
+}
+//# sourceMappingURL=CopyrightHeaderFactory.d.ts.map

package/dist/Eslint/Factory/CopyrightHeaderFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CopyrightHeaderFactory.d.ts","sourceRoot":"","sources":["../../../src/Eslint/Factory/CopyrightHeaderFactory.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AA2BnC;;;;;GAKG;AACH,qBAAa,sBAAsB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAU9C;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAI7C;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC,UAAU;IAiDpD;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAkBrC"}

package/dist/Eslint/Factory/CopyrightHeaderFactory.js

@@ -0,0 +1,122 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+import { EslintInvalidPackageNameException } from "../Throwable/Exception/EslintInvalidPackageNameException.js";
+/**
+ * The header body, one entry per line, with `{package}` where the package identifier goes.
+ *
+ * COPYRIGHT_HEADER.md in the `.github` repository holds the same text, and it maps every
+ * repository to its own identifier. An empty entry renders as a bare ` *` line.
+ */
+const LINES = [
+    'This file is part of the {package} package.',
+    '',
+    'Copyright (c) 2016-present Melech Mizrachi',
+    '',
+    'Released under the MIT License. See LICENSE.md for details.',
+];
+/**
+ * The sentence that opens the header.
+ *
+ * A caller that passes a whole assembled header where a package identifier belongs builds
+ * `This file is part of the ⟨whole header⟩ package.`, so the factory rejects a name that
+ * carries this sentence. See `validatePackageName`.
+ */
+const OPENING_SENTENCE = 'This file is part of the';
+/**
+ * Builds the copyright header, and the ESLint rule that enforces it.
+ *
+ * Every Valkyrja TypeScript repository takes its header from this factory and supplies only its
+ * own package identifier, so the text lives in one place.
+ */
+export class CopyrightHeaderFactory {
+    /**
+     * Gets the text that sits between the two block comment delimiters.
+     *
+     * The rule compares the first comment of a file against this, so a file whose header body is
+     * wrong fails too, and not only a file that carries no header at all.
+     */
+    static getComment(packageName) {
+        CopyrightHeaderFactory.validatePackageName(packageName);
+        const body = LINES.map((line) => (line === '' ? ' *' : ` * ${line.replace('{package}', packageName)}`)).join('\n');
+        return `\n${body}\n `;
+    }
+    /**
+     * Gets the full header block, and the empty line that separates it from the code below it.
+     */
+    static getHeader(packageName) {
+        return `/*${CopyrightHeaderFactory.getComment(packageName)}*/\n\n`;
+    }
+    /**
+     * Gets the ESLint rule that requires the header at the top of each linted file.
+     */
+    static getRule(packageName) {
+        const header = CopyrightHeaderFactory.getHeader(packageName);
+        const comment = CopyrightHeaderFactory.getComment(packageName);
+        return {
+            meta: {
+                type: 'layout',
+                fixable: 'code',
+                schema: [],
+                messages: {
+                    missing: 'Missing copyright header. Add the standard block comment at the top of the file.',
+                    incorrect: 'Incorrect copyright header. The block comment must match the standard header exactly.',
+                },
+            },
+            create(context) {
+                return {
+                    Program(node) {
+                        // `getAllComments` returns the comments in source order, so the first block
+                        // comment is the one that a header occupies.
+                        const first = context.sourceCode.getAllComments().find((c) => c.type === 'Block');
+                        const loc = first?.loc;
+                        if (first === undefined || loc == null || loc.start.line !== 1) {
+                            context.report({
+                                node,
+                                messageId: 'missing',
+                                fix: (fixer) => fixer.insertTextBefore(node, header),
+                            });
+                            return;
+                        }
+                        if (first.value === comment) {
+                            return;
+                        }
+                        // The file carries a header whose text differs. Replace that comment. An
+                        // insert would put a second header above the first one.
+                        context.report({
+                            loc,
+                            messageId: 'incorrect',
+                            fix: (fixer) => fixer.replaceText(first, header.trimEnd()),
+                        });
+                    },
+                };
+            },
+        };
+    }
+    /**
+     * Rejects a value that names no package.
+     *
+     * Warning: the rule rewrites the header of every file it reads, and it then reports the file
+     * as correct, because the file and the configuration agree. A wrong package name therefore
+     * corrupts a repository behind a green gate, so this guard runs before any text is built.
+     * The same defect landed in the PHP port, where a caller passed the assembled header to an
+     * argument that had become the package name.
+     */
+    static validatePackageName(packageName) {
+        if (packageName.includes('\n') || packageName.includes('\r')) {
+            throw new EslintInvalidPackageNameException(`A package name is one line. Got ${JSON.stringify(packageName)}.`);
+        }
+        if (packageName.includes(OPENING_SENTENCE)) {
+            throw new EslintInvalidPackageNameException(`A package name is an identifier such as 'Valkyrja Framework', not a built header. ` +
+                `Got ${JSON.stringify(packageName)}.`);
+        }
+        if (packageName.trim() === '') {
+            throw new EslintInvalidPackageNameException('A package name holds at least one character.');
+        }
+    }
+}
+//# sourceMappingURL=CopyrightHeaderFactory.js.map

package/dist/Eslint/Factory/CopyrightHeaderFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CopyrightHeaderFactory.js","sourceRoot":"","sources":["../../../src/Eslint/Factory/CopyrightHeaderFactory.ts"],"names":[],"mappings":"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"}

package/dist/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The base for every exception this package throws for a bad argument.
+ *
+ * The chain roots in the native `Error` rather than in `ValkyrjaInvalidArgumentException`. An
+ * ESLint configuration is plain JavaScript that Node loads directly, so this package cannot
+ * depend on `@valkyrjaio/valkyrja`, which ships TypeScript source that Node does not compile.
+ */
+export declare abstract class EslintInvalidArgumentException extends Error {
+}
+//# sourceMappingURL=EslintInvalidArgumentException.d.ts.map

package/dist/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EslintInvalidArgumentException.d.ts","sourceRoot":"","sources":["../../../../../src/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,8BAAsB,8BAA+B,SAAQ,KAAK;CAAG"}

package/dist/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.js

@@ -0,0 +1,17 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+/**
+ * The base for every exception this package throws for a bad argument.
+ *
+ * The chain roots in the native `Error` rather than in `ValkyrjaInvalidArgumentException`. An
+ * ESLint configuration is plain JavaScript that Node loads directly, so this package cannot
+ * depend on `@valkyrjaio/valkyrja`, which ships TypeScript source that Node does not compile.
+ */
+export class EslintInvalidArgumentException extends Error {
+}
+//# sourceMappingURL=EslintInvalidArgumentException.js.map

package/dist/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EslintInvalidArgumentException.js","sourceRoot":"","sources":["../../../../../src/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,OAAgB,8BAA+B,SAAQ,KAAK;CAAG"}

package/dist/Eslint/Throwable/Exception/EslintInvalidPackageNameException.d.ts

@@ -0,0 +1,8 @@
+import { EslintInvalidArgumentException } from './Abstract/EslintInvalidArgumentException.ts';
+/**
+ * The package name that a caller gave does not name a package.
+ */
+export declare class EslintInvalidPackageNameException extends EslintInvalidArgumentException {
+    constructor(message: string);
+}
+//# sourceMappingURL=EslintInvalidPackageNameException.d.ts.map

package/dist/Eslint/Throwable/Exception/EslintInvalidPackageNameException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EslintInvalidPackageNameException.d.ts","sourceRoot":"","sources":["../../../../src/Eslint/Throwable/Exception/EslintInvalidPackageNameException.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AAE9F;;GAEG;AACH,qBAAa,iCAAkC,SAAQ,8BAA8B;gBACrE,OAAO,EAAE,MAAM;CAK9B"}

package/dist/Eslint/Throwable/Exception/EslintInvalidPackageNameException.js

@@ -0,0 +1,18 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+import { EslintInvalidArgumentException } from "./Abstract/EslintInvalidArgumentException.js";
+/**
+ * The package name that a caller gave does not name a package.
+ */
+export class EslintInvalidPackageNameException extends EslintInvalidArgumentException {
+    constructor(message) {
+        super(message);
+        this.name = 'EslintInvalidPackageNameException';
+    }
+}
+//# sourceMappingURL=EslintInvalidPackageNameException.js.map

package/dist/Eslint/Throwable/Exception/EslintInvalidPackageNameException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EslintInvalidPackageNameException.js","sourceRoot":"","sources":["../../../../src/Eslint/Throwable/Exception/EslintInvalidPackageNameException.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AAE9F;;GAEG;AACH,MAAM,OAAO,iCAAkC,SAAQ,8BAA8B;IACjF,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,mCAAmC,CAAC;IACpD,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { EslintInfo } from './Eslint/Constant/EslintInfo.ts';
+export { CopyrightHeaderFactory } from './Eslint/Factory/CopyrightHeaderFactory.ts';
+export { EslintInvalidArgumentException } from './Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.ts';
+export { EslintInvalidPackageNameException } from './Eslint/Throwable/Exception/EslintInvalidPackageNameException.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,EAAE,8BAA8B,EAAE,MAAM,yEAAyE,CAAC;AACzH,OAAO,EAAE,iCAAiC,EAAE,MAAM,mEAAmE,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+export { EslintInfo } from "./Eslint/Constant/EslintInfo.js";
+export { CopyrightHeaderFactory } from "./Eslint/Factory/CopyrightHeaderFactory.js";
+export { EslintInvalidArgumentException } from "./Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.js";
+export { EslintInvalidPackageNameException } from "./Eslint/Throwable/Exception/EslintInvalidPackageNameException.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,EAAE,8BAA8B,EAAE,MAAM,yEAAyE,CAAC;AACzH,OAAO,EAAE,iCAAiC,EAAE,MAAM,mEAAmE,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@valkyrjaio/ci-eslint",
+    "version": "26.0.0",
+    "description": "Shared ESLint configuration for Valkyrja TypeScript repositories",
+    "homepage": "https://www.valkyrja.io",
+    "keywords": [
+        "ci",
+        "eslint",
+        "valkyrja"
+    ],
+    "license": "MIT",
+    "author": {
+        "name": "Melech Mizrachi",
+        "email": "melechmizrachi@gmail.com"
+    },
+    "type": "module",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "engines": {
+        "node": ">=22"
+    },
+    "scripts": {
+        "build": "cd .github/ci/typescript && npm run build",
+        "prepublishOnly": "npm run build",
+        "typescript": "cd .github/ci/typescript && npm run check",
+        "typescript-outdated-check": "cd .github/ci/typescript && npm install && npm outdated",
+        "typescript-outdated-check-major-release": "cd .github/ci/typescript && npm install && npm outdated",
+        "typescript-npm-update": "cd .github/ci/typescript && npm update",
+        "eslint": "cd .github/ci/eslint && npm run check",
+        "eslint-outdated-check": "cd .github/ci/eslint && npm install && npm outdated",
+        "eslint-outdated-check-major-release": "cd .github/ci/eslint && npm install && npm outdated",
+        "eslint-npm-update": "cd .github/ci/eslint && npm update",
+        "prettier": "cd .github/ci/prettier && npm run fix",
+        "prettier-check": "cd .github/ci/prettier && npm run check",
+        "prettier-outdated-check": "cd .github/ci/prettier && npm install && npm outdated",
+        "prettier-outdated-check-major-release": "cd .github/ci/prettier && npm install && npm outdated",
+        "prettier-npm-update": "cd .github/ci/prettier && npm update",
+        "vitest": "cd .github/ci/vitest && npm run check",
+        "vitest-coverage": "cd .github/ci/vitest && npm run coverage",
+        "vitest-outdated-check": "cd .github/ci/vitest && npm install && npm outdated",
+        "vitest-outdated-check-major-release": "cd .github/ci/vitest && npm install && npm outdated",
+        "vitest-npm-update": "cd .github/ci/vitest && npm update",
+        "root-outdated-check": "npm install && npm outdated",
+        "root-outdated-check-major-release": "npm install && npm outdated",
+        "root-and-suggested-outdated-check": "cd .github/ci/root-and-suggested && npm install && npm outdated",
+        "root-and-suggested-outdated-check-major-release": "cd .github/ci/root-and-suggested && npm install && npm outdated",
+        "root-and-suggested-npm-update": "cd .github/ci/root-and-suggested && npm update"
+    },
+    "peerDependencies": {
+        "eslint": ">=9"
+    }
+}

package/src/Eslint/Constant/EslintInfo.ts

@@ -0,0 +1,12 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+export class EslintInfo {
+    static readonly VERSION = '26.0.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'August 2 2026 20:32:26 MST' as const;
+}

package/src/Eslint/Factory/CopyrightHeaderFactory.ts

@@ -0,0 +1,145 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import type { Rule } from 'eslint';
+
+import { EslintInvalidPackageNameException } from '../Throwable/Exception/EslintInvalidPackageNameException.ts';
+
+/**
+ * The header body, one entry per line, with `{package}` where the package identifier goes.
+ *
+ * COPYRIGHT_HEADER.md in the `.github` repository holds the same text, and it maps every
+ * repository to its own identifier. An empty entry renders as a bare ` *` line.
+ */
+const LINES = [
+    'This file is part of the {package} package.',
+    '',
+    'Copyright (c) 2016-present Melech Mizrachi',
+    '',
+    'Released under the MIT License. See LICENSE.md for details.',
+] as const;
+
+/**
+ * The sentence that opens the header.
+ *
+ * A caller that passes a whole assembled header where a package identifier belongs builds
+ * `This file is part of the ⟨whole header⟩ package.`, so the factory rejects a name that
+ * carries this sentence. See `validatePackageName`.
+ */
+const OPENING_SENTENCE = 'This file is part of the';
+
+/**
+ * Builds the copyright header, and the ESLint rule that enforces it.
+ *
+ * Every Valkyrja TypeScript repository takes its header from this factory and supplies only its
+ * own package identifier, so the text lives in one place.
+ */
+export class CopyrightHeaderFactory {
+    /**
+     * Gets the text that sits between the two block comment delimiters.
+     *
+     * The rule compares the first comment of a file against this, so a file whose header body is
+     * wrong fails too, and not only a file that carries no header at all.
+     */
+    static getComment(packageName: string): string {
+        CopyrightHeaderFactory.validatePackageName(packageName);
+
+        const body = LINES.map((line) => (line === '' ? ' *' : ` * ${line.replace('{package}', packageName)}`)).join(
+            '\n',
+        );
+
+        return `\n${body}\n `;
+    }
+
+    /**
+     * Gets the full header block, and the empty line that separates it from the code below it.
+     */
+    static getHeader(packageName: string): string {
+        return `/*${CopyrightHeaderFactory.getComment(packageName)}*/\n\n`;
+    }
+
+    /**
+     * Gets the ESLint rule that requires the header at the top of each linted file.
+     */
+    static getRule(packageName: string): Rule.RuleModule {
+        const header = CopyrightHeaderFactory.getHeader(packageName);
+        const comment = CopyrightHeaderFactory.getComment(packageName);
+
+        return {
+            meta: {
+                type: 'layout',
+                fixable: 'code',
+                schema: [],
+                messages: {
+                    missing: 'Missing copyright header. Add the standard block comment at the top of the file.',
+                    incorrect: 'Incorrect copyright header. The block comment must match the standard header exactly.',
+                },
+            },
+            create(context: Rule.RuleContext): Rule.RuleListener {
+                return {
+                    Program(node): void {
+                        // `getAllComments` returns the comments in source order, so the first block
+                        // comment is the one that a header occupies.
+                        const first = context.sourceCode.getAllComments().find((c) => c.type === 'Block');
+                        const loc = first?.loc;
+
+                        if (first === undefined || loc == null || loc.start.line !== 1) {
+                            context.report({
+                                node,
+                                messageId: 'missing',
+                                fix: (fixer) => fixer.insertTextBefore(node, header),
+                            });
+
+                            return;
+                        }
+
+                        if (first.value === comment) {
+                            return;
+                        }
+
+                        // The file carries a header whose text differs. Replace that comment. An
+                        // insert would put a second header above the first one.
+                        context.report({
+                            loc,
+                            messageId: 'incorrect',
+                            fix: (fixer) => fixer.replaceText(first, header.trimEnd()),
+                        });
+                    },
+                };
+            },
+        };
+    }
+
+    /**
+     * Rejects a value that names no package.
+     *
+     * Warning: the rule rewrites the header of every file it reads, and it then reports the file
+     * as correct, because the file and the configuration agree. A wrong package name therefore
+     * corrupts a repository behind a green gate, so this guard runs before any text is built.
+     * The same defect landed in the PHP port, where a caller passed the assembled header to an
+     * argument that had become the package name.
+     */
+    private static validatePackageName(packageName: string): void {
+        if (packageName.includes('\n') || packageName.includes('\r')) {
+            throw new EslintInvalidPackageNameException(
+                `A package name is one line. Got ${JSON.stringify(packageName)}.`,
+            );
+        }
+
+        if (packageName.includes(OPENING_SENTENCE)) {
+            throw new EslintInvalidPackageNameException(
+                `A package name is an identifier such as 'Valkyrja Framework', not a built header. ` +
+                    `Got ${JSON.stringify(packageName)}.`,
+            );
+        }
+
+        if (packageName.trim() === '') {
+            throw new EslintInvalidPackageNameException('A package name holds at least one character.');
+        }
+    }
+}

package/src/Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+/**
+ * The base for every exception this package throws for a bad argument.
+ *
+ * The chain roots in the native `Error` rather than in `ValkyrjaInvalidArgumentException`. An
+ * ESLint configuration is plain JavaScript that Node loads directly, so this package cannot
+ * depend on `@valkyrjaio/valkyrja`, which ships TypeScript source that Node does not compile.
+ */
+export abstract class EslintInvalidArgumentException extends Error {}

package/src/Eslint/Throwable/Exception/EslintInvalidPackageNameException.ts

@@ -0,0 +1,20 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { EslintInvalidArgumentException } from './Abstract/EslintInvalidArgumentException.ts';
+
+/**
+ * The package name that a caller gave does not name a package.
+ */
+export class EslintInvalidPackageNameException extends EslintInvalidArgumentException {
+    constructor(message: string) {
+        super(message);
+
+        this.name = 'EslintInvalidPackageNameException';
+    }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/*
+ * This file is part of the Valkyrja ESLint package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+export { EslintInfo } from './Eslint/Constant/EslintInfo.ts';
+export { CopyrightHeaderFactory } from './Eslint/Factory/CopyrightHeaderFactory.ts';
+export { EslintInvalidArgumentException } from './Eslint/Throwable/Exception/Abstract/EslintInvalidArgumentException.ts';
+export { EslintInvalidPackageNameException } from './Eslint/Throwable/Exception/EslintInvalidPackageNameException.ts';