@joshuafolkken/kit 1.872.0

package/env/index.d.ts

@@ -0,0 +1,7 @@
+declare const environment_flags: {
+	normalize_flag_value: (value: string) => string
+	is_flag_enabled: (value: string | undefined) => boolean
+	is_ci_enabled: (value: string | undefined) => boolean
+}
+
+export { environment_flags }

package/env/index.js

@@ -0,0 +1,62 @@
+// Single definition of the env-flag vocabulary for every kit consumer.
+//
+// "Is this env var switched on?" looks too small to share, but the vocabulary is the interface: a
+// consumer config that re-declares it drifts immediately (#828 — a `vite.config.ts` clone accepted
+// only '1'/'true', so `ANALYZE=yes` silently did nothing in the same repository where
+// `PLAYWRIGHT_REUSE_SERVER=yes` worked). One exported predicate is what makes every config file
+// answer "what is a truthy flag?" the same way.
+//
+// This module is plain committed JavaScript rather than a `dist/`-built library like `./version`
+// for the same reason as `./ports`: `playwright.config.ts` imports it, and that config is loaded
+// by kit's own type check, unit suite and E2E run. A build artifact would make all three fail on a
+// fresh clone until `pnpm build` had run.
+const TRUTHY_FLAG_VALUES = new Set(['1', 'true', 'yes', 'on'])
+const FALSY_FLAG_VALUES = new Set(['0', 'false', 'no', 'off'])
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalize_flag_value(value) {
+	return value.trim().toLowerCase()
+}
+
+/**
+ * Whether an opt-in env flag is switched on.
+ *
+ * Env vars are always strings, so `Boolean(value)` would enable the flag for '0' and 'false' too —
+ * the two spellings someone reaches for to turn it off. Only affirmative spellings enable; every
+ * other value, including empty and unset, reads as off.
+ *
+ * @param {string | undefined} value
+ * @returns {boolean}
+ */
+function is_flag_enabled(value) {
+	return value !== undefined && TRUTHY_FLAG_VALUES.has(normalize_flag_value(value))
+}
+
+/**
+ * Whether the `CI` variable says this run is CI.
+ *
+ * `CI` is not an opt-in flag with a fixed vocabulary — Woodpecker exports `CI=woodpecker` — so the
+ * affirmative allow-list above would drop such runs into dev mode. Invert the test instead: any
+ * value counts as CI except an empty one and the explicit negatives. (`ci-info` opts out on the
+ * exact string 'false' alone; the negative set here also covers '0', 'no' and 'off'.)
+ *
+ * @param {string | undefined} value
+ * @returns {boolean}
+ */
+function is_ci_enabled(value) {
+	if (value === undefined) return false
+	const normalized = normalize_flag_value(value)
+
+	return normalized.length > 0 && !FALSY_FLAG_VALUES.has(normalized)
+}
+
+const environment_flags = {
+	normalize_flag_value,
+	is_flag_enabled,
+	is_ci_enabled,
+}
+
+export { environment_flags }

package/eslint/base.js

@@ -0,0 +1,233 @@
+import { fileURLToPath } from 'node:url'
+import { includeIgnoreFile } from '@eslint/compat'
+import js from '@eslint/js'
+import stylistic from '@stylistic/eslint-plugin'
+import prettier from 'eslint-config-prettier'
+import importPlugin from 'eslint-plugin-import-x'
+import promise from 'eslint-plugin-promise'
+import sonarjs from 'eslint-plugin-sonarjs'
+import unicorn from 'eslint-plugin-unicorn'
+import { defineConfig } from 'eslint/config'
+import globals from 'globals'
+import ts from 'typescript-eslint'
+import { checkout_rooted_parser } from './checkout-rooted-parser.js'
+import { config_fingerprint } from './config-fingerprint.js'
+import { code_quality_rules } from './rules/code-quality.js'
+import { formatting_rules } from './rules/formatting.js'
+import { import_rules } from './rules/import.js'
+import { namespace_object_export_rule } from './rules/namespace-object-export.js'
+import { naming_convention_rules } from './rules/naming-convention.js'
+import { promise_rules } from './rules/promise.js'
+import { sonarjs_rules } from './rules/sonarjs.js'
+import {
+	CENTRALIZED_TESTS_DIRECTORY_ENTRY,
+	CENTRALIZED_TESTS_DIRECTORY_PATTERNS,
+	extend_restricted_syntax,
+	SPEC_FILENAME_ENTRY,
+	SPEC_FILENAME_PATTERNS,
+} from './rules/test-filename.js'
+import { typescript_rules } from './rules/typescript.js'
+import { unicorn_rules } from './rules/unicorn.js'
+
+const SCRIPTS_AI_PATTERNS = ['scripts-ai/**/*.ts', 'scripts-ai/**/*.js']
+
+const FILE_PATTERNS = {
+	d_ts: ['**/*.d.ts'],
+	typescript: ['**/*.ts', '**/*.tsx'],
+	scripts_ai: SCRIPTS_AI_PATTERNS,
+	scripts: ['scripts/**/*.ts', 'scripts/**/*.js', ...SCRIPTS_AI_PATTERNS],
+	// joshuafolkken/kit#1414: `**/*.spec.ts` is deliberately absent. The same config bans that name
+	// outright, so handing it the test relaxation (`max-lines-per-function` 35 and the rest) is the
+	// config contradicting itself, and it is what makes `*.spec.ts` read as supported. A banned file
+	// is already a lint error, so what the removal costs a migrating consumer is one extra error on a
+	// file that was failing anyway.
+	tests: ['**/*.test.ts', '**/*.e2e.ts'],
+	eslint_rules: ['eslint/**/*.ts', 'eslint/rules/**/*.js'],
+}
+
+// One test-filename ban block. Both bans differ only in their glob and their message, so the shape
+// is written once — the `disableTypeChecked` carry and the rule composition both have to hold
+// identically for either, and a second copy is what lets them drift apart.
+//
+// `disableTypeChecked` is carried because a banned file is usually outside the tsconfig project:
+// `tsconfig.json`'s `include` is an allowlist of the directories a project keeps sources in, and a
+// top-level `tests/` is by definition not one of them. With the typed parser forced on, such a file
+// reports `Parsing error: ... was not found in any of the provided project(s)` and
+// `no-restricted-syntax` never runs at all — lint still fails, but on a tsconfig complaint instead
+// of the rename-or-move instruction this rule exists to give. Type-aware rules buy nothing on a file
+// whose only correct fix is to stop existing under that name.
+//
+// joshuafolkken/kit#1414 widened the bans to `.tsx` / `.mts` / `.cts` and the JS siblings, and no
+// parser has to be named for them: typescript-eslint's own base block installs its parser with no
+// `files` restriction, so every extension here is read by it and picks its script kind from the file
+// name. `eslint/base.test.ts` asserts each one reports the rule's message rather than a parse error,
+// so a future change that narrows that parser fails there instead of silently.
+//
+// joshuafolkken/kit#1414: `no-restricted-syntax` is composed on top of `code_quality_rules` rather
+// than set on its own, because flat config replaces a rule's options instead of merging them — set
+// alone, the ban would silently drop that module's four selectors on exactly the files it applies
+// to, which a consumer keeping a legitimate `tests/` would inherit as a hole.
+function create_test_filename_ban_block(files, ban_entry) {
+	return {
+		files,
+		...ts.configs.disableTypeChecked,
+		rules: {
+			...ts.configs.disableTypeChecked.rules,
+			...extend_restricted_syntax(code_quality_rules, ban_entry),
+		},
+	}
+}
+
+export function create_base_config({ gitignore_path, tsconfig_root_dir }) {
+	return defineConfig(
+		includeIgnoreFile(fileURLToPath(gitignore_path)),
+		{
+			// joshuafolkken/kit#1112: `.claude/worktrees/` is where Claude Code puts its bridge work
+			// trees — a full checkout of the project, carrying its own repository root. Linted, every
+			// one of its TypeScript files fails to parse: typescript-eslint finds two candidate
+			// `tsconfigRootDir`s, the project's and the work tree's, and refuses to choose. The work
+			// trees are created and removed on their own, so the same commit lints green or red
+			// depending on whether one happens to exist, which reads as an unstable linter rather
+			// than as a scope problem.
+			//
+			// It is listed here rather than left to `includeIgnoreFile` above, because git excludes
+			// these through `.git/info/exclude` — a per-checkout file that is never committed and
+			// that nothing outside git reads. The same gap published them to npm until
+			// joshuafolkken/kit#1107 narrowed `files`; this is that gap's other half, and the fix has
+			// to live in the shared config so every consumer inherits it.
+			// `**/` anchors nowhere: a monorepo puts a package's work trees at
+			// `packages/<name>/.claude/worktrees/`, and a root-anchored pattern lints every one of
+			// them. It is the spelling git's own exclude uses, for the same reason.
+			ignores: ['node_modules/**', '**/.claude/worktrees/**', '*.config.{ts,js,cjs,mjs}'],
+		},
+		// joshuafolkken/kit#1347: a content fingerprint of this directory's rule modules, carried in
+		// `settings` so that ESLint's own cache key changes when one of them is edited. Serializing the
+		// config drops every `create` function, so without this an edit to a rule left every cached
+		// entry valid and the gate reported the pre-edit verdict for every unchanged file. It sits in
+		// the shared config rather than beside either cache file because both the gate's cache and the
+		// edit hook's are invalidated by the same value — `config-fingerprint.js` carries the reasoning
+		// and what the fingerprint deliberately does not cover.
+		config_fingerprint.create_config_fingerprint_block(),
+		js.configs.recommended,
+		...ts.configs.strictTypeChecked,
+		...ts.configs.stylisticTypeChecked,
+		prettier,
+		unicorn.configs.recommended,
+		sonarjs.configs.recommended,
+		{ plugins: { promise }, rules: { ...promise.configs.recommended.rules } },
+		importPlugin.flatConfigs.recommended,
+		{
+			plugins: { import: importPlugin },
+			settings: {
+				'import/resolver': { typescript: { alwaysTryTypes: true }, node: true },
+				'import-x/ignore': ['node_modules'],
+			},
+		},
+		{
+			// joshuafolkken/kit#2180: `local` is kit's own rule plugin. `namespace-object-export` is the
+			// one §4.2 checklist item ESLint could not decide until now — a file that exports two or more
+			// functions individually instead of grouping them into one namespace object. It is wired here
+			// in the shared rules block so every consumer of `create_base_config` inherits it, the same
+			// way the test-filename bans are.
+			plugins: {
+				'@stylistic': stylistic,
+				local: { rules: { 'namespace-object-export': namespace_object_export_rule } },
+			},
+			languageOptions: { globals: { ...globals.browser, ...globals.node } },
+			rules: {
+				'no-undef': 'off',
+				'local/namespace-object-export': 'error',
+				...naming_convention_rules,
+				...typescript_rules,
+				...code_quality_rules,
+				...import_rules,
+				...unicorn_rules,
+				...sonarjs_rules,
+				...promise_rules,
+				...formatting_rules,
+			},
+		},
+		{ files: FILE_PATTERNS.d_ts, rules: { 'import/no-default-export': 'off' } },
+		{
+			files: FILE_PATTERNS.typescript,
+			ignores: ['**/*.svelte.ts'],
+			languageOptions: {
+				parser: checkout_rooted_parser.create(tsconfig_root_dir),
+				parserOptions: { project: './tsconfig.json' },
+			},
+		},
+		{
+			files: FILE_PATTERNS.scripts,
+			rules: {
+				'unicorn/no-process-exit': 'off',
+				// scripts under scripts/ and scripts-ai/ are dual-purpose: shebang-executable
+				// (run via tsx) AND importable namespace modules (consumed via #scripts/* and
+				// in tests). unicorn/no-exports-in-scripts flags exports in any shebang file,
+				// which conflicts with the kit export { module } convention, so disable it here.
+				'unicorn/no-exports-in-scripts': 'off',
+				'no-console': ['error', { allow: ['warn', 'error', 'info'] }],
+				// CLI tooling under scripts/ invokes pnpm/git/node via PATH by design
+				'sonarjs/no-os-command-from-path': 'off',
+				// kit's export { module } namespace pattern means functions never use this,
+				// so referencing them unbound (e.g. test spies) is safe
+				'@typescript-eslint/unbound-method': 'off',
+			},
+		},
+		{
+			files: FILE_PATTERNS.scripts_ai,
+			rules: {
+				'@typescript-eslint/no-restricted-imports': 'off',
+			},
+		},
+		{
+			files: FILE_PATTERNS.tests,
+			rules: {
+				'@typescript-eslint/no-magic-numbers': 'off',
+				'max-lines-per-function': ['error', { max: 35, skipBlankLines: true, skipComments: true }],
+				'no-console': ['error', { allow: ['warn', 'error', 'info'] }],
+				// vi mock/stub patterns require explicit undefined (mockResolvedValue/stubGlobal)
+				'unicorn/no-useless-undefined': 'off',
+				// describe-scoped `let` assigned in beforeEach is the standard vitest fixture shape;
+				// the declaration cannot be initialized where it is declared.
+				'init-declarations': 'off',
+				// `expect(x).toBe(0.05)` compares deterministic config constants, not computed
+				// floats; working around the rule only weakens the assertion.
+				'sonarjs/no-floating-point-equality': 'off',
+			},
+		},
+		{
+			files: FILE_PATTERNS.eslint_rules,
+			rules: {
+				'@typescript-eslint/naming-convention': 'off',
+				'@typescript-eslint/no-magic-numbers': 'off',
+			},
+		},
+		{
+			files: ['**/*.js'],
+			...ts.configs.disableTypeChecked,
+			rules: {
+				...ts.configs.disableTypeChecked.rules,
+				// These two rules check for the *presence* of a TS type annotation, so they
+				// are not part of disableTypeChecked. A hand-authored .js file cannot express
+				// the annotation (JSDoc does not satisfy them), making them unsatisfiable there.
+				'@typescript-eslint/explicit-function-return-type': 'off',
+				'@typescript-eslint/explicit-module-boundary-types': 'off',
+			},
+		},
+		// joshuafolkken/kit#1233: the test-filename bans are wired into the shared base config
+		// rather than left to each consumer's own `eslint.config.js`. Exported alone
+		// (`@joshuafolkken/kit/eslint/test-filename`), the rule reached only the projects that
+		// remembered to wire it — kit itself never did, so the `*.spec.ts` and top-level `tests/`
+		// bans the documents call lint-enforced were a reader's check in the very repository that
+		// distributes them. Every consumer of `create_base_config` now inherits both.
+		//
+		// These two blocks come last so nothing inside this config can override them; a project's
+		// own trailing blocks still can, which is how `eslint.config.js` keeps its existing
+		// per-directory relaxations.
+		create_test_filename_ban_block(SPEC_FILENAME_PATTERNS, SPEC_FILENAME_ENTRY),
+		create_test_filename_ban_block(
+			CENTRALIZED_TESTS_DIRECTORY_PATTERNS,
+			CENTRALIZED_TESTS_DIRECTORY_ENTRY,
+		),
+	)
+}

package/eslint/checkout-rooted-parser.js

@@ -0,0 +1,34 @@
+import ts from 'typescript-eslint'
+
+// joshuafolkken/kit#2435: ESLint keys every cache entry on the file's content hash **and** a hash of
+// the serialized config (`hashOfConfig`). typescript-eslint needs `tsconfigRootDir` as an absolute
+// path, and carried in `parserOptions` it put the checkout's location into that hash: a lane at
+// `.kit-lanes/<N>/` and the primary checkout hashed the same config differently, so every entry the
+// lane warm-up (joshuafolkken/kit#1849) or the per-tool sync (joshuafolkken/kit#2060) carried across
+// missed, and a lane's first gate re-linted every file.
+//
+// **The root directory travels inside the parser instead.** ESLint serializes a parser by its
+// `meta` name and version alone, so a parser that supplies `tsconfigRootDir` itself keeps the path
+// out of the hash while typescript-eslint still receives it. Leaving it out is sound: the checkout
+// root decides where the files are, not how they are linted.
+//
+// It is a parser rather than a `toJSON` on `parserOptions` because ESLint's config merge replaces,
+// instead of deep-merging, any `languageOptions` object that holds a function — a consumer block that
+// set one more parser option for `.ts` files would have dropped `project` and the root with it.
+// `parserOptions` stays plain data here, so it merges exactly as before, and a `tsconfigRootDir` a
+// consumer sets there explicitly still wins.
+//
+// Only the location leaves the hash. Every parser option stays in it, the parser's version stays in
+// it, and so does joshuafolkken/kit#1347's rule fingerprint, which lives in `settings`.
+
+const META = { name: 'kit/checkout-rooted-typescript-parser', version: ts.parser.meta?.version }
+
+function create(checkout_root) {
+	function parseForESLint(code, options) {
+		return ts.parser.parseForESLint(code, { tsconfigRootDir: checkout_root, ...options })
+	}
+
+	return { meta: META, parseForESLint }
+}
+
+export const checkout_rooted_parser = { create }

package/eslint/config-fingerprint.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// joshuafolkken/kit#1347: ESLint decides a cache entry is still valid from the file's own content
+// hash plus a hash of the **serialized** config, and serializing drops every function — so the
+// `create` of each rule under `rules/` is not in it. Edit `rules/naming-convention.js` and every
+// entry already in the cache stays valid: the gate's `josh lint` then reports the pre-edit verdict
+// for every file the change did not touch, and the edit hook's own cache does the same. Both were
+// there from the day `--cache` was added (joshuafolkken/kit#1256), and the gate side is the wider
+// exposure of the two.
+//
+// **This is the one place both sides are fixed from.** Every eslint run in a kit project — the
+// gate's whole-tree lint, `josh lint:related`, the `PostToolUse` edit hook, `josh health`, and a
+// consumer's own run — loads its config through `create_base_config`, so a value placed here reaches
+// each of their cache files at once. `settings` is where it goes because `settings` survives
+// serialization while a rule's `create` does not: measured against ESLint's own cache, two configs
+// differing only in this value produced `hashOfConfig` `a84wo9` and `1bi5fu4`, which invalidates
+// every entry in whichever file the run was pointed at.
+//
+// **Nothing reads the value.** Being inside the serialized config is the whole of its job, and no
+// rule or plugin is meant to look it up.
+//
+// **It is a content fingerprint rather than a version, an mtime or a random token** because it has
+// to agree across machines: CI restores the gate's cache (`.github/workflows/ci.yml` → "Setup ESLint
+// cache"), and a value that differed per checkout would make every CI lint cold while reporting a
+// cache hit. Content also means an edit that changes nothing but whitespace in a rule module does
+// invalidate — the safe direction, and the same direction `--cache-strategy content` already picked
+// for the files themselves.
+//
+// **Its scope is this directory, not the consumer's config entry file.** A consumer that writes an
+// inline rule implementation directly in its own `eslint.config.js` is outside the fingerprint: that
+// file's serializable content is already part of ESLint's hash, its `create` functions are not, and
+// this preset cannot locate a file it is not given. Rule implementations belong in a module the
+// preset composes, which is what every kit project does.
+
+const HASH_ALGORITHM = 'sha256'
+// Half of a sha256 is far more than a cache key needs, and it keeps the value readable when the
+// calculated config is dumped for debugging.
+const FINGERPRINT_LENGTH = 32
+// What serialization drops: the modules in this directory are loaded as code. The `.test.ts` files
+// beside them are not config inputs at all, so the extension list is what leaves them out — a test
+// edit must not throw away a warm cache.
+const CONFIG_SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs'])
+// Namespaced by the package rather than by a plugin, because no plugin owns it. A plugin key would
+// read as configuration something is meant to consume.
+const SETTINGS_KEY = 'kit_config_fingerprint'
+const PRESET_DIRECTORY = path.dirname(fileURLToPath(import.meta.url))
+
+// Code-unit order rather than `localeCompare`: the fingerprint has to be identical on every machine
+// that reads the same sources, and a locale-aware comparison is by definition not.
+function compare_source_names(left, right) {
+	if (left === right) return 0
+
+	return left < right ? -1 : 1
+}
+
+// Sorted, relative to the directory being read, and always with forward slashes. Each of the three is
+// what keeps the value the same on two machines: `readdirSync` guarantees no order, an absolute path
+// carries the checkout location into the hash, and `path.sep` would make a Windows checkout disagree
+// with the CI cache it restores.
+function list_config_sources(directory) {
+	return readdirSync(directory, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile() && CONFIG_SOURCE_EXTENSIONS.has(path.extname(entry.name)))
+		.map((entry) => path.relative(directory, path.join(entry.parentPath, entry.name)))
+		.map((relative_path) => relative_path.split(path.sep).join('/'))
+		.toSorted(compare_source_names)
+}
+
+// The relative path is hashed beside the content so that renaming a rule module, or moving one
+// between directories, changes the fingerprint too — a rename changes which files the config
+// applies and would otherwise be invisible here.
+//
+// The `NUL` between them is what keeps the concatenation unambiguous: fed straight into one digest,
+// a byte moved from the end of a name into the start of the next file's content would hash the same,
+// and a fingerprint that silently fails to change is the one failure this file exists to prevent.
+function compute_config_fingerprint(directory = PRESET_DIRECTORY) {
+	const digest = createHash(HASH_ALGORITHM)
+
+	for (const relative_path of list_config_sources(directory)) {
+		digest.update(`${relative_path}\0`)
+		digest.update(readFileSync(path.join(directory, relative_path)))
+		digest.update('\0')
+	}
+
+	return digest.digest('hex').slice(0, FINGERPRINT_LENGTH)
+}
+
+// A config block of its own, carrying no `files`, so it applies to every file the run lints. Given
+// `files`, the entries for everything outside that glob would keep the old config hash and the whole
+// point would be lost on exactly the files a rule edit is least likely to be tested against.
+function create_config_fingerprint_block(directory = PRESET_DIRECTORY) {
+	return { settings: { [SETTINGS_KEY]: compute_config_fingerprint(directory) } }
+}
+
+const config_fingerprint = {
+	SETTINGS_KEY,
+	compute_config_fingerprint,
+	create_config_fingerprint_block,
+}
+
+export { config_fingerprint }