eslint-plugin-typefest 1.0.1

package/docs/rules/getting-started.md

@@ -0,0 +1,74 @@
+---
+title: Getting Started
+description: Enable eslint-plugin-typefest quickly in Flat Config.
+---
+
+# Getting Started
+
+Install the plugin:
+
+```bash
+npm install --save-dev eslint-plugin-typefest typescript
+```
+
+Enable one preset in your Flat Config:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    typefest.configs.recommended,
+];
+```
+
+`recommended` does not require type information.
+
+If you want the same baseline plus type-aware helper rules, use
+`typefest.configs["recommended-type-checked"]`.
+
+## Alternative: manual scoped setup
+
+If you prefer to apply plugin rules inside your own file-scoped config object, spread the preset rules manually.
+
+```ts
+import tsParser from "@typescript-eslint/parser";
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        files: ["**/*.{ts,tsx,mts,cts}"],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                ecmaVersion: "latest",
+                // Enable only when using a type-aware preset.
+                // projectService: true,
+                sourceType: "module",
+            },
+        },
+        plugins: {
+            typefest,
+        },
+        rules: {
+            ...typefest.configs.recommended.rules,
+        },
+    },
+];
+```
+
+Use this pattern when you only extend rules and want full control over parser setup per scope.
+
+## Recommended rollout
+
+1. Start with `recommended` (or `minimal` if you want low initial noise).
+2. Fix violations in small batches.
+3. Move to `recommended-type-checked` when you are ready for typed rules.
+4. Move to `strict` once your baseline is stable.
+5. Use `all` only when you explicitly want every rule, including experimental rules.
+
+## Need a subset instead of a full preset?
+
+- 💠 `typefest.configs["type-fest/types"]`
+- ✴️ `typefest.configs["ts-extras/type-guards"]`
+
+See the **Presets** section in this sidebar for details and examples.

package/docs/rules/guides/adoption-checklist.md

@@ -0,0 +1,37 @@
+---
+title: Rule adoption checklist
+description: Practical checklist for adopting eslint-plugin-typefest rules with low risk.
+---
+
+# Rule adoption checklist
+
+Use this checklist when rolling out one or more rules across an existing codebase.
+
+## Before enabling rules
+
+1. Identify the target package/folder scope.
+2. Run ESLint in report-only mode to estimate violation count.
+3. Confirm your CI, tests, and typecheck are green before refactoring.
+4. Decide whether this rollout is autofix-first or manual-first.
+
+## During migration
+
+1. Apply changes in small batches (per folder/package).
+2. Keep each PR focused on one rule family when possible.
+3. Re-run tests and typecheck after each batch.
+4. Flag behavior-sensitive replacements for reviewer attention.
+
+## After migration
+
+1. Switch rule severity from `warn` to `error`.
+2. Remove local disables added during migration.
+3. Add one representative example to internal team docs.
+4. Track regressions by keeping the rule enabled in CI.
+
+## Suggested PR checklist
+
+- [ ] Only target files for this migration are changed.
+- [ ] Tests pass after each replacement batch.
+- [ ] Typecheck passes after each replacement batch.
+- [ ] Reviewer notes include runtime-sensitive replacements.
+- [ ] Final lint run has no new violations for the migrated rule(s).

package/docs/rules/guides/preset-selection-strategy.md

@@ -0,0 +1,87 @@
+---
+title: Preset selection strategy
+description: Choose the right eslint-plugin-typefest preset and roll it out with minimal migration risk.
+---
+
+# Preset selection strategy
+
+This guide helps teams pick a preset based on migration tolerance, type-checking maturity, and rollout velocity.
+
+## Decision checkpoints
+
+Use these checkpoints before choosing a preset:
+
+1. **Type information availability**: Do you run ESLint with project-aware type services in CI/local workflows?
+2. **Migration bandwidth**: Can the team handle broad replacement churn this quarter?
+3. **Runtime sensitivity**: Do you need to review behavior-sensitive changes manually before broad adoption?
+4. **Convergence target**: Do you intend to land on `strict`/`all`, or stay at a stable baseline?
+
+## Recommended starting points
+
+### `minimal`
+
+Choose this when:
+
+- You need the lowest-friction baseline.
+- You want immediate value with minimal code churn.
+
+### `recommended`
+
+Choose this when:
+
+- You want broader coverage but still pragmatic defaults.
+- You can absorb moderate migration effort.
+
+### `recommended-type-checked`
+
+Choose this when:
+
+- Type services are already stable in your lint pipeline.
+- You want stronger guidance on typed guard/helper patterns.
+
+### `strict`
+
+Choose this when:
+
+- Your codebase already enforces high lint/type discipline.
+- You prefer stronger consistency constraints over minimal churn.
+
+### `all`
+
+Choose this when:
+
+- You want full plugin coverage and can manage incremental cleanup.
+- You actively maintain migration and suppression hygiene.
+
+### Domain overlays
+
+Layer these when they match your codebase goals:
+
+- `type-fest/types`
+- `ts-extras/type-guards`
+
+## Rollout playbook
+
+1. Start with `warn` for one target folder/package.
+2. Record baseline violations and identify high-churn rule families.
+3. Run autofix in scoped batches, then run full tests/typecheck.
+4. Promote to `error` after each batch reaches zero violations.
+5. Repeat until all target folders are converged.
+
+## Validation gates
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm run test`
+
+For monorepos, run package-level gates first, then full-repo gates.
+
+## Escalation policy
+
+If a rule creates migration risk or noisy output:
+
+1. Keep the preset enabled.
+2. Temporarily lower that single rule to `warn` or `off` with a tracking note.
+3. Re-enable after targeted remediation.
+
+This preserves preset consistency while avoiding long-lived blind spots.

package/docs/rules/guides/rollout-and-fix-safety.md

@@ -0,0 +1,42 @@
+---
+title: Rollout and fix safety
+description: Guidance for phased rollout, fix safety, and manual verification.
+---
+
+# Rollout and fix safety
+
+This page centralizes rollout guidance used across rule migrations.
+
+## Phased rollout model
+
+1. Start with `warn` severity to measure blast radius.
+2. Run `--fix` only on a scoped folder first.
+3. Review runtime-sensitive call sites manually.
+4. Promote to `error` after baseline cleanup.
+
+## Fix safety expectations
+
+- **Autofix-safe patterns:** simple API shape substitutions where runtime behavior is equivalent.
+- **Suggestion-only patterns:** potentially behavior-sensitive changes requiring explicit reviewer choice.
+- **Manual migrations:** replacements that depend on local typing, nullability, or control flow assumptions.
+
+## Manual verification checklist
+
+1. Verify import changes are deduplicated and stable.
+2. Confirm narrowed types still match downstream usage.
+3. Validate guard/predicate behavior with tests.
+4. Confirm no accidental semantic changes in edge cases.
+
+## FAQ
+
+### Why not migrate everything in one pass?
+
+Large one-shot migrations make regressions harder to detect and review. Smaller batches isolate risk.
+
+### Should we always use `--fix` in CI?
+
+No. Prefer running `--fix` locally and committing explicit changes. CI should validate, not rewrite, code.
+
+### How do we handle wrapper utilities?
+
+Either align wrappers to canonical helpers/types used by this plugin or deprecate wrappers that duplicate behavior.

package/docs/rules/guides/snapshot-testing.md

@@ -0,0 +1,121 @@
+---
+title: Snapshot testing guidance
+description: How to use Vitest snapshots safely and effectively in eslint-plugin-typefest.
+---
+
+# Snapshot testing guidance
+
+This guide explains where snapshot tests add value in this repository, where
+they do not, and how to keep snapshots stable and reviewable.
+
+## Why we use snapshots selectively
+
+Snapshot tests are useful when they protect a stable, public contract.
+
+In this plugin, high-value snapshots focus on:
+
+- public plugin contracts (rules, presets, parser-option flags)
+- normalized rule metadata matrices
+- generated documentation artifacts (for example README rule tables)
+- docs heading schemas and structural content contracts
+
+Snapshot tests are intentionally not the default for all tests. Rule behavior,
+autofixes, and diagnostics should still be asserted explicitly in `RuleTester`
+cases.
+
+## High-value snapshot targets in this repository
+
+The current snapshot suites cover:
+
+- `test/plugin-contract-snapshots.test.ts`
+  - exported rule names and counts
+  - preset matrix with normalized parser options and sorted rule IDs
+- `test/rule-metadata-snapshots.test.ts`
+  - normalized rule metadata contract summaries
+- `test/readme-rules-table-sync.test.ts`
+  - generated README rules section via file snapshot
+- `test/docs-heading-snapshots.test.ts`
+  - canonical rule-doc heading matrix per rule page
+
+## Anti-patterns to avoid
+
+Avoid snapshotting these unless there is a strong reason:
+
+- raw AST trees (too noisy and version-fragile)
+- full ESLint diagnostics objects for normal rule tests
+- unnormalized runtime objects with unstable key ordering
+- large snapshots that hide intent and are hard to review
+
+If a test can use a precise explicit assertion, prefer that over a large
+snapshot.
+
+## Snapshot design checklist
+
+Before adding a snapshot, ensure all of the following are true:
+
+1. The value represents a stable contract, not incidental internals.
+2. Fields are normalized and deterministic:
+   - sort arrays and keys
+   - remove volatile data (timestamps, environment-specific paths, random IDs)
+3. The snapshot payload is intentionally small and reviewer-friendly.
+4. The test name explains the contract, not just the mechanism.
+5. A failing diff should be actionable in code review.
+
+## Matcher selection
+
+Choose the matcher based on the output shape:
+
+- `toMatchSnapshot()`
+  - best for small-to-medium normalized object graphs
+- `toMatchInlineSnapshot()`
+  - best for compact payloads (identity labels, short strings)
+- `toMatchFileSnapshot()`
+  - best for generated text artifacts where markdown/code readability matters
+
+For generated Markdown sections or tables, prefer `toMatchFileSnapshot()`.
+
+## Update workflow
+
+Use focused updates first:
+
+```bash
+npx vitest run test/plugin-contract-snapshots.test.ts -u
+npx vitest run test/rule-metadata-snapshots.test.ts -u
+npx vitest run test/readme-rules-table-sync.test.ts -u
+npx vitest run test/docs-heading-snapshots.test.ts -u
+```
+
+Then verify without update mode:
+
+```bash
+npx vitest run test/plugin-contract-snapshots.test.ts test/rule-metadata-snapshots.test.ts test/readme-rules-table-sync.test.ts test/docs-heading-snapshots.test.ts
+```
+
+Finally run repo checks before opening a PR:
+
+```bash
+npm run lint:all:fix:quiet
+npm run typecheck
+npm test
+```
+
+## PR review checklist for snapshot changes
+
+- [ ] Snapshot diff reflects an intentional contract change.
+- [ ] No volatile or environment-specific fields were added.
+- [ ] Sorting/normalization is preserved.
+- [ ] Rule behavior tests (explicit assertions) were updated when required.
+- [ ] Generated docs snapshots still match canonical generators.
+
+## Additional notes
+
+- With async concurrent tests, use the local test context `expect` when
+  snapshotting to avoid association issues.
+- Prefer one logical contract per snapshot test block; split broad snapshots
+  into smaller focused contracts.
+- If a snapshot repeatedly churns from unrelated dependency updates, redesign
+  the payload to snapshot less and assert more explicitly.
+
+## Further reading
+
+- [Vitest Snapshot Guide](https://v2.vitest.dev/guide/snapshot.html)

package/docs/rules/guides/type-aware-linting-readiness.md

@@ -0,0 +1,105 @@
+---
+title: Type-aware linting readiness
+description: Checklist and rollout playbook for enabling type-aware eslint-plugin-typefest rules safely.
+---
+
+# Type-aware linting readiness
+
+Use this guide before enabling type-aware presets or rules in a large codebase.
+
+## When this guide applies
+
+Use this checklist when adopting:
+
+- `recommended-type-checked`
+- `strict` or `all` in projects with type-aware rules
+- `ts-extras/type-guards`
+
+## Readiness checklist
+
+### 1) Parser-service availability
+
+Confirm the lint runtime can provide full type services:
+
+- ESLint uses `@typescript-eslint/parser`
+- your lint config resolves the intended `tsconfig`(s)
+- the targeted files are included in those `tsconfig`(s)
+
+### 2) Project graph stability
+
+Before enabling strict typed checks:
+
+- `npm run typecheck` is green
+- baseline linting is green (or has a controlled known backlog)
+- generated types/artifacts are not stale
+
+### 3) Performance baseline
+
+Capture a baseline to detect regressions:
+
+```bash
+npx eslint "src/**/*.{ts,tsx}" --stats
+```
+
+Track:
+
+- total runtime
+- expensive files
+- hot rules that call type-checker operations frequently
+
+### 4) CI gate ordering
+
+Prefer this order:
+
+1. typecheck
+2. lint (typed rules enabled)
+3. tests
+
+This keeps typed-service failures easy to classify.
+
+## Recommended rollout sequence
+
+1. Start with one package/folder.
+2. Enable type-aware rules as `warn` first.
+3. Fix baseline findings in small batches.
+4. Promote to `error` once the scope stays green.
+5. Expand scope incrementally.
+
+## Fast validation commands
+
+```bash
+npm run typecheck
+npm run lint
+npm run test
+```
+
+For focused typed checks during migration:
+
+```bash
+npx eslint "src/**/*.{ts,tsx}" --stats
+```
+
+## Common failure modes
+
+### "Typed rule requires type information"
+
+Likely causes:
+
+- file not included in the active `tsconfig`
+- parser-service wiring mismatch for the current workspace
+- incorrect project root assumptions in local/CI lint execution
+
+### Large runtime regressions
+
+Likely causes:
+
+- expensive semantic checks on broad selectors
+- repeated checker calls without syntax prefilters
+- too-large rollout scope for first pass
+
+## Related docs
+
+- [Rollout and fix safety](./rollout-and-fix-safety.md)
+- [Rule adoption checklist](./adoption-checklist.md)
+- [Preset selection strategy](./preset-selection-strategy.md)
+- [Typed service path inventory](https://nick2bad4u.github.io/eslint-plugin-typefest/docs/developer/typed-paths)

package/docs/rules/overview.md

@@ -0,0 +1,49 @@
+---
+title: Overview
+description: README-style overview for eslint-plugin-typefest.
+---
+
+# eslint-plugin-typefest
+
+ESLint plugin for teams that want consistent TypeScript-first conventions based on:
+
+- [`type-fest`](https://github.com/sindresorhus/type-fest)
+- [`ts-extras`](https://github.com/sindresorhus/ts-extras)
+
+The plugin ships focused rule sets for modern Flat Config usage, with parser setup included in each preset.
+
+## Installation
+
+```bash
+npm install --save-dev eslint-plugin-typefest typescript
+```
+
+> `@typescript-eslint/parser` is loaded automatically by plugin presets.
+
+## Quick start (Flat Config)
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [typefest.configs.recommended];
+```
+
+That is enough for TypeScript files (`**/*.{ts,tsx,mts,cts}`).
+
+## Presets
+
+| Preset                                            | Preset page                                                         |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| 🟢 `typefest.configs.minimal`                     | [Minimal](./presets/minimal.md)                                     |
+| 🟡 `typefest.configs.recommended`                 | [Recommended](./presets/recommended.md)                             |
+| 🟠 `typefest.configs["recommended-type-checked"]` | [Recommended (type-checked)](./presets/recommended-type-checked.md) |
+| 🔴 `typefest.configs.strict`                      | [Strict](./presets/strict.md)                                       |
+| 🟣 `typefest.configs.all`                         | [All](./presets/all.md)                                             |
+| 💠 `typefest.configs["type-fest/types"]`          | [type-fest/types](./presets/type-fest-types.md)                     |
+| ✴️ `typefest.configs["ts-extras/type-guards"]`    | [ts-extras/type-guards](./presets/ts-extras-type-guards.md)         |
+
+## Next steps
+
+- Open **Getting Started** in this sidebar.
+- Browse [**Presets**](./presets/index.md) for preset-by-preset guidance.
+- Use **Rules** to review every rule with examples.

package/docs/rules/prefer-ts-extras-array-at.md

@@ -0,0 +1,132 @@
+# prefer-ts-extras-array-at
+
+Prefer [`arrayAt`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-at.ts) from `ts-extras` over `array.at(...)`.
+
+`arrayAt(...)` preserves stronger element typing for indexed array access.
+
+## Targeted pattern scope
+
+This rule focuses on direct `array.at(index)` calls that can be migrated to `arrayAt(array, index)` with deterministic fixes.
+
+- `array.at(index)` call sites that can use `arrayAt(array, index)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayAt(array, index)` migrations safe.
+
+## What this rule reports
+
+This rule reports `array.at(index)` call sites when `arrayAt(array, index)` is the intended replacement.
+
+- `array.at(index)` call sites that can use `arrayAt(array, index)`.
+
+## Why this rule exists
+
+`arrayAt` keeps indexed access explicit and improves type inference for tuples and readonly arrays.
+
+- Indexing logic is standardized across modules.
+- Tuple element access needs fewer local casts.
+- Call sites remain explicit about both source array and index.
+
+## ❌ Incorrect
+
+```ts
+const firstStatus = statuses.at(0);
+```
+
+## ✅ Correct
+
+```ts
+const firstStatus = arrayAt(statuses, 0);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics align with `Array.prototype.at`.
+- Negative indexes are supported (`-1` means last element).
+- Out-of-range access still returns `undefined`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const selected = tuple.at(-1); // Weaker tuple index inference
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const selected = arrayAt(tuple, -1);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const first = arrayAt(users, 0);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-at": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if native `.at()` usage is required by a local coding standard.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/array-at.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-at.ts)
+
+````ts
+/**
+Return the item at the given index like `Array#at()`, but with stronger typing for tuples. Supports `-1` on tuples.
+
+This mirrors the runtime behavior of `Array#at()` and returns `undefined` for out-of-bounds indices. For tuples, a negative index of `-1` resolves to the tuple’s last element type. Positive literal indices for tuples resolve to the corresponding element type.
+
+@example
+```
+import {arrayAt} from 'ts-extras';
+
+const tuple = ['abc', 123, true] as const;
+const last = arrayAt(tuple, -1);
+//=> true
+//   ^? true | undefined
+
+const first = arrayAt(tuple, 0);
+//=> 'abc'
+//   ^? 'abc' | undefined
+
+const array = ['a', 'b', 'c'];
+const maybeItem = arrayAt(array, -1);
+//=> 'c'
+//   ^? string | undefined
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R001
+
+## Further reading
+
+- [`ts-extras` README](https://github.com/sindresorhus/ts-extras)
+- [`ts-extras` package reference](https://www.npmjs.com/package/ts-extras)
+- [TypeScript Handbook: Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)