vigiles 2.5.0 → 3.0.0

package/skills/linter-docs/clippy.md

@@ -0,0 +1,241 @@
+# Clippy — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom lints).
+
+## Check Existing Lints First
+
+Before writing a custom lint, search these lint groups — the pattern may already be covered:
+
+| Lint group    | Scope                                               | Key lints to know                                                                                                                                            |
+| ------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `correctness` | Code that is outright wrong or will panic           | `uninit_assumed_init`, `wrong_self_convention`, `nonsensical_open_options`, `mistyped_literal_suffixes`, `transmuting_null`, `undropped_manually_drops`      |
+| `suspicious`  | Code that is very likely a bug                      | `suspicious_else_formatting`, `suspicious_unary_op_formatting`, `suspicious_op_assign_impl`, `blanket_clippy_restriction_lints`, `almost_complete_range`     |
+| `style`       | Idiomatic Rust style violations                     | `needless_return`, `redundant_closure`, `match_bool`, `single_match`, `collapsible_if`, `len_zero`, `manual_map`, `if_let_mutex`                             |
+| `complexity`  | Code that can be simplified                         | `unnecessary_cast`, `needless_borrow`, `redundant_clone`, `type_complexity`, `manual_strip`, `option_map_unit_fn`, `useless_conversion`                      |
+| `perf`        | Code that can be made faster                        | `large_enum_variant`, `box_collection`, `redundant_allocation`, `manual_memcpy`, `iter_nth`, `unnecessary_to_owned`, `needless_collect`                      |
+| `pedantic`    | Stricter lints, off by default                      | `unwrap_used`, `expect_used`, `cast_possible_truncation`, `cast_sign_loss`, `missing_errors_doc`, `missing_panics_doc`, `doc_markdown`, `must_use_candidate` |
+| `restriction` | Lints for specific project policies, off by default | `print_stdout`, `print_stderr`, `dbg_macro`, `unimplemented`, `todo`, `unwrap_used`, `expect_used`, `mem_forget`, `shadow_reuse`, `float_arithmetic`         |
+| `nursery`     | Experimental lints, may have false positives        | `missing_const_for_fn`, `cognitive_complexity`, `use_self`, `option_if_let_else`, `redundant_pub_crate`, `significant_drop_tightening`                       |
+| `cargo`       | Cargo manifest issues                               | `multiple_crate_versions`, `wildcard_dependencies`, `negative_feature_names`, `redundant_feature_names`                                                      |
+
+**Tip:** Run `cargo clippy --warn clippy::pedantic` on your codebase to see what pedantic catches before manually hunting for rules. The full lint list is at <https://rust-lang.github.io/rust-clippy/stable/>.
+
+## Lint Configuration
+
+### Cargo.toml `[lints.clippy]` section (recommended)
+
+The modern way to configure Clippy project-wide. Checked into version control, applies to every `cargo clippy` invocation:
+
+```toml
+# Cargo.toml
+[lints.clippy]
+# Enable entire groups
+pedantic = "warn"
+nursery = "warn"
+
+# Override individual lints
+unwrap_used = "deny"
+expect_used = "warn"
+cast_possible_truncation = "allow"
+
+# Restriction lints — opt-in individually
+print_stdout = "warn"
+dbg_macro = "deny"
+```
+
+This replaces the older `#![warn(clippy::pedantic)]` crate-level attribute approach. vigiles reads `Cargo.toml` for `enforce()` verification.
+
+### Inline attributes
+
+Use `#[allow]`, `#[warn]`, and `#[deny]` for per-item overrides:
+
+```rust
+// Suppress a lint on a single function
+#[allow(clippy::too_many_arguments)]
+fn create_widget(a: u32, b: u32, c: u32, d: u32, e: u32, f: u32, g: u32) { /* ... */ }
+
+// Escalate a lint to a hard error for a module
+#[deny(clippy::unwrap_used)]
+mod payment_processing {
+    // Any .unwrap() in this module fails compilation
+}
+
+// Warn on a lint for a specific impl block
+#[warn(clippy::cast_possible_truncation)]
+impl Converter {
+    fn to_u32(&self, val: u64) -> u32 { val as u32 }
+}
+```
+
+Attribute precedence (highest to lowest): `#[forbid]` > `#[deny]` > `#[warn]` > `#[allow]`. `#[forbid]` cannot be overridden by inner attributes — use it for security-critical lints.
+
+### `clippy.toml` / `.clippy.toml`
+
+Project-level configuration for lint thresholds and behavior:
+
+```toml
+# clippy.toml
+too-many-arguments-threshold = 10
+type-complexity-threshold = 500
+cognitive-complexity-threshold = 30
+single-char-binding-names-threshold = 4
+msrv = "1.70.0"
+
+# Disallow certain types
+disallowed-types = [
+    { path = "std::collections::HashMap", reason = "Use indexmap::IndexMap for deterministic iteration" },
+]
+
+# Disallow certain methods
+disallowed-methods = [
+    { path = "std::env::var", reason = "Use config::get() for environment access" },
+]
+
+# Disallow certain macros
+disallowed-macros = [
+    { path = "std::println", reason = "Use tracing::info! instead" },
+]
+```
+
+`disallowed-types`, `disallowed-methods`, and `disallowed-macros` are particularly powerful — they let you ban specific APIs project-wide with custom error messages, no custom lint needed.
+
+## Custom Lints
+
+### dylint — custom Clippy-style lints
+
+[dylint](https://github.com/trailofbits/dylint) loads lint libraries as dynamic libraries, giving you the same compiler internals that Clippy uses:
+
+```rust
+// my_lint/src/lib.rs
+use clippy_utils::diagnostics::span_lint_and_help;
+use rustc_lint::{LateContext, LateLintPass, LintArray, LintPass};
+use rustc_session::{declare_lint, declare_lint_pass};
+
+declare_lint! {
+    /// Disallow direct database calls outside the `db` module.
+    pub NO_DIRECT_DB_CALL,
+    Warn,
+    "direct database calls should go through the db module"
+}
+
+declare_lint_pass!(NoDirectDbCall => [NO_DIRECT_DB_CALL]);
+
+impl<'tcx> LateLintPass<'tcx> for NoDirectDbCall {
+    fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx rustc_hir::Expr<'_>) {
+        if is_direct_db_call(cx, expr) {
+            span_lint_and_help(
+                cx,
+                NO_DIRECT_DB_CALL,
+                expr.span,
+                "direct database calls are not allowed here",
+                None,
+                "use the repository pattern — import from `crate::db` instead",
+            );
+        }
+    }
+}
+```
+
+**When to use dylint vs existing Clippy lints:**
+
+| Situation                                 | Use                                         |
+| ----------------------------------------- | ------------------------------------------- |
+| Ban a specific function/type/macro        | `clippy.toml` `disallowed-*` — zero code    |
+| Enforce naming or style convention        | Existing Clippy pedantic/style lints        |
+| Detect a pattern needing type information | dylint — access to rustc type checker       |
+| Enforce architectural boundaries          | dylint or `cargo-deny` for dependency rules |
+| One-off "don't use X" in a single crate   | `#[deny(clippy::...)]` attribute            |
+
+**dylint tradeoffs:**
+
+- Tied to a specific Rust nightly version (compiler internals are unstable)
+- Requires maintaining a separate crate with `rustc_private` dependencies
+- `clippy_utils` provides helper functions but its API changes between releases
+- Build times increase since the lint library compiles against `rustc` internals
+
+For vigiles, reference dylint lints via: `enforce("clippy/no_direct_db_call", "Use the repository pattern.")` — the lint name maps to the `declare_lint!` identifier (snake_case).
+
+## Edge Cases and Gotchas
+
+### False positives from macros
+
+Clippy lints operate on the expanded AST. Macros can trigger false positives because the expanded code looks different from what the author wrote:
+
+```rust
+// This macro expansion may trigger `clippy::redundant_clone`
+// even though the clone is structurally necessary in the macro output
+my_derive_macro! {
+    struct Foo { bar: String }
+}
+```
+
+Workarounds:
+
+- `#[allow(clippy::...)]` on the macro invocation site
+- Add `#[automatically_derived]` in proc-macro output — Clippy skips many lints for derived code
+- File an issue upstream if the false positive is in a common macro pattern
+
+### Nightly-only lints
+
+Some Clippy lints require nightly Rust because they depend on unstable compiler features. The `nursery` group is the most common source. If you enable `nursery` lints in CI:
+
+- Pin a specific nightly version: `rust-toolchain.toml` with `channel = "nightly-2025-01-15"`
+- Expect breakage on nightly updates — nursery lints can be renamed, removed, or change behavior
+- Never `#[deny]` nursery lints — use `#[warn]` so they don't block builds when behavior changes
+
+### `allow` vs `warn` on groups
+
+Enabling a group and then allowing individual lints works top-down:
+
+```toml
+# Cargo.toml
+[lints.clippy]
+pedantic = "warn"           # Enable all pedantic lints
+module_name_repetitions = "allow"   # But suppress this one
+```
+
+The reverse does NOT work — you cannot `allow` a group and then `warn` an individual lint from it. The group-level `allow` takes precedence. Always enable groups first, then suppress specific lints.
+
+### Interaction with `#[must_use]`
+
+Clippy's `must_use_candidate` lint (pedantic) suggests adding `#[must_use]` to functions that return values. This interacts with other lints:
+
+- Once `#[must_use]` is added, callers who ignore the return value get `unused_must_use` (a rustc warning, not Clippy)
+- `let _ = foo()` silences `unused_must_use` but triggers `let_underscore_must_use` (Clippy restriction)
+- `drop(foo())` silences both but may trigger `drop_non_drop` if the type doesn't implement `Drop`
+
+Recommendation: Enable `must_use_candidate` globally, but only `#[deny(unused_must_use)]` in modules where ignoring results is dangerous (I/O, error handling).
+
+### Unsafe code linting
+
+Clippy provides several lints for `unsafe` code, but they have limitations:
+
+- `undocumented_unsafe_blocks` (restriction) — requires a `// SAFETY:` comment above every `unsafe` block. Enable this project-wide.
+- `unsafe_derive_deserialize` (pedantic) — warns when `Deserialize` is derived on types with unsafe invariants
+- `multiple_unsafe_ops_per_block` (restriction) — each `unsafe` block should contain exactly one unsafe operation for precise `// SAFETY:` documentation
+
+These lints do NOT verify that safety invariants are actually upheld — they only enforce documentation conventions. Use `cargo miri test` and `#[cfg(miri)]` for runtime verification of unsafe code.
+
+### MSRV-aware lints
+
+Clippy respects the `msrv` field in `clippy.toml`. Some lints suggest replacements that require newer Rust versions. If you set `msrv = "1.65.0"`, Clippy won't suggest `let-else` (stabilized in 1.65) but will suppress suggestions for features from 1.66+. Always set this to match your `rust-version` in `Cargo.toml`.
+
+## Mapping PR Feedback to Lint Strategy
+
+| PR comment pattern                          | Best approach                                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| "Don't use `.unwrap()`"                     | `enforce("clippy/unwrap_used", "Use expect() with context or propagate with ?.")` — pedantic, enable project-wide |
+| "Don't call this function"                  | `clippy.toml` `disallowed-methods` — zero custom code, includes custom error message                              |
+| "Don't use this type"                       | `clippy.toml` `disallowed-types` — same approach, works for `HashMap`, `Mutex`, etc.                              |
+| "Don't use `println!`"                      | `enforce("clippy/print_stdout", "Use tracing macros.")` — restriction lint, opt-in                                |
+| "Add error context"                         | Not Clippy — use `#[deny(clippy::unwrap_used)]` + guidance for `anyhow`/`thiserror` patterns                      |
+| "This clone is unnecessary"                 | `enforce("clippy/redundant_clone", "Remove the unnecessary clone.")` — already in complexity group                |
+| "Use `Self` in impl blocks"                 | `enforce("clippy/use_self", "Use Self instead of repeating the type name.")` — nursery lint                       |
+| "Document safety invariants"                | `enforce("clippy/undocumented_unsafe_blocks", "Add a // SAFETY: comment.")` — restriction lint                    |
+| "Too many function parameters"              | `enforce("clippy/too_many_arguments", "Refactor into a config struct.")` — already in complexity group            |
+| "Wildcard deps in Cargo.toml"               | `enforce("clippy/wildcard_dependencies", "Pin dependency versions.")` — cargo group                               |
+| "Every public fn needs error docs"          | `enforce("clippy/missing_errors_doc", "Document the errors this function can return.")` — pedantic                |
+| "Avoid `as` casts"                          | `enforce("clippy/cast_possible_truncation", "Use try_from() or explicit checked conversion.")` — pedantic         |
+| "Don't leave `todo!()` in code"             | `enforce("clippy/todo", "Replace todo!() with an implementation or file an issue.")` — restriction lint           |
+| "Use the builder pattern"                   | Not Clippy — use vigiles `guidance()` for architectural patterns                                                  |
+| "Enforce import boundaries between modules" | Not Clippy — use `cargo-deny` for crate-level boundaries or dylint for module-level enforcement                   |

package/skills/linter-docs/eslint.md

@@ -0,0 +1,384 @@
+# ESLint — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+
+## Check Existing Plugins First
+
+Before writing a custom rule, search these plugins — the pattern may already be covered:
+
+| Plugin                                              | Scope                               | Key rules to know                                                                                                                              |
+| --------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@typescript-eslint`                                | Type-aware TS rules                 | `no-floating-promises`, `no-misused-promises`, `strict-boolean-expressions`, `naming-convention`, `no-restricted-imports` (type-aware variant) |
+| `eslint-plugin-import-x`                            | Import hygiene (flat-config native) | `no-cycle`, `no-unresolved`, `no-extraneous-dependencies`, `order`, `no-internal-modules`                                                      |
+| `eslint-plugin-boundaries`                          | Module boundary enforcement         | `element-types`, `entry-point`, `external` — define allowed dependency directions between architectural layers                                 |
+| `eslint-plugin-sonarjs`                             | Code smells & complexity            | `cognitive-complexity`, `no-duplicate-string`, `no-identical-functions`, `no-nested-conditional`                                               |
+| `eslint-plugin-unicorn`                             | Modern JS idioms                    | `prefer-node-protocol`, `no-array-for-each`, `prefer-top-level-await`, `filename-case`                                                         |
+| `eslint-plugin-react` / `eslint-plugin-react-hooks` | React patterns                      | `rules-of-hooks`, `exhaustive-deps`, `no-unstable-nested-components`, `jsx-no-leaked-render`                                                   |
+| `eslint-plugin-jsx-a11y`                            | Accessibility                       | `alt-text`, `anchor-is-valid`, `no-autofocus`, `click-events-have-key-events`                                                                  |
+| `eslint-plugin-n`                                   | Node.js-specific                    | `no-sync`, `no-process-exit`, `prefer-global/buffer`, `no-unsupported-features`                                                                |
+| `eslint-plugin-regexp`                              | Regex safety                        | `no-super-linear-backtracking`, `no-misleading-unicode-character`, `prefer-quantifier`                                                         |
+| `eslint-plugin-security`                            | Security anti-patterns              | `detect-object-injection`, `detect-non-literal-regexp`, `detect-child-process`                                                                 |
+| `@eslint/json` / `@eslint/markdown`                 | Non-JS file linting                 | Lint JSON and markdown files with ESLint flat config — useful for config validation                                                            |
+
+**Tip:** `no-restricted-syntax` with an AST selector handles many one-off patterns without a custom rule. Try it first.
+
+## Rule Anatomy
+
+Every ESLint rule is an object with `meta` and `create`:
+
+```js
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: "suggestion", // "problem" | "suggestion" | "layout"
+    docs: {
+      description: "Disallow direct database calls outside the data layer",
+      recommended: false,
+    },
+    messages: {
+      noDirectDb:
+        "Use the repository pattern — import from 'src/data/' instead of calling {{ name }} directly.",
+    },
+    fixable: null, // "code" if you provide a fixer
+    schema: [], // JSON Schema for rule options
+  },
+
+  create(context) {
+    return {
+      // visitor methods keyed by AST node type or selector
+      CallExpression(node) {
+        if (isDirectDbCall(node)) {
+          context.report({
+            node,
+            messageId: "noDirectDb",
+            data: { name: node.callee.name },
+          });
+        }
+      },
+    };
+  },
+};
+```
+
+### meta.type — choose correctly
+
+| Type           | When to use                               | Example                                           |
+| -------------- | ----------------------------------------- | ------------------------------------------------- |
+| `"problem"`    | Code that is/will be broken               | Missing `await` on a promise                      |
+| `"suggestion"` | Code that works but violates a convention | Using `console.log` instead of the project logger |
+| `"layout"`     | Whitespace/formatting only                | Rarely used — Prettier handles this               |
+
+### meta.messages — be prescriptive
+
+Bad: `"Don't do this."` — tells the developer nothing.
+Good: `"Use the {{ replacement }} wrapper instead of {{ original }}."` — tells them exactly what to write.
+
+Always include **what to do** in the message, not just what's wrong.
+
+## AST Node Types — Cheat Sheet
+
+Common patterns and the AST nodes that catch them:
+
+| You want to detect         | AST node / selector                                                             | Notes                               |
+| -------------------------- | ------------------------------------------------------------------------------- | ----------------------------------- |
+| Function call `foo()`      | `CallExpression[callee.name="foo"]`                                             | Selector form — no code needed      |
+| Method call `obj.method()` | `CallExpression[callee.type="MemberExpression"][callee.property.name="method"]` |                                     |
+| Import `from "module"`     | `ImportDeclaration[source.value="module"]`                                      | Static imports only                 |
+| `require("module")`        | `CallExpression[callee.name="require"][arguments.0.value="module"]`             | CJS                                 |
+| Variable named X           | `VariableDeclarator[id.name="X"]`                                               |                                     |
+| Class with decorator       | `ClassDeclaration > Decorator`                                                  | Experimental — needs parser support |
+| JSX element `<Foo>`        | `JSXOpeningElement[name.name="Foo"]`                                            | Needs JSX parser                    |
+| Template literal           | `TemplateLiteral`                                                               | Includes tagged templates           |
+| `throw` statement          | `ThrowStatement`                                                                |                                     |
+| `new Promise()`            | `NewExpression[callee.name="Promise"]`                                          |                                     |
+
+**Pro tip:** Use [AST Explorer](https://astexplorer.net) (parser: `@typescript-eslint/parser`, transform: `ESLint v4`) to prototype visitor logic interactively.
+
+## ESTree Selectors
+
+ESLint supports CSS-like AST selectors. These replace boilerplate visitor code:
+
+```js
+create(context) {
+  return {
+    // Match: import from any path containing "internal"
+    'ImportDeclaration[source.value=/internal/]'(node) {
+      context.report({ node, messageId: "noInternalImport" });
+    },
+
+    // Match: await inside a loop body
+    'ForStatement > BlockStatement AwaitExpression'(node) {
+      context.report({ node, messageId: "noAwaitInLoop" });
+    },
+
+    // Match: console.log, console.warn, console.error
+    'MemberExpression[object.name="console"]'(node) {
+      context.report({ node: node.parent, messageId: "useLogger" });
+    },
+  };
+}
+```
+
+Selector syntax:
+
+- `A > B` — B is a direct child of A
+- `A B` — B is a descendant of A
+- `A[attr="val"]` — attribute match (string equality)
+- `A[attr=/regex/]` — attribute match (regex)
+- `A:exit` — fires when **leaving** the node (post-order)
+- `:not(A)` — negation
+- `A + B` — B immediately follows A (sibling)
+
+## Accessing TypeScript Type Information
+
+For type-aware rules, use `@typescript-eslint/utils`:
+
+```ts
+import { ESLintUtils } from "@typescript-eslint/utils";
+
+const createRule = ESLintUtils.RuleCreator(
+  (name) => `https://example.com/rules/${name}`,
+);
+
+export default createRule({
+  name: "no-unhandled-promise",
+  meta: {
+    type: "problem",
+    docs: { description: "Require promises to be handled" },
+    messages: { unhandled: "This promise must be awaited or returned." },
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    const services = ESLintUtils.getParserServices(context);
+    const checker = services.program.getTypeChecker();
+
+    return {
+      ExpressionStatement(node) {
+        const tsNode = services.esTreeNodeToTSNodeMap.get(node.expression);
+        const type = checker.getTypeAtLocation(tsNode);
+        if (isPromiseLike(checker, type)) {
+          context.report({ node, messageId: "unhandled" });
+        }
+      },
+    };
+  },
+});
+```
+
+**Requirements for type-aware rules:**
+
+1. The ESLint config must use `@typescript-eslint/parser` with `projectService: true` (or legacy `project` option)
+2. The rule must live in a plugin (not standalone `eslint-rules/` dir) for parser services to work reliably
+3. Type-aware rules are slower — only use when you genuinely need type information
+
+## Auto-Fix and Suggestions
+
+### `fix` — automatic, silent
+
+Use for safe, semantics-preserving changes:
+
+```js
+context.report({
+  node,
+  messageId: "preferNodeProtocol",
+  fix(fixer) {
+    return fixer.replaceText(node.source, `"node:${module}"`);
+  },
+});
+```
+
+Safety rules for `fix`:
+
+- **Never change runtime behavior.** If the fix might break code, use `suggest` instead.
+- **Never remove code** unless it's provably dead.
+- One `fix` per report. Multiple changes go in a single fix call using an array.
+- Test your fix: `RuleTester` will verify the fix output matches `output` in your test case.
+
+### `suggest` — manual, user-picks
+
+Use for changes that might alter semantics:
+
+```js
+context.report({
+  node,
+  messageId: "noDirectDbCall",
+  suggest: [
+    {
+      messageId: "wrapWithRepo",
+      fix(fixer) {
+        return fixer.replaceText(
+          node,
+          `repository.${node.callee.property.name}(${argsText})`,
+        );
+      },
+    },
+  ],
+});
+```
+
+## Testing with RuleTester
+
+```js
+import { RuleTester } from "eslint";
+import rule from "./no-direct-db.js";
+
+const tester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2024,
+    sourceType: "module",
+  },
+});
+
+tester.run("no-direct-db", rule, {
+  valid: [
+    // Always include: correctly following the rule
+    `import { findUser } from "src/data/users";`,
+    // Edge case: dynamic import (intentionally allowed)
+    `const mod = await import("pg");`,
+  ],
+  invalid: [
+    {
+      code: `import { Pool } from "pg";`,
+      errors: [{ messageId: "noDirectDb" }],
+    },
+    // If the rule has a fixer, test the output
+    {
+      code: `const fs = require("fs");`,
+      output: `const fs = require("node:fs");`,
+      errors: [{ messageId: "preferNodeProtocol" }],
+    },
+  ],
+});
+```
+
+**Testing best practices:**
+
+1. **Test the valid cases first.** If valid cases fail, your rule is too aggressive.
+2. **Include edge cases.** Dynamic imports, re-exports, type-only imports, destructured requires.
+3. **Test error placement.** Use `errors: [{ messageId, line, column }]` to verify the squiggly appears on the right token.
+4. **Test with options.** If your rule has configurable options, test each combination.
+5. **For TypeScript rules**, use `@typescript-eslint/rule-tester` and provide `parser` + `parserOptions` with a real `tsconfig.json`.
+
+## Flat Config Registration
+
+ESLint 9+ uses flat config. Register custom rules via a local plugin object:
+
+```js
+// eslint.config.js
+import noDirectDb from "./eslint-rules/no-direct-db.js";
+
+export default [
+  {
+    plugins: {
+      // Namespace all custom rules under "local"
+      local: {
+        rules: {
+          "no-direct-db": noDirectDb,
+        },
+      },
+    },
+    rules: {
+      "local/no-direct-db": "error",
+    },
+  },
+];
+```
+
+**Important:** The config key in `rules` must be `<plugin-namespace>/<rule-name>`. The `enforce()` reference in vigiles matches this: `enforce("eslint/local/no-direct-db", "...")`.
+
+If the project still uses legacy `.eslintrc`, the rule goes in `rulesDir` instead — but flat config is the path forward.
+
+## Edge Cases and Gotchas
+
+### TypeScript AST differences
+
+TypeScript adds AST node types that ESTree doesn't have. Common ones to watch for:
+
+- `TSAsExpression` — `x as string` wraps the expression; your visitor might miss the inner node
+- `TSNonNullExpression` — `x!` adds a wrapper node
+- `TSTypeAnnotation` — `: string` on parameters creates child nodes that break naive `node.params.length` checks
+- `TSImportEqualsDeclaration` — `import x = require("y")` is NOT an `ImportDeclaration`
+- `TSEnumDeclaration` — enums look like variable declarations but aren't
+
+**Rule of thumb:** If your rule targets function parameters, imports, or expressions, test it with TypeScript annotations and assertions.
+
+### `no-restricted-syntax` — the 80% solution
+
+Before writing a custom rule, check if `no-restricted-syntax` covers it:
+
+```js
+rules: {
+  "no-restricted-syntax": ["error",
+    {
+      selector: 'CallExpression[callee.object.name="console"]',
+      message: "Use the project logger from 'src/lib/logger'.",
+    },
+    {
+      selector: 'ImportDeclaration[source.value="moment"]',
+      message: "Use dayjs — we're migrating off moment.",
+    },
+  ],
+}
+```
+
+This works for any pattern you can express as an AST selector. You only need a custom rule when you need:
+
+- Type information
+- Multi-node analysis (e.g., "if X is imported, then Y must also be imported")
+- Auto-fix or suggestions
+- Configurable options via schema
+
+### `no-restricted-imports` — the import-specific shortcut
+
+For import bans specifically, `no-restricted-imports` is more ergonomic:
+
+```js
+rules: {
+  "no-restricted-imports": ["error", {
+    paths: [
+      { name: "lodash", message: "Import specific lodash functions: lodash/get" },
+      { name: "moment", message: "Use dayjs instead." },
+    ],
+    patterns: [
+      { group: ["src/internal/*"], message: "Use the public API from src/index.ts" },
+    ],
+  }],
+}
+```
+
+### Auto-fix conflicts
+
+If two rules try to fix the same range of code, ESLint drops both fixes. Avoid this by:
+
+- Keeping fix ranges tight (fix only the exact tokens, not the whole statement)
+- Using `suggest` instead of `fix` when the rule might overlap with Prettier or another fixer
+- Testing with `--fix-dry-run` before enabling in CI
+
+### Performance
+
+- Avoid `Program:exit` handlers that walk the entire AST — use specific node visitors instead.
+- Selector matching has overhead. For hot paths, a manual `CallExpression` check is faster than a complex selector.
+- Type-aware rules add ~2-5x overhead because they invoke the TypeScript compiler. Group them in a separate config block with `files: ["src/**/*.ts"]` so they only run on TS files.
+- If your custom rules directory has more than ~10 rules, bundle them into a proper plugin package for better caching.
+
+### Monorepo considerations
+
+- ESLint flat config is resolved from `cwd`, not from the file being linted. In a monorepo, set `cwd` to the package root, not the workspace root.
+- `vigiles generate-types` discovers ESLint rules using `calculateConfigForFile("dummy.js")` from the project `basePath`. If your monorepo has different configs per package, run `generate-types` from each package root.
+- Plugin rules must be installed in the `node_modules` visible from the config file's location. Hoisted deps in a monorepo can cause "plugin not found" errors — install them in the package's own `devDependencies`.
+
+## Mapping PR Feedback to Rule Strategy
+
+| PR comment pattern                  | Best approach                                                                                      |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| "Don't import from X"               | `no-restricted-imports` — zero custom code                                                         |
+| "Don't call X()"                    | `no-restricted-syntax` with a `CallExpression` selector                                            |
+| "Use X instead of Y"                | `no-restricted-syntax` if detection is simple; custom rule with `fix` if you want auto-replacement |
+| "Every file must have X"            | Not ESLint — use vigiles `check(every(...).has(...))`                                              |
+| "This promise isn't awaited"        | `@typescript-eslint/no-floating-promises` — already exists                                         |
+| "Use our custom hook"               | Custom rule checking `CallExpression` against an allow-list                                        |
+| "Wrong naming convention"           | `@typescript-eslint/naming-convention` — highly configurable, rarely needs custom code             |
+| "Don't use `any`"                   | `@typescript-eslint/no-explicit-any` — already exists                                              |
+| "Wrap API calls with error handler" | Custom rule: detect unwrapped `fetch`/`axios` calls, `suggest` the wrapper                         |
+| "Don't mutate state directly"       | `eslint-plugin-react` `no-direct-mutation-state` or custom rule checking assignment targets        |