legion-audit 0.1.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,162 @@
 # legion-audit
 
+## 0.5.0
+
+### Minor Changes
+
+- 45ef19c: Five changes aimed at the same thing: making the toolkit enforceable in a
+  repo that already has debt, rather than only in a new one.
+  
+  **Autofixers.** None of the rules had one. `button-has-type` and
+  `no-target-blank-without-rel` now insert the missing attribute, and
+  `no-react-fc` performs the whole transform, moving the type argument onto the
+  parameter so props do not silently become untyped. Three rules are
+  deliberately left unfixable: `alt=""` is a semantic claim that an image is
+  decorative, converting a `function` declaration to a `const` arrow changes
+  hoisting, and a hex literal cannot be replaced without knowing the token
+  name.
+  
+  **A suppression ratchet.** `legion-audit suppress` records today's findings
+  as accepted, so a repo can move to error level immediately and fail only on
+  new violations. This is what `--baseline` never did: that compares two
+  reports, this is a budget per rule and file, and a fourth violation in a file
+  that recorded three still fails.
+  
+  **`legion-steer`.** A new package that writes a managed block into
+  `AGENTS.md`, `.junie/guidelines.md`, `.cursor/rules/legion.mdc` and
+  `.github/copilot-instructions.md`, generated from the resolved lint config.
+  A rule the config does not enforce cannot appear in the block, so steering
+  cannot drift from enforcement. `legion-steer check` fails CI when it has.
+  Only the region between its markers is ever touched.
+  
+  `legion-steer hook` closes the loop. Lint reports a violation after the file
+  exists; the hook runs the same rules on the content Claude Code is about to
+  write and exits 2, which blocks the write. `PreToolUse` lints
+  `tool_input.content` in a scratch copy beside the intended path, so
+  path-based rules see the real directory, and the finding is reported against
+  the file the agent tried to write rather than the copy. `PostToolUse` lints
+  what just landed and reports without blocking. `init` registers both in
+  `.claude/settings.json`, merging with hooks that are already there.
+  
+  **A dependency check.** Section 10 lists adding a state library under
+  automatic rejection and nothing was checking it. The audit now reads
+  `package.json` for Redux, MobX, runtime CSS-in-JS and Moment, and nudges with
+  what to use instead.
+  
+  **GitHub annotations.** `legion-audit --annotations` emits workflow commands,
+  so findings land on the pull request diff rather than in a log.
+
+## 0.4.0
+
+No changes in this release.
+
+## 0.3.0
+
+### Minor Changes
+
+- 649a264: Ten new rules, a platform split, and the React Compiler flag actually working.
+  
+  Two of the rules were already law in LEGION-STANDARDS with no mechanical
+  check, which is the drift §8.1 warns about: `no-hardcoded-hex` (§7, §10 lists
+  it under automatic rejection) and `no-rn-button` (§3 mandates
+  `TouchableOpacity`, not `Button`). The rest are silent-default bugs rather
+  than style: `button-has-type` (HTML defaults a bare button to `submit`, so
+  one inside a form reloads the page), `no-target-blank-without-rel`,
+  `anchor-is-not-a-button`, `img-has-alt`, `no-dangerous-html`,
+  `no-array-index-key`, `touchable-has-accessibility-label` and
+  `controlled-text-input`.
+  
+  Rules now know their platform. `WEB_ONLY_RULES` gained the five DOM rules and
+  a mirrored `NATIVE_ONLY_RULES` holds the three React Native ones, so a config
+  only runs what can fire on its platform: the DOM rules are off under
+  `reactNative`, the native rules off everywhere else, and `no-hardcoded-hex`
+  and `no-array-index-key` run in both.
+  
+  New rules land at level 1 in `recommended` and 3 in `strict`. The cohort is
+  exported as `INTRODUCED_AT_WARN`, so promoting them later is one edit and the
+  preset tests fail if the policy changes silently. Adding a rule should never
+  turn an existing repo's build red for code written before it existed.
+  
+  `reactCompiler: true` now works when composed with a preset. It only enabled
+  `no-manual-memo` when the rule was `undefined`, but both presets set it to
+  `0` explicitly, so the flag was inert for every documented way of using it.
+  `legion-audit` also detects the compiler now — from
+  `babel-plugin-react-compiler`, `eslint-plugin-react-compiler`, or
+  `reactCompiler` in a Next config, never from the React version, since React
+  19 does not imply the compiler — and nudges when it is on while the rule is
+  off.
+  
+  `no-hardcoded-hex` is off in test files, since a rule's own fixtures have to
+  contain the thing it forbids.
+- 6c16c00: **Breaking:** `runAudit` is now `async` and returns `Promise<AuditResult>`.
+  Reading the consumer's installed plugin needs a dynamic import, which cannot
+  be done synchronously. Callers must `await` it. The `legion-audit` CLI does
+  this internally, so only code importing `runAudit` directly is affected. The
+  version bump stays minor because pre-1.0 that is where a breaking change
+  lands; a `major` here would force 1.0.0, which is a decision this change
+  should not make on its own.
+  
+  PR hygiene understands more than GitHub, and the audit reports rules your
+  config never picked up.
+  
+  `prHygiene` matched `/\(#\d+\)/`, which is GitHub's squash-merge subject and
+  nothing else. A GitLab, Bitbucket or Azure DevOps repo scored 0% and got a
+  nudge telling a team that reviews everything that it reviews nothing. The
+  forge is now read from the origin remote, each one gets the pattern it
+  actually writes, and the fix command matches the host (`gh pr create`,
+  `glab mr create`, `az repos pr create`). GitLab's merge-request reference
+  lives in the commit body rather than the subject, so the log format is now
+  `%s%n%b`. An unrecognized host skips the check rather than guessing, because
+  guessing is what caused this.
+  
+  New `ruleCoverage` check. A config that enumerates rules by hand stops
+  receiving them: the rules added since it was written sit at 0 and nothing
+  says so. The audit now reads the rule list from the plugin _the consumer has
+  installed_, compares it against what their oxlint config names or what
+  `eslint --print-config` resolves, and nudges with the missing rules by name.
+  Reading from the installed plugin rather than a list baked into the audit
+  keeps `legion-audit` dependency-free and means it reports against the version
+  in front of it.
+
+## 0.2.0
+
+### Minor Changes
+
+- 4d0ccf6: React Native support and an advice layer.
+  
+  `legion-rules` gains a `reactNative` preset and a `reactNative: true` flag on
+  `defineLegionConfig`. It turns off the two rules that can only describe a
+  server-rendered page, widens `no-admin-client-in-browser` to every file
+  because a device bundle has no unreachable half, and adds the `src/`-prefixed
+  `any` boundaries. `eslint-plugin-legion` exposes it as
+  `configs.reactNative`.
+  
+  `legion-audit` gains three things. An `expo-doctor` gate on Expo projects
+  that keeps a real version incompatibility blocking while demoting
+  patch-level drift to a nudge. Workspace awareness, so a package inside a
+  monorepo finds the lockfile and the hoisted bins at the workspace root
+  instead of reporting them missing. And a nudge layer: every run now ends with
+  what the repo could do better, why, and the command, including migrating off
+  npm or Yarn Classic to Yarn Berry in whichever package manager is currently
+  in use. Nudges never affect the score or the exit code. `legion-audit advice`
+  prints only those.
+  
+  Two scoring changes, both so the number measures what the current code
+  controls. PR hygiene no longer scores at all: it reads history on `main`,
+  cannot be fixed retroactively, and section 12 only requires a PR on a client
+  repo, so it is now a nudge. And the test penalty is the _share_ of components
+  and hooks left uncovered rather than the count, so decomposing one oversized
+  component into ten presentational children cannot make the score worse than
+  the component it replaced. `findRegressions` compares the same share for the
+  same reason.
+  
+  Test coverage is now measured rather than guessed. The audit reads
+  `coverage/coverage-summary.json` when it exists, then Istanbul's
+  `coverage-final.json` (which is what Jest's default reporters write, so it is
+  the more common of the two), then falls back to what the test files actually
+  import and `describe`, and only then to matching base names. A single test
+  file covering many components now counts for all of them.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -25,11 +25,36 @@ yarn legion-audit --md AUDIT.md --json audit.json
 | lint bypasses      | every `eslint-disable` / `oxlint-disable` directive and `NOSONAR`, counted per rule   |
 | file-wide disables | a bare `/* eslint-disable */` or `/* oxlint-disable */`; always a hard fail           |
 | PR hygiene         | share of the last 80 commits whose subject carries a `(#123)` PR number               |
-| tests by file      | components (`components/**`, `app/**`) and `use*` hooks without a matching test file  |
-| lockfile           | exactly one lockfile at the root                                                      |
+| expo-doctor        | `expo-doctor` on an Expo project; patch-level drift is a nudge, not a failure         |
+| test coverage      | the coverage report when there is one, otherwise what the test files actually import  |
+| lockfile           | exactly one lockfile, found at the workspace root when this is a monorepo package     |
+| toolchain          | package manager and Yarn flavor, framework, whether the plugin is actually wired in   |
 
 A tool that is not installed reports `skipped`, never `pass`.
 
+### Test coverage, in order of preference
+
+The question is which components and hooks are actually exercised, and there
+are three ways to answer it. The audit uses the best one available and says
+which in the report:
+
+1. **`coverage/coverage-summary.json`** if it exists. Real per-file line
+   coverage, which is a measurement rather than a guess. Run the suite once
+   with `--coverage --coverageReporters=json-summary` to get it.
+2. **What the test files import and `describe`.** One file covering thirteen
+   components counts for all thirteen. Group your tests however reads best;
+   the audit is not a reason to split them.
+3. **Matching base names**, only when there is nothing better to go on.
+
+### expo-doctor
+
+On an Expo project the doctor runs as a gate, but not every doctor failure is
+equal. A wrong major or minor against the installed SDK breaks builds and
+fails the gate. A newer patch existing does not break anything, and Expo
+ships patches faster than a project can consume them, so that is reported as
+a nudge with the exact `expo install --fix` to run. A gate that goes red for
+something unrelated to your code is a gate people learn to ignore.
+
 ## Output
 
 `AUDIT.md` opens with the gate table, then per-rule counts, findings with
@@ -40,6 +65,18 @@ The score starts at 100 and subtracts documented penalties (see the bottom of
 any report). It is meant for comparing runs of the same repo over time, not
 for comparing repos to each other.
 
+Two things deliberately do not score, because a score should measure what the
+current state of the code controls:
+
+- **PR hygiene is a nudge, not a penalty.** It reads commit history on `main`,
+  which cannot be fixed retroactively and corrects itself as PR-tagged commits
+  land. Section 12 requires a PR on a client repo; on your own repo it is your
+  call, and the audit is not the place to argue about it.
+- **The test penalty is a share, not a count.** Decomposing one oversized
+  component into ten presentational children is exactly what section 1 asks
+  for, and it triples the denominator. Scoring the count would mean the score
+  got worse for doing the right thing.
+
 ## In CI
 
 ```sh
@@ -52,6 +89,30 @@ file-wide disables, more files without tests, or a lower score. `--fail-on
 error` fails on any failed gate or `legion/*` error regardless of baseline;
 `--fail-on never` always exits 0.
 
+## Nudges
+
+Every run ends with the nudges: what this repo could do better, why it
+matters, and the command to do it. They are advisory. They never change the
+score and never change the exit code, because advice that can fail your build
+is not advice.
+
+```
+legion-audit: score 71/100, all gates green
+
+TOOLCHAIN
+  This repo runs on npm. Legion repos run on Yarn Berry.
+    why  Berry writes a packageManager field into package.json, so
+         Corepack pins the exact Yarn every machine and every CI runner
+         uses.
+    fix  corepack enable
+    fix  yarn set version berry
+    fix  rm -rf node_modules package-lock.json
+    fix  yarn install
+```
+
+`legion-audit advice` prints only that, skipping the slow gates. The nudges
+also land in `AUDIT.md` under `## Nudges` and in the JSON as `advice`.
+
 ## `legion-audit directives`
 
 The fast subcommand: only the file-wide disable scan, exit 1 if any. A

package/dist/advice/index.d.ts

@@ -0,0 +1,12 @@
+import type { Advice, AuditResult, DirectivesResult, LintResult, DependencyResult, PrHygiene, RuleCoverage, TestCoverage } from '../types.js';
+export declare const topRuleAdvice: (lint: LintResult) => Advice[];
+export declare const testAdvice: (coverage: TestCoverage) => Advice | null;
+export declare const bypassAdvice: (directives: DirectivesResult) => Advice | null;
+export declare const ruleCoverageAdvice: (coverage: RuleCoverage) => Advice | null;
+export declare const dependencyAdvice: (dependencies: DependencyResult) => Advice | null;
+export declare const prAdvice: (hygiene: PrHygiene) => Advice | null;
+export declare const buildAdvice: (result: Omit<AuditResult, "schema" | "generatedAt" | "score" | "advice">) => Advice[];
+export { RULE_LESSONS } from './lessons.js';
+export { yarnMigrationSteps, toolchainAdvice, TARGET_YARN, } from './toolchain.js';
+export type { Lesson } from './lessons.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/advice/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/advice/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,MAAM,EACN,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,YAAY,EACb,MAAM,aAAa,CAAC;AAiBrB,eAAO,MAAM,aAAa,GAAI,MAAM,UAAU,KAAG,MAAM,EAoBtD,CAAC;AAWF,eAAO,MAAM,UAAU,GAAI,UAAU,YAAY,KAAG,MAAM,GAAG,IAuB5D,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,YAAY,gBAAgB,KAAG,MAAM,GAAG,IAcpE,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAAI,UAAU,YAAY,KAAG,MAAM,GAAG,IAiBpE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,cAAc,gBAAgB,KAC7B,MAAM,GAAG,IAeX,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,SAAS,SAAS,KAAG,MAAM,GAAG,IAetD,CAAC;AAEF,eAAO,MAAM,WAAW,GACtB,QAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC,KACvE,MAAM,EAqBR,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC"}

package/dist/advice/index.js

@@ -0,0 +1,151 @@
+import { RULE_LESSONS } from './lessons.js';
+import { toolchainAdvice } from './toolchain.js';
+import { forgeFix, forgeLabel } from '../checks/forge.js';
+const MAX_DETAIL = 6;
+const MEMO_RULES = new Set(['legion/no-manual-memo']);
+const manualMemoCount = (lint) => lint.rules
+    .filter((rule) => MEMO_RULES.has(rule.rule))
+    .reduce((total, rule) => total + rule.errors + rule.warnings, 0);
+const TOP_RULES = 3;
+const withOverflow = (lines, total) => {
+    if (total <= lines.length)
+        return lines;
+    return [...lines, `...and ${total - lines.length} more`];
+};
+export const topRuleAdvice = (lint) => {
+    const ranked = lint.rules
+        .filter((rule) => RULE_LESSONS[rule.rule] !== undefined)
+        .filter((rule) => rule.errors + rule.warnings > 0)
+        .slice(0, TOP_RULES);
+    return ranked.map((rule) => {
+        const lesson = RULE_LESSONS[rule.rule];
+        const hits = lint.legion
+            .concat(lint.componentCap)
+            .filter((finding) => finding.rule === rule.rule);
+        const files = [...new Set(hits.map((finding) => finding.file))];
+        return {
+            id: `rule:${rule.rule}`,
+            area: 'rules',
+            title: `${rule.rule} fires ${rule.errors + rule.warnings} time(s).`,
+            why: lesson.why,
+            fix: lesson.fix,
+            detail: withOverflow(files.slice(0, MAX_DETAIL), files.length),
+        };
+    });
+};
+const COVERAGE_WORDING = {
+    'coverage-report': 'Measured from your coverage report, so this is what the tests actually execute.',
+    references: 'Inferred from what your test files import and describe, so a batch file covering many components counts for all of them.',
+    filenames: 'Inferred from filenames only. Run the tests with coverage once and this becomes a measurement instead of a guess.',
+};
+export const testAdvice = (coverage) => {
+    if (coverage.missing.length === 0)
+        return null;
+    const components = coverage.missing.filter((entry) => entry.kind === 'component').length;
+    const hooks = coverage.missing.length - components;
+    const files = coverage.missing.map((entry) => entry.file);
+    const detail = [
+        COVERAGE_WORDING[coverage.source],
+        ...withOverflow(files.slice(0, MAX_DETAIL), files.length),
+    ];
+    return {
+        id: 'missing-tests',
+        area: 'tests',
+        title: `${components} component(s) and ${hooks} hook(s) are not covered by a test.`,
+        why: 'Section 8: a feature without tests is incomplete. The hooks are the cheap ones to start with, because a view-model hook is a plain function that takes props and returns an object.',
+        fix: [
+            'hooks: call it with props and assert the returned object',
+            'components: Testing Library with the hook mocked',
+            'one file per component is not required; group them however reads best',
+        ],
+        detail,
+    };
+};
+export const bypassAdvice = (directives) => {
+    if (directives.fileWide.length === 0)
+        return null;
+    const lesson = RULE_LESSONS['legion/scoped-disables'];
+    const files = directives.fileWide.map((hit) => `${hit.file}:${hit.line}`);
+    return {
+        id: 'file-wide-disables',
+        area: 'bypasses',
+        title: `${directives.fileWide.length} file-wide lint disable(s).`,
+        why: lesson.why,
+        fix: lesson.fix,
+        detail: withOverflow(files.slice(0, MAX_DETAIL), files.length),
+    };
+};
+const PR_HYGIENE_FLOOR = 0.2;
+export const ruleCoverageAdvice = (coverage) => {
+    if (coverage.status !== 'checked')
+        return null;
+    if (coverage.unconfigured.length === 0)
+        return null;
+    return {
+        id: 'unconfigured-rules',
+        area: 'toolchain',
+        title: `${coverage.configured.length} of ${coverage.available.length} Legion rules are configured.`,
+        why: 'A config that names every rule by hand stops receiving them. The rules added since this config was written sit at 0, nothing reports that, and the repo quietly drifts from the standard it thinks it is holding. A preset picks up new rules on upgrade; an explicit list never does.',
+        fix: [
+            'oxlint: "jsPlugins": ["legion-toolkit/eslint-plugin"] plus the recommended preset',
+            'eslint: spread plugin.configs.recommended, then override only what differs',
+        ],
+        detail: withOverflow(coverage.unconfigured.slice(0, MAX_DETAIL), coverage.unconfigured.length),
+    };
+};
+export const dependencyAdvice = (dependencies) => {
+    if (dependencies.forbidden.length === 0)
+        return null;
+    const names = dependencies.forbidden.map((entry) => entry.name).join(', ');
+    return {
+        id: 'forbidden-dependencies',
+        area: 'toolchain',
+        title: `${dependencies.forbidden.length} dependency choice(s) section 9 rules out: ${names}.`,
+        why: 'Section 10 lists adding a state library to a simple app under automatic rejection, and section 7 replaces runtime CSS-in-JS with tokens. Nothing was checking either, so the rule lived only in the document.',
+        fix: dependencies.forbidden.map((entry) => `${entry.name}: use ${entry.instead}`),
+        detail: dependencies.forbidden.map((entry) => `${entry.name}@${entry.version} — ${entry.reason}`),
+    };
+};
+export const prAdvice = (hygiene) => {
+    if (hygiene.status === 'skipped')
+        return null;
+    if (hygiene.ratio >= PR_HYGIENE_FLOOR)
+        return null;
+    const direct = hygiene.inspected - hygiene.withPr;
+    return {
+        id: 'pr-hygiene',
+        area: 'process',
+        title: `${direct} of the last ${hygiene.inspected} commits landed straight on the branch (${forgeLabel(hygiene.forge)}).`,
+        why: 'Not a problem by itself, and it does not affect the score. Section 12 only requires a PR on a client repo, where nothing reaches main without review. On your own repo it is your call, so the thing to check is that the commit messages carry what a PR description would have said, because they are then the only record.',
+        fix: [
+            `client repo: ${forgeFix(hygiene.forge).join(', ')}, and never merge it yourself`,
+            'own repo: nothing to change, as long as the commit message says why',
+        ],
+        detail: [],
+    };
+};
+export const buildAdvice = (result) => {
+    const entries = [
+        ...toolchainAdvice(result.toolchain, result.lockfile, result.expo, manualMemoCount(result.lint)),
+        ...topRuleAdvice(result.lint),
+    ];
+    const tests = testAdvice(result.testCoverage);
+    if (tests)
+        entries.push(tests);
+    const bypasses = bypassAdvice(result.directives);
+    if (bypasses)
+        entries.push(bypasses);
+    const coverage = ruleCoverageAdvice(result.ruleCoverage);
+    if (coverage)
+        entries.push(coverage);
+    const deps = dependencyAdvice(result.dependencies);
+    if (deps)
+        entries.push(deps);
+    const process = prAdvice(result.prHygiene);
+    if (process)
+        entries.push(process);
+    return entries;
+};
+export { RULE_LESSONS } from './lessons.js';
+export { yarnMigrationSteps, toolchainAdvice, TARGET_YARN, } from './toolchain.js';
+//# sourceMappingURL=index.js.map

package/dist/advice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/advice/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAY1D,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC;AAEtD,MAAM,eAAe,GAAG,CAAC,IAAgB,EAAU,EAAE,CACnD,IAAI,CAAC,KAAK;KACP,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KAC3C,MAAM,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AACrE,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB,MAAM,YAAY,GAAG,CAAC,KAAe,EAAE,KAAa,EAAY,EAAE;IAChE,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,GAAG,KAAK,EAAE,UAAU,KAAK,GAAG,KAAK,CAAC,MAAM,OAAO,CAAC,CAAC;AAC3D,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAgB,EAAY,EAAE;IAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK;SACtB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;SACvD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;SACjD,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACzB,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAkC,CAAC;QACxE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM;aACrB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;aACzB,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChE,OAAO;YACL,EAAE,EAAE,QAAQ,IAAI,CAAC,IAAI,EAAE;YACvB,IAAI,EAAE,OAAgB;YACtB,KAAK,EAAE,GAAG,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,WAAW;YACnE,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC;SAC/D,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAA2C;IAC/D,iBAAiB,EACf,iFAAiF;IACnF,UAAU,EACR,0HAA0H;IAC5H,SAAS,EACP,mHAAmH;CACtH,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAsB,EAAiB,EAAE;IAClE,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CACxC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW,CACtC,CAAC,MAAM,CAAC;IACT,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC;IACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG;QACb,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC;QACjC,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC;KAC1D,CAAC;IACF,OAAO;QACL,EAAE,EAAE,eAAe;QACnB,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,GAAG,UAAU,qBAAqB,KAAK,qCAAqC;QACnF,GAAG,EAAE,qLAAqL;QAC1L,GAAG,EAAE;YACH,0DAA0D;YAC1D,kDAAkD;YAClD,uEAAuE;SACxE;QACD,MAAM;KACP,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAA4B,EAAiB,EAAE;IAC1E,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,MAAM,GAAG,YAAY,CACzB,wBAAwB,CACQ,CAAC;IACnC,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,OAAO;QACL,EAAE,EAAE,oBAAoB;QACxB,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,MAAM,6BAA6B;QACjE,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC;KAC/D,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAsB,EAAiB,EAAE;IAC1E,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO;QACL,EAAE,EAAE,oBAAoB;QACxB,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,OAAO,QAAQ,CAAC,SAAS,CAAC,MAAM,+BAA+B;QACnG,GAAG,EAAE,wRAAwR;QAC7R,GAAG,EAAE;YACH,mFAAmF;YACnF,4EAA4E;SAC7E;QACD,MAAM,EAAE,YAAY,CAClB,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EAC1C,QAAQ,CAAC,YAAY,CAAC,MAAM,CAC7B;KACF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,YAA8B,EACf,EAAE;IACjB,IAAI,YAAY,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO;QACL,EAAE,EAAE,wBAAwB;QAC5B,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,8CAA8C,KAAK,GAAG;QAC7F,GAAG,EAAE,+MAA+M;QACpN,GAAG,EAAE,YAAY,CAAC,SAAS,CAAC,GAAG,CAC7B,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,OAAO,EAAE,CACjD;QACD,MAAM,EAAE,YAAY,CAAC,SAAS,CAAC,GAAG,CAChC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,MAAM,KAAK,CAAC,MAAM,EAAE,CAC9D;KACF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAkB,EAAiB,EAAE;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,OAAO,CAAC,KAAK,IAAI,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAClD,OAAO;QACL,EAAE,EAAE,YAAY;QAChB,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,GAAG,MAAM,gBAAgB,OAAO,CAAC,SAAS,2CAA2C,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI;QACzH,GAAG,EAAE,+TAA+T;QACpU,GAAG,EAAE;YACH,gBAAgB,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,+BAA+B;YACjF,qEAAqE;SACtE;QACD,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,MAAwE,EAC9D,EAAE;IACZ,MAAM,OAAO,GAAa;QACxB,GAAG,eAAe,CAChB,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,IAAI,EACX,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAC7B;QACD,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC;KAC9B,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC9C,IAAI,KAAK;QAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACnD,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,WAAW,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/advice/lessons.d.ts

@@ -0,0 +1,6 @@
+export interface Lesson {
+    why: string;
+    fix: string[];
+}
+export declare const RULE_LESSONS: Record<string, Lesson>;
+//# sourceMappingURL=lessons.d.ts.map

package/dist/advice/lessons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.d.ts","sourceRoot":"","sources":["../../src/advice/lessons.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4F/C,CAAC"}

package/dist/advice/lessons.js

@@ -0,0 +1,94 @@
+export const RULE_LESSONS = {
+    'legion/no-function-keyword': {
+        why: 'A default export written as `export default function App` loses its name in React DevTools and in stack traces, so a crash report points at Anonymous. Arrow consts also hoist the way you expect instead of silently working before their definition.',
+        fix: ['const App = () => { ... };', 'export default App;'],
+    },
+    'legion/presentational-components': {
+        why: 'A component that holds state, effects or a handler body cannot be rendered in a test without also standing up everything it fetches. Moving the logic into use<Component> gives you a plain function to unit test and a component that is only markup.',
+        fix: [
+            'create lib/hooks/use<Component>.ts',
+            'move the state, effects and handlers into it',
+            'return a flat object of values and handleX functions',
+            'the component becomes: call the hook, early return, render children',
+        ],
+    },
+    'legion/no-literal-conditions-in-jsx': {
+        why: 'A comparison in the markup is a business rule hidden where nobody greps for it. When the rule changes you have to find every JSX file that encoded it, and you will miss one.',
+        fix: [
+            'derive the flag in the hook: const showBanner = status === "expired";',
+            'render with the flag: {showBanner && <Banner />}',
+        ],
+    },
+    'legion/no-narrative-comments': {
+        why: 'Comments drift. The code changes, the comment does not, and now the file actively lies to the next reader. Names and small functions cannot drift because they are the thing being executed.',
+        fix: [
+            'delete the comment',
+            'if it explained what, rename until the name says it',
+            'if it explained why, that belongs in the PR description',
+        ],
+    },
+    'legion/no-react-fc': {
+        why: 'React.FC adds an implicit children prop to components that do not take children, and it gets in the way of generics. A plain typed props parameter says exactly what the component accepts.',
+        fix: ['const Card = ({ title }: CardProps) => { ... }'],
+    },
+    'legion/no-enum': {
+        why: 'A TypeScript enum emits a runtime object, so it survives into the bundle and is not erasable. A string-literal union is compile-time only and narrows better.',
+        fix: ["type Status = 'idle' | 'loading' | 'done';"],
+    },
+    'legion/guarded-context-hook': {
+        why: 'A raw useContext returns undefined outside its provider, so the failure surfaces later as a property access on undefined, somewhere unrelated. A guarded hook fails at the call site with the provider name in the message.',
+        fix: [
+            'export const useAppContext = () => {',
+            '  const ctx = useContext(AppContext);',
+            '  if (!ctx) throw new Error("useAppContext must be used within AppProvider");',
+            '  return ctx;',
+            '};',
+        ],
+    },
+    'legion/no-client-globals-in-state-init': {
+        why: 'The server has no localStorage, so it renders one value and the browser hydrates with another. React throws away the server markup and you get a flash of the wrong content.',
+        fix: [
+            'initialize from a prop or a URL value',
+            'read the client-only preference in a useEffect and reconcile',
+        ],
+    },
+    'legion/no-use-client-in-page': {
+        why: 'A "use client" page ships the whole route to the browser and gives up server-side data fetching for it. The point of the app router is that the page fetches and only the interactive leaf is client.',
+        fix: [
+            'keep page.tsx a server component that fetches',
+            'move the interactivity into <Route>Client.tsx with the directive',
+            'pass the fetched data down as props',
+        ],
+    },
+    'legion/no-admin-client-in-browser': {
+        why: 'The service-role key bypasses row level security. Anything that reaches the browser or a device bundle can be read out of it, and then the key is not a secret any more.',
+        fix: [
+            'use the browser or server client here',
+            'keep admin queries behind a route handler or a server component',
+        ],
+    },
+    'legion/scoped-disables': {
+        why: 'A file-wide disable turns the rule off for every line in the file, including the code nobody has written yet. A scoped disable with a reason turns it off for exactly the line that needed it and tells the next reader why.',
+        fix: ['eslint-disable-next-line <rule> -- <the reason>'],
+    },
+    'legion/no-manual-memo': {
+        why: 'Under the React Compiler the memoization is automatic, so a hand-written useMemo is a dependency array to keep correct for no gain. A wrong dep array is a real bug; no dep array cannot be.',
+        fix: ['drop the useMemo and write the value directly'],
+    },
+    'no-ternary': {
+        why: 'Nested ternaries are where render logic goes to hide. A named flag reads as the rule it encodes, and a two-way branch is usually a child component or a Record lookup.',
+        fix: [
+            'default: value ?? fallback',
+            'render branch: {isReady && <Ready />} or an early return',
+            'two-way: a child component, or a Record keyed by the value',
+        ],
+    },
+    'max-lines': {
+        why: 'The cap is a symptom check, not the rule. A component over 180 lines has almost always absorbed logic that belongs in a hook, and the length is just how you noticed.',
+        fix: [
+            'move state, effects and handlers into use<Component>',
+            'extract each section of the markup into its own child component',
+        ],
+    },
+};
+//# sourceMappingURL=lessons.js.map

package/dist/advice/lessons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.js","sourceRoot":"","sources":["../../src/advice/lessons.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,4BAA4B,EAAE;QAC5B,GAAG,EAAE,wPAAwP;QAC7P,GAAG,EAAE,CAAC,4BAA4B,EAAE,qBAAqB,CAAC;KAC3D;IACD,kCAAkC,EAAE;QAClC,GAAG,EAAE,wPAAwP;QAC7P,GAAG,EAAE;YACH,oCAAoC;YACpC,8CAA8C;YAC9C,sDAAsD;YACtD,qEAAqE;SACtE;KACF;IACD,qCAAqC,EAAE;QACrC,GAAG,EAAE,+KAA+K;QACpL,GAAG,EAAE;YACH,uEAAuE;YACvE,kDAAkD;SACnD;KACF;IACD,8BAA8B,EAAE;QAC9B,GAAG,EAAE,8LAA8L;QACnM,GAAG,EAAE;YACH,oBAAoB;YACpB,qDAAqD;YACrD,yDAAyD;SAC1D;KACF;IACD,oBAAoB,EAAE;QACpB,GAAG,EAAE,6LAA6L;QAClM,GAAG,EAAE,CAAC,gDAAgD,CAAC;KACxD;IACD,gBAAgB,EAAE;QAChB,GAAG,EAAE,+JAA+J;QACpK,GAAG,EAAE,CAAC,4CAA4C,CAAC;KACpD;IACD,6BAA6B,EAAE;QAC7B,GAAG,EAAE,6NAA6N;QAClO,GAAG,EAAE;YACH,sCAAsC;YACtC,uCAAuC;YACvC,+EAA+E;YAC/E,eAAe;YACf,IAAI;SACL;KACF;IACD,wCAAwC,EAAE;QACxC,GAAG,EAAE,8KAA8K;QACnL,GAAG,EAAE;YACH,uCAAuC;YACvC,8DAA8D;SAC/D;KACF;IACD,8BAA8B,EAAE;QAC9B,GAAG,EAAE,uMAAuM;QAC5M,GAAG,EAAE;YACH,+CAA+C;YAC/C,kEAAkE;YAClE,qCAAqC;SACtC;KACF;IACD,mCAAmC,EAAE;QACnC,GAAG,EAAE,0KAA0K;QAC/K,GAAG,EAAE;YACH,uCAAuC;YACvC,iEAAiE;SAClE;KACF;IACD,wBAAwB,EAAE;QACxB,GAAG,EAAE,8NAA8N;QACnO,GAAG,EAAE,CAAC,iDAAiD,CAAC;KACzD;IACD,uBAAuB,EAAE;QACvB,GAAG,EAAE,8LAA8L;QACnM,GAAG,EAAE,CAAC,+CAA+C,CAAC;KACvD;IACD,YAAY,EAAE;QACZ,GAAG,EAAE,wKAAwK;QAC7K,GAAG,EAAE;YACH,4BAA4B;YAC5B,0DAA0D;YAC1D,4DAA4D;SAC7D;KACF;IACD,WAAW,EAAE;QACX,GAAG,EAAE,uKAAuK;QAC5K,GAAG,EAAE;YACH,sDAAsD;YACtD,iEAAiE;SAClE;KACF;CACF,CAAC"}

package/dist/advice/toolchain.d.ts

@@ -0,0 +1,5 @@
+import type { Advice, ExpoDoctorResult, LockfileResult, Toolchain } from '../types.js';
+export declare const TARGET_YARN = "yarn@4.18.0";
+export declare const yarnMigrationSteps: (found: string[]) => string[];
+export declare const toolchainAdvice: (toolchain: Toolchain, lockfile: LockfileResult, expo: ExpoDoctorResult, memoFindings?: number) => Advice[];
+//# sourceMappingURL=toolchain.d.ts.map

package/dist/advice/toolchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain.d.ts","sourceRoot":"","sources":["../../src/advice/toolchain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,cAAc,EACd,SAAS,EACV,MAAM,aAAa,CAAC;AAGrB,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,KAAG,MAAM,EAQ1D,CAAC;AAuNF,eAAO,MAAM,eAAe,GAC1B,WAAW,SAAS,EACpB,UAAU,cAAc,EACxB,MAAM,gBAAgB,EACtB,qBAAgB,KACf,MAAM,EAgBR,CAAC"}