vigiles 2.0.0

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        |

package/skills/linter-docs/pylint.md

@@ -0,0 +1,288 @@
+# Pylint — Reference
+
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom checkers).
+
+## Check Existing Plugins First
+
+Before writing a custom checker, search these plugins — the pattern may already be covered:
+
+| Plugin                          | Scope                                       | Key messages to know                                                                                                                                |
+| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pylint` (core)                 | Convention, Refactor, Warning, Error, Fatal | `C0114` (missing-module-docstring), `R0902` (too-many-instance-attributes), `W0612` (unused-variable), `E1101` (no-member), `W0611` (unused-import) |
+| `pylint-django`                 | Django conventions                          | `E5110` (no-member on Django models), `W5101` (fixme in templates), `C5105` (string-used-as-django-setting)                                         |
+| `pylint-celery`                 | Celery task patterns                        | Detects common Celery anti-patterns (task retry without max_retries, etc.)                                                                          |
+| `pylint-pydantic`               | Pydantic model checking                     | Suppresses false positives from Pydantic's metaclass magic                                                                                          |
+| `pylint-pytest`                 | pytest conventions                          | `W6301` (useless-pytest-mark-decorator), `W6302` (unnecessary-pytest-mark-parametrize)                                                              |
+| `pylint-flask`                  | Flask patterns                              | Suppresses false positives for Flask's app context, request globals                                                                                 |
+| `pylint-sqlalchemy`             | SQLAlchemy ORM                              | Suppresses false `no-member` on SQLAlchemy models                                                                                                   |
+| `pylint-protobuf`               | Protobuf message checking                   | Type-checks protobuf field access, catches typos in field names                                                                                     |
+| `pylint-import-modules`         | Import style enforcement                    | `C6201` (import-modules-only) — enforce `import module` over `from module import name`                                                              |
+| `pylint-secure-coding-standard` | Security patterns                           | Detects insecure patterns: `eval`, `exec`, hardcoded passwords, insecure hash algorithms                                                            |
+
+**Tip:** Many patterns can be handled by Pylint's built-in `bad-names`, `good-names`, `bad-functions`, or the `--disable`/`--enable` system without a custom checker.
+
+**Also consider Ruff.** If the project uses Ruff, it reimplements many Pylint rules (prefixed `PL`) at much higher speed. Check Ruff's rule catalog before writing a Pylint-specific checker.
+
+## Checker Anatomy
+
+Every Pylint checker inherits from `BaseChecker`:
+
+```python
+"""Checker for direct database queries outside the repository layer."""
+
+from astroid import nodes
+from pylint.checkers import BaseChecker
+from pylint.interfaces import HIGH
+
+
+class NoDirectDbQueryChecker(BaseChecker):
+    name = "no-direct-db-query"
+
+    msgs = {
+        "C9001": (
+            "Use %sRepository instead of %s.%s",
+            "no-direct-db-query",
+            "Direct model queries should go through the repository layer.",
+        ),
+    }
+
+    # Optional: add configuration options
+    options = (
+        (
+            "allowed-models",
+            {
+                "default": (),
+                "type": "csv",
+                "metavar": "<models>",
+                "help": "Models that are allowed to be queried directly.",
+            },
+        ),
+    )
+
+    def visit_call(self, node: nodes.Call) -> None:
+        if not isinstance(node.func, nodes.Attribute):
+            return
+        if not isinstance(node.func.expr, nodes.Name):
+            return
+
+        model = node.func.expr.name
+        method = node.func.attrname
+
+        if method in ("objects", "filter", "get", "all", "count", "values"):
+            if model not in self.linter.config.allowed_models:
+                self.add_message(
+                    "no-direct-db-query",
+                    node=node,
+                    args=(model, model, method),
+                    confidence=HIGH,
+                )
+
+
+def register(linter):
+    linter.register_checker(NoDirectDbQueryChecker(linter))
+```
+
+### Key concepts
+
+| Concept       | Purpose             | Notes                                                      |
+| ------------- | ------------------- | ---------------------------------------------------------- |
+| `name`        | Checker identifier  | Must be unique across all checkers                         |
+| `msgs`        | Message dictionary  | Key format: `{C,R,W,E,F}{4 digits}` — category + unique ID |
+| `options`     | Configuration       | Exposed via `pylintrc` or command line                     |
+| `visit_*`     | AST visitor methods | Called for each matching node type                         |
+| `leave_*`     | Post-visit methods  | Called when leaving a node (post-order)                    |
+| `add_message` | Report a violation  | Pass message ID, node, args for formatting                 |
+| `register`    | Plugin entry point  | Module-level function that registers the checker           |
+
+### Message categories
+
+| Prefix | Category   | When to use                                |
+| ------ | ---------- | ------------------------------------------ |
+| `C`    | Convention | Style/naming conventions                   |
+| `R`    | Refactor   | Code that works but should be restructured |
+| `W`    | Warning    | Probable bugs or risky patterns            |
+| `E`    | Error      | Definite bugs or broken code               |
+| `F`    | Fatal      | Pylint can't process the file              |
+
+Choose a unique 4-digit code starting from `9001` to avoid collisions with core Pylint. Check existing codes with `pylint --list-msgs`.
+
+## AST Nodes — Cheat Sheet (astroid)
+
+Pylint uses `astroid` for AST parsing, which adds type inference on top of Python's `ast` module:
+
+| You want to detect         | Node type / visitor                                 | Notes                                         |
+| -------------------------- | --------------------------------------------------- | --------------------------------------------- |
+| Function call `foo()`      | `visit_call` + check `node.func`                    | `node.func` is a `Name` or `Attribute`        |
+| Method call `obj.method()` | `visit_call` + `isinstance(node.func, Attribute)`   | `node.func.attrname` = method name            |
+| Import `import X`          | `visit_import`                                      | `node.names` = list of `(name, alias)` tuples |
+| Import `from X import Y`   | `visit_importfrom`                                  | `node.modname` = module, `node.names` = names |
+| Class definition           | `visit_classdef`                                    | `node.name`, `node.bases`, `node.body`        |
+| Function definition        | `visit_functiondef`                                 | `node.name`, `node.args`, `node.body`         |
+| Assignment `x = ...`       | `visit_assign`                                      | `node.targets`, `node.value`                  |
+| String literal             | `visit_const` + check `isinstance(node.value, str)` |                                               |
+| Decorator `@foo`           | `visit_decorators`                                  | Or check `node.decorators` on function/class  |
+| `raise` statement          | `visit_raise`                                       | `node.exc` = exception expression             |
+| `with` statement           | `visit_with`                                        | `node.items` = context manager list           |
+| `try`/`except`             | `visit_tryexcept`                                   | `node.handlers` = list of except clauses      |
+
+### astroid type inference
+
+astroid can infer types, which is more powerful than plain AST:
+
+```python
+def visit_call(self, node: nodes.Call) -> None:
+    # Infer what the function resolves to
+    try:
+        for inferred in node.func.infer():
+            if isinstance(inferred, nodes.FunctionDef):
+                # We know the actual function being called
+                if inferred.name == "dangerous_function":
+                    self.add_message("no-dangerous-call", node=node)
+    except astroid.InferenceError:
+        pass  # Can't determine — skip
+```
+
+**Caution:** `infer()` can raise `InferenceError` and can return `Uninferable`. Always handle both.
+
+## Testing Checkers
+
+```python
+"""Tests for no_direct_db_query checker."""
+
+import astroid
+import pylint.testutils
+
+from my_checkers.no_direct_db_query import NoDirectDbQueryChecker
+
+
+class TestNoDirectDbQueryChecker(pylint.testutils.UnittestLinter):
+    CHECKER_CLASS = NoDirectDbQueryChecker
+
+    def test_direct_query_flagged(self):
+        node = astroid.extract_node("""
+            User.objects.filter(active=True)  #@
+        """)
+        with self.assertAddsMessages(
+            pylint.testutils.MessageTest(
+                msg_id="no-direct-db-query",
+                node=node,
+                args=("User", "User", "objects"),
+            ),
+        ):
+            self.checker.visit_call(node)
+
+    def test_repository_call_allowed(self):
+        node = astroid.extract_node("""
+            UserRepository.active_users()  #@
+        """)
+        with self.assertNoMessages():
+            self.checker.visit_call(node)
+```
+
+**Testing best practices:**
+
+1. **Use `astroid.extract_node` with `#@` marker.** The marker indicates which node to extract from the code.
+2. **Test with `assertAddsMessages` and `assertNoMessages`.** These are the canonical assertion methods.
+3. **Test configuration options.** If your checker has options, test each combination.
+4. **Test inference edge cases.** Code with dynamic attributes, metaclasses, or `__getattr__` may cause `InferenceError`.
+5. **Run with `pytest` not `unittest`.** Pylint's test utils work with both, but pytest gives better output.
+
+## Registration
+
+### As a Pylint plugin
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.pylint.main]
+load-plugins = ["my_checkers.no_direct_db_query"]
+```
+
+Or `.pylintrc`:
+
+```ini
+[MAIN]
+load-plugins=my_checkers.no_direct_db_query
+```
+
+The module must be importable from `PYTHONPATH`. For a local checker, put it in the project and ensure the path is set.
+
+### vigiles enforce() reference
+
+```typescript
+enforce(
+  "pylint/no-direct-db-query",
+  "Use repository pattern for all DB queries.",
+);
+```
+
+vigiles checks `pylint --help-msg=no-direct-db-query` and verifies the message exists and is enabled.
+
+## Edge Cases and Gotchas
+
+### Symbolic names vs message codes
+
+Pylint messages have both a code (`C0114`) and a symbolic name (`missing-module-docstring`). Both work in vigiles:
+
+```typescript
+enforce("pylint/C0114", "All modules need docstrings.");
+enforce("pylint/missing-module-docstring", "All modules need docstrings.");
+```
+
+Prefer symbolic names — they're readable and stable across Pylint versions.
+
+### astroid inference limitations
+
+astroid can't infer:
+
+- Dynamically constructed classes (`type("Foo", (Base,), {...})`)
+- Heavy metaprogramming (`__init_subclass__`, custom metaclasses)
+- C extensions (some methods on `numpy`, `pandas` are opaque)
+- Runtime-only attributes (`setattr`, `__dict__` manipulation)
+
+If your convention targets heavily dynamic code, expect false negatives. Add a comment explaining the limitation in the checker.
+
+### Plugin vs Ruff
+
+For simple pattern bans, Ruff's built-in rules or `flake8-*` plugins reimplemented in Ruff are 10-100x faster. Use a Pylint custom checker only when you need:
+
+- Type inference (astroid's `infer()`)
+- Cross-function or cross-module analysis
+- Configuration options exposed in `pylintrc`
+- Integration with Django/Flask/SQLAlchemy brain plugins
+
+### Message ID collisions
+
+Core Pylint uses codes `C0001`-`C8999`, `W0001`-`W8999`, etc. Custom checkers should use `9000+` to avoid collisions. Check with:
+
+```bash
+pylint --list-msgs | grep "C90\|W90\|E90"
+```
+
+### Performance
+
+- Pylint is slow on large codebases. Custom checkers add overhead per-file.
+- Avoid `infer()` in hot paths — each call can trigger recursive type resolution.
+- Use `visit_module` + early return to skip files that can't contain violations (e.g., skip test files for production-only rules).
+- Consider `--jobs=N` for parallel execution, but note that custom checkers must be pickle-safe for multiprocessing.
+
+### Monorepo considerations
+
+- Pylint resolves `pylintrc` / `pyproject.toml` from `cwd`, not from the file being linted. In a monorepo, run Pylint per-package.
+- vigiles checks `pylint --help-msg=<name>` from the project `basePath`. If packages have different plugins loaded, run from each package root.
+- Custom checkers must be on `PYTHONPATH`. In a monorepo, use relative `load-plugins` paths or install checkers as a development package.
+
+## Mapping PR Feedback to Checker Strategy
+
+| PR comment pattern                    | Best approach                                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| "Don't import X directly"             | `pylint/no-name-in-module` or custom checker with `visit_importfrom`                           |
+| "Don't call X()"                      | `pylint/bad-functions` config or custom checker with `visit_call`                              |
+| "Missing docstring"                   | `pylint/missing-function-docstring` (C0116) — already exists                                   |
+| "Function too long"                   | `pylint/too-many-statements` (R0915) — configure threshold                                     |
+| "Too many arguments"                  | `pylint/too-many-arguments` (R0913) — configure `max-args`                                     |
+| "Use logging instead of print"        | Ruff `T201` or custom checker banning `print()`                                                |
+| "Don't use global state"              | Custom checker detecting `global` keyword or module-level mutation                             |
+| "Always type-hint public methods"     | `pylint/missing-function-docstring` doesn't cover this — use `mypy --strict` or custom checker |
+| "Don't catch bare Exception"          | `pylint/broad-exception-caught` (W0718) — already exists                                       |
+| "Don't use mutable default arguments" | `pylint/dangerous-default-value` (W0102) — already exists                                      |