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.

Installation

npm install --save-dev @valkyrjaio/ci-eslint

Install it in the repository's .github/ci/eslint/ directory, next to eslint itself.

Usage

A repository states only what is true of itself, and Rules supplies the rest:

import path from 'path';
import { Rules } from '@valkyrjaio/ci-eslint';

export default Rules.getConfig({
    packageName: 'Valkyrja Framework',
    tsconfigRootDir: path.resolve(import.meta.dirname, '../../..'),
    project: ['./tsconfig.tests.json'],
});

getConfig returns the whole flat configuration: the ESLint and typescript-eslint presets, the shared rules, the copyright header rule, and the test-file rules.

A repository picks one of two ways to find its TypeScript project. Give project when one tsconfig spans both src and tests. Give projectService to let typescript-eslint find the project, which reads tsconfig.json only. Give exactly one; getConfig rejects neither and both.

Warning: with neither option typescript-eslint reads no type information, every type-aware rule goes quiet, and the run still reports success. That is why the guard stops rather than picking a default.

Add what only this repository needs through overrides, which append after the shared entries:

Rules.getConfig({
    packageName: 'Valkyrja Application',
    tsconfigRootDir: path.resolve(import.meta.dirname, '../../..'),
    projectService: true,
    overrides: [{ files: ['bin/**/*.ts'], rules: { 'no-console': 'off' } }],
});

COPYRIGHT_HEADER.md in the .github 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 | | :---------------------------------------- | :-------------------------------------------------- | | Rules.getConfig(options) | the whole flat configuration | | Rules.getRules() | the rules that apply to every linted file | | Rules.getTestRules() | the rules that apply to a test file only | | Rules.getParserOptions(options) | the parser options that find the project | | 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 CopyrightHeaderFactory 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.

// 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 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.

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 for the submission process and VOCABULARY.md for the terminology used across Valkyrja.

Security Issues

If you discover a security vulnerability, please follow our disclosure procedure.

License

This package is open-source software licensed under the MIT license. See LICENSE.md.