evlog Map Rule Creator

Create an evlog map Rule (or Framework Adapter)

Extend the coverage scanner in @evlog/cli. Two kinds of extension:

• A rule: a new question asked of every entry point (packages/cli/src/lib/map/rules/). This is the common case.
• A framework adapter: teach evlog map to find entry points in a new framework (packages/cli/src/lib/map/adapters/). Rarer and heavier; see the last section.

PR Title

feat(cli): add the {id} map rule

The cli scope already exists, so no scope registration is needed.

Requirement or opportunity? Decide first

This is the design decision everything else follows from (see apps/docs/content/3.cli/3.rules.md for the published contract):

Guiding principle (from error-catalog.ts): a rule that fires on perfectly good code is policing, not helping. Opportunities must be gated on a signal that makes the case on its own (duplication, an installed package used without its evlog integration), never on "you could adopt a feature you don't use".

Current requirements: wide-event (40), audit (25), structured-errors (20), page-error-handling (20), context (15), error-handling (15). Current opportunities: error-catalog, audit-coverage, ai-logging, auth-identity.

Touchpoints Checklist (rule)

Important: Do NOT consider the task complete until all applicable touchpoints have been addressed.

Step 1: Rule Source

One file, one exported const satisfying MapRule (from rules/types.ts; requirements and opportunities are its two variants):

export const {camelId}Rule = {
  id: '{id}',                    // kebab-case, matches CheckId
  category: 'requirement',       // or 'opportunity'
  title: '{col}',                // column header in --all, ~8 chars max
  expects: '{concrete thing}',   // e.g. 'log.audit()'
  question: 'Does this entry point …?',  // one sentence, shown by --inspect
  weight: 15,                    // requirements only — opportunities cannot have one
  docs: '/learn/…',              // docs path, no domain
  fixSlot: 'body',               // where suggest() lands: 'setup' | 'body' | … (default 'body')
  appliesTo: {
    kinds: HANDLER_KINDS,        // or a subset: 'api' | 'server-action' | 'middleware' | 'cron' | 'page'
    // frameworks: ['next'],     // optional framework gate
    when: ({ project, facts }) => /* opportunity gate — cheap, declarative */,
  },
  suggest({ project, target }) {
    // Code suggestion for `evlog map <file>`, aware of what the project already
    // has (project.catalogs, project.features…). Return lines of code.
    return ['const log = useLogger(event)']
  },
  create(context) {
    return {
      // Prefer onEnd + FileFacts — the shared AST pass already answers most
      // questions. Node-type listeners are the escape hatch.
      onEnd() {
        if (/* gap found */) context.report({ message: '…', line, snippet: true })
      },
    }
  },
} satisfies MapRule

Key rules:

• Reporting nothing means the rule passed. context.report() only for gaps.
• Read FileFacts first (../facts.ts). If the answer isn't there, consider extending the facts rather than writing AST listeners; facts are computed once per file for all rules.
• project (ProjectFacts) is the gate for opportunities: project.features (evlog features in use), project.pairable (installed packages evlog integrates with), project.catalogs (for naming things in suggestions).
• Messages are report copy. Concrete, lowercase, pointing at the evidence ("X is spelled out here and in 2 other files, and one catalog entry would cover them"). No exclamation marks, no advice-column tone.
• Weights are a scoring decision: look at score.ts and the existing spread (40 down to 15) and discuss the number in the PR rather than inventing precedent.
• Every rule id is also a suppression target (evlog-map-disable {id}) and part of the public evlog.map.json contract. Renaming later is a breaking change.

Steps 2 and 3: Registry + CheckId

Add the import and one REGISTRY line in rules/index.ts (report order matters: requirements before opportunities, heaviest first), and the id to the CheckId union in types.ts. The AssertIdsMatch type in index.ts fails the build if you forget either side.

Step 4: Tests

packages/cli/test/map/rules.test.ts has a declarative Case harness: source code in, expected check results out, with knobs for kind, framework, path (sensitivity), hasEvlog, features, pairable, dependencies, catalogs, barrels. Use runRuleSet([yourRule], run) to exercise the rule in isolation.

Cover at minimum:

1. The gap fires (with the message and line you expect)
2. The compliant version passes
3. The n/a boundaries: wrong kind, gated when returning false, hasEvlog: false phrasing if the rule branches on it
4. Opportunity gating. Does NOT fire when the project doesn't use the feature
5. suggest() output when it adapts to the project (e.g. names an existing catalog)
6. Suppression (evlog-map-disable {id}) behaves like the other rules. Usually free via the shared harness

Run: pnpm --filter @evlog/cli exec vitest run test/map/rules.test.ts

Step 5 and 6: Docs

Read apps/docs/AGENTS.md before touching anything under apps/docs/. Then in apps/docs/content/3.cli/3.rules.md: add the row (column title, id, weight/fires-when, expects) and a ### {title} — {question} section following the existing ones, covering what it checks, what passes, what fails, the suggested shape. Requirements with a weight also touch the scoring narrative in 4.scoring.md.