rip-lang 3.16.0 → 3.16.1

package/src/typecheck.js

@@ -12,11 +12,11 @@
 
 import { Compiler, getStdlibCode } from './compiler.js';
 import { STDLIB_TYPE_DECLS } from './stdlib.js';
-import { INTRINSIC_TYPE_DECLS, INTRINSIC_FN_DECL, ARIA_TYPE_DECLS, SIGNAL_INTERFACE, SIGNAL_FN, COMPUTED_INTERFACE, COMPUTED_FN, EFFECT_FN } from './dts.js';
+import { INTRINSIC_TYPE_DECLS, INTRINSIC_FN_DECL, ARIA_TYPE_DECLS, SIGNAL_INTERFACE, SIGNAL_FN, COMPUTED_INTERFACE, COMPUTED_FN, EFFECT_FN, ripDestructuredNames } from './dts.js';
 import './schema/loader-server.js';   // registers full schema runtime provider
 import { createRequire } from 'module';
 import { readFileSync, existsSync, readdirSync } from 'fs';
-import { resolve, relative, dirname, sep as pathSep } from 'path';
+import { resolve, relative, dirname, basename, sep as pathSep } from 'path';
 import { buildLineMap } from './sourcemaps.js';
 
 // ── Typed stash: project entry discovery ───────────────────────────
@@ -29,12 +29,60 @@ import { buildLineMap } from './sourcemaps.js';
 // `import('<rel-to-stash>').__RipStash` into their `app.data` declaration.
 //
 // Discovery: walk up from each file to the nearest dir that contains an
-// `index.rip` AND a `rip.json` or `package.json` (the project anchor),
-// then look for `<root>/app/stash.rip`. Cached per-directory for the
-// process lifetime.
+// `index.rip` AND a `package.json` (the project anchor), then look for
+// `<root>/app/stash.rip`. Cached per-directory for the process lifetime.
 const entryFileCache = new Map(); // dir → entryFile|null
 const stashFileCache = new Map(); // root dir → stashFile|null
 
+// ── Robust import extraction ───────────────────────────────────────
+//
+// Walk a file's `import ...` / dynamic `import(...)` specifiers via Bun's
+// real parser instead of regex-scanning. This is immune to false matches
+// from comments, string literals, regex bodies, and any other place a
+// `from "@rip-lang/..."`-shaped sequence might appear in source.
+//
+// `scanText` is the compiled TS-virtual content (entry.tsContent) when
+// available; we fall back to the raw .rip source for entries that
+// haven't been compiled yet (the only such call site reads a freshly-
+// read package file).
+const _ripImportTranspiler = new Bun.Transpiler({ loader: 'ts' });
+function scanRipPkgImports(scanText) {
+  if (!scanText) return [];
+  let imports;
+  try { imports = _ripImportTranspiler.scanImports(scanText); }
+  catch { return []; }
+  const out = [];
+  for (const imp of imports) {
+    const p = imp.path;
+    if (typeof p === 'string' && p.startsWith('@rip-lang/')) out.push(p);
+  }
+  return out;
+}
+// Type-position `import('@rip-lang/...')` import-types are erased by
+// `scanImports` (they live in type space), so the parser-based scan above
+// never sees them. The DTS pipeline injects exactly these — e.g.
+// `declare router: import('@rip-lang/app').Router` and the `NavOpts` alias
+// — so the referenced package must still be pulled into the TS
+// program or its types silently resolve to `any` (e.g. `push`'s `opts`
+// going unchecked). Used ONLY for package seeding, never the
+// undeclared-import check: these are synthesized references, not source
+// dependencies the user must declare in package.json.
+const _ripImportTypeRe = /\bimport\(\s*(["'])(@rip-lang\/[^"']+)\1\s*\)/g;
+function scanRipPkgImportTypes(scanText) {
+  if (!scanText) return [];
+  const out = [];
+  _ripImportTypeRe.lastIndex = 0;
+  let m;
+  while ((m = _ripImportTypeRe.exec(scanText))) out.push(m[2]);
+  return out;
+}
+// Extract the bare package name (`@rip-lang/foo`) from a specifier
+// that may include a subpath (`@rip-lang/foo/sub/path`).
+function ripPkgRoot(spec) {
+  const i = spec.indexOf('/', '@rip-lang/'.length);
+  return i === -1 ? spec : spec.slice(0, i);
+}
+
 export function findEntryFile(filePath) {
   let dir = dirname(filePath);
   const visited = [];
@@ -45,7 +93,7 @@ export function findEntryFile(filePath) {
       return cached;
     }
     visited.push(dir);
-    const hasAnchor = existsSync(resolve(dir, 'rip.json')) || existsSync(resolve(dir, 'package.json'));
+    const hasAnchor = existsSync(resolve(dir, 'package.json'));
     if (hasAnchor) {
       const entry = resolve(dir, 'index.rip');
       const result = existsSync(entry) ? entry : null;
@@ -84,6 +132,129 @@ export function findStashFile(filePath) {
   return result;
 }
 
+// ── Route tree discovery ───────────────────────────────────────────
+//
+// The project's routes live under `<projectRoot>/app/routes/` — a fixed
+// convention (not configurable) that matches `@rip-lang/server`'s
+// `serve dir: "<root>/app"`, which mounts route files under `app/routes/`.
+// Each `.rip` file there contributes one entry to a
+// generated `__RipRoutes` template-literal union, used for typed
+// `<a href: "...">`, typed `router.push`, and per-route `@params`
+// tightening. Mirrors the runtime rules in `buildRoutes`
+// (packages/app/index.rip): skip `_-prefixed` files, skip files
+// inside `_-prefixed` directories, treat `index.rip` as `/`,
+// `[id]` as a dynamic segment, `[...rest]` as catch-all.
+const routesDirCache  = new Map(); // entryDir → absoluteRoutesDir|null
+const routesTreeCache = new Map(); // routesDir → { entries, union }
+
+// Invalidate the route-tree cache for the project containing `filePath`,
+// or all projects when no path is given. Called by the LSP whenever a
+// `.rip` file is added/removed/renamed so completions, hover, and
+// diagnostics see the new route shape without a process restart.
+export function invalidateRoutesCache(filePath) {
+  if (!filePath) {
+    routesDirCache.clear();
+    routesTreeCache.clear();
+    return;
+  }
+  // Cheap and correct: drop both caches. Reads are O(routes-dir scan),
+  // and the caches refill on the next access. Pin-pointing the exact
+  // entryDir would require re-running findEntryFile, which itself
+  // caches; clearing wholesale avoids the dependency.
+  routesDirCache.clear();
+  routesTreeCache.clear();
+}
+
+export function findRoutesDir(filePath) {
+  const entryFile = findEntryFile(filePath);
+  if (!entryFile) return null;
+  const root = dirname(entryFile);
+  if (routesDirCache.has(root)) return routesDirCache.get(root);
+  // Convention: `app/routes/`. Matches `@rip-lang/server`'s `serve dir:
+  // "<root>/app"` pattern, which resolves routes under `app/routes/`.
+  const dir = resolve(root, 'app/routes');
+  const result = existsSync(dir) ? dir : null;
+  routesDirCache.set(root, result);
+  return result;
+}
+
+// Build per-route metadata and the `__RipRoutes` template-literal union.
+// Each entry: { rel, file, pattern (TS expression), dynamic: [{name, catchAll}] }
+export function walkRoutesDir(routesDir) {
+  if (!routesDir) return { entries: [], union: 'never' };
+  if (routesTreeCache.has(routesDir)) return routesTreeCache.get(routesDir);
+  const entries = [];
+  function walk(dir, segs) {
+    let dirents;
+    try { dirents = readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of dirents) {
+      // Skip _-prefixed files (_layout.rip etc.) and dirs (shared
+      // helpers, not pages). Same rule as runtime buildRoutes.
+      if (e.name.startsWith('_')) continue;
+      if (e.isDirectory()) walk(resolve(dir, e.name), [...segs, e.name]);
+      else if (e.isFile() && e.name.endsWith('.rip')) {
+        const base = e.name.slice(0, -'.rip'.length);
+        const fileSegs = base === 'index' ? segs : [...segs, base];
+        const dynamic = [];
+        const displaySegs = [];
+        const tsSegs = fileSegs.map(s => {
+          let m = s.match(/^\[\.\.\.(\w+)\]$/);
+          if (m) { dynamic.push({ name: m[1], catchAll: true }); displaySegs.push('$' + m[1]); return '${string}'; }
+          m = s.match(/^\[(\w+)\]$/);
+          if (m) { dynamic.push({ name: m[1], catchAll: false }); displaySegs.push('$' + m[1]); return '${string}'; }
+          displaySegs.push(s);
+          return s;
+        });
+        const path = '/' + tsSegs.join('/');
+        const displayPath = '/' + displaySegs.join('/');
+        const pattern = dynamic.length === 0
+          ? JSON.stringify(path === '//' ? '/' : path)
+          : '`' + (path === '//' ? '/' : path) + '`';
+        const display = dynamic.length === 0
+          ? null
+          : '`' + (displayPath === '//' ? '/' : displayPath) + '`';
+        entries.push({
+          rel: relative(routesDir, resolve(dir, e.name)),
+          file: resolve(dir, e.name),
+          pattern,
+          display,
+          displayPath,
+          dynamic,
+        });
+      }
+    }
+  }
+  walk(routesDir, []);
+  // Canonical order: index route ("/") first, then the rest by display
+  // path, lexicographically. Filesystem walk order is undefined across
+  // platforms — sorting here gives stable union order and a consistent
+  // member sequence in completions, hovers, and error messages.
+  entries.sort((a, b) => {
+    if (a.displayPath === '/') return -1;
+    if (b.displayPath === '/') return 1;
+    return a.displayPath < b.displayPath ? -1 : a.displayPath > b.displayPath ? 1 : 0;
+  });
+  // Build union, deduping static patterns (template-literal patterns
+  // are inherently distinct by structure). Catch-all routes
+  // (`[...rest].rip`) are excluded — they're runtime 404 fallbacks,
+  // not navigation targets, and including them as `/${string}` would
+  // make the union accept any slash-prefixed string and defeat
+  // typo-catching for every other route.
+  const seen = new Set();
+  const parts = [];
+  for (const e of entries) {
+    if (e.dynamic.some(d => d.catchAll)) continue;
+    if (seen.has(e.pattern)) continue;
+    seen.add(e.pattern);
+    parts.push(e.pattern);
+  }
+  const union = parts.length ? parts.join(' | ') : 'never';
+  const result = { entries, union };
+  routesTreeCache.set(routesDir, result);
+  return result;
+}
+
 // ── Shared helpers ─────────────────────────────────────────────────
 
 // Detect type annotations (:: followed by space or =) ignoring comments,
@@ -219,12 +390,12 @@ export function checkComponentDefs(compProps, srcLines, startLine = 0) {
   const errors = [];
   for (const prop of compProps) {
     for (let s = startLine; s < srcLines.length; s++) {
-      const m = new RegExp('(@' + prop.name + ')\\s*(::|([:!]?=))').exec(srcLines[s]);
+      const m = new RegExp('(@' + prop.name + ')\\??\\s*(::|([:!]?=))').exec(srcLines[s]);
       if (!m) continue;
       if (m[1 + 1] !== '::') {
         errors.push({ line: s, col: m.index, len: m[1].length, propName: prop.name, message: `Prop '${prop.name}' has no type annotation` });
       } else {
-        const dm = srcLines[s].match(new RegExp('@' + prop.name + '\\s*::\\s*(.+?)\\s*:=\\s*(.+)'));
+        const dm = srcLines[s].match(new RegExp('@' + prop.name + '\\??\\s*::\\s*(.+?)\\s*:=\\s*(.+)'));
         if (dm) {
           const defVal = dm[2].replace(/#.*$/, '').trim();
           const err = validatePropDefault(dm[1].trim(), defVal);
@@ -419,19 +590,30 @@ export const SKIP_CODES = new Set([
   1064, // Return type of async function must be Promise
 ]);
 
-// Dedup diagnostics by (start line/col, end line/col, code, message).
+// Dedup diagnostics by (start line/col, code).
 // The same TS error can fire twice when the dts header and compiled body
 // both contain the offending construct (e.g. an `import { X }` line that
-// maps to the same source position from both copies).
+// maps to the same source position from both copies), or when a diagnostic
+// hits both an injected function overload signature and its implementation.
+//
+// The key intentionally excludes end position and message: the duplicates we
+// want to collapse routinely differ in span length (overload sig vs impl
+// token widths) and occasionally in message text (TS referencing different
+// candidate signatures). Same start position + same code is the right
+// invariant — distinct logical errors at the exact same (line, col, code)
+// would be vanishingly rare and folding them is preferable to leaking
+// structural duplicates.
 //
 // `getRange(d)` must return `{ startLine, startCol, endLine, endCol }`.
-// Returns a new array; does not mutate the input.
+// Returns a new array; does not mutate the input. Preserves input object
+// identity so callers can use Set membership to find which entries were
+// dropped.
 export function dedupDiagnostics(diags, getRange) {
   const seen = new Set();
   const out = [];
   for (const d of diags) {
     const r = getRange(d);
-    const key = `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}:${d.code}:${d.message}`;
+    const key = `${r.startLine}:${r.startCol}:${d.code}`;
     if (seen.has(key)) continue;
     seen.add(key);
     out.push(d);
@@ -605,6 +787,116 @@ export function cleanDiagnosticMessage(msg) {
   return msg;
 }
 
+// Classify a route-related diagnostic so the message rewrite and the
+// squiggle-snap use one consistent detection. Returns:
+//   'el'    — anchor href mismatch (static __ripEl or dynamic __ripRoute)
+//   'route' — programmatic router.push/replace mismatch
+//   null    — unrelated diagnostic
+//
+// Detection is position-aware: a single source line can host both an anchor
+// and an inline event handler (e.g. `a @click: () -> @router.push(...)`),
+// so substring-checking the whole TS line is ambiguous. Instead we look at
+// the call site immediately preceding the diagnostic's TS offset.
+function classifyRouteDiagnostic(entry, start) {
+  if (!entry?.tsContent || start == null) return null;
+  const before = entry.tsContent.slice(Math.max(0, start - 64), start);
+  if (/(?:__ripEl|__ripRoute)\([^()]*$/.test(before)) return 'el';
+  if (/\.(?:push|replace)\([^()]*$/.test(before)) return 'route';
+  return null;
+}
+
+// Unify route diagnostics with the static __ripEl form so users see one
+// consistent message shape regardless of which call site (anchor href,
+// router.push, etc.) produced the error. Rewrites TS2345 "Argument of
+// type 'X' is not assignable to parameter of type 'Y'." into TS2322
+// "Type 'X' is not assignable to type 'Y | undefined'." Then prettifies
+// `${string}` placeholders in route patterns to their source-form
+// `$paramName` (from `[id].rip` → `$id`). Used by both the CLI
+// (runCheck) and the LSP diagnostic publisher.
+export function unifyRouteDiagnostic(code, message, entry, start, filePath) {
+  const kind = classifyRouteDiagnostic(entry, start);
+  const routesDir = filePath ? findRoutesDir(filePath) : null;
+  const tree = routesDir ? walkRoutesDir(routesDir) : null;
+
+  if ((kind === 'route' || kind === 'el') && code === 2345) {
+    const m = message.match(/^Argument of type '([^']*(?:''[^']*)*)' is not assignable to parameter of type '([^']*(?:''[^']*)*)'\.$/);
+    if (m) {
+      code = 2322;
+      message = `Type '${m[1]}' is not assignable to type '${m[2]} | undefined'.`;
+    }
+  }
+
+  // Prettify ${string} placeholders in known route patterns.
+  if (tree && message.includes('${string}')) {
+    message = prettifyRoutePatterns(message, tree);
+  }
+  // Canonicalize route-union member order (TS normalizes unions, so the
+  // order shifts between error contexts — pin to walkRoutesDir order).
+  if (tree) message = canonicalizeRouteUnion(message, tree);
+  return { code, message };
+}
+
+// Rewrite `${string}` placeholders in route patterns to their source-form
+// `$paramName` (from `[id].rip` → `$id`). Used by diagnostics and hover.
+export function prettifyRoutePatterns(text, tree) {
+  if (!tree || !text || !text.includes('${string}')) return text;
+  for (const e of tree.entries) {
+    if (!e.display) continue;
+    if (e.pattern !== e.display) text = text.split(e.pattern).join(e.display);
+  }
+  return text;
+}
+
+// Reorder route-union members to match walkRoutesDir order. TS normalizes
+// unions internally, so the same set can render in different orders across
+// hover and error contexts. Scans for runs of unioned string/template/
+// undefined members, and if the run exactly covers the known route set
+// (plus optional `undefined`), rewrites it in canonical order. Leaves
+// unrelated unions untouched.
+export function canonicalizeRouteUnion(text, tree) {
+  if (!tree || !text || !text.includes(' | ')) return text;
+  const canonical = [];
+  const seen = new Set();
+  for (const e of tree.entries) {
+    if (e.dynamic.some(d => d.catchAll)) continue;
+    const member = e.display || e.pattern;
+    if (seen.has(member)) continue;
+    seen.add(member);
+    canonical.push(member);
+  }
+  if (canonical.length === 0) return text;
+  const canonicalSet = new Set(canonical);
+  const memberRe = /(?:"[^"]*"|`[^`]*`|undefined)/.source;
+  const unionRe = new RegExp(`${memberRe}(?:\\s*\\|\\s*${memberRe})+`, 'g');
+  return text.replace(unionRe, run => {
+    const parts = run.split(/\s*\|\s*/);
+    const hasUndefined = parts.includes('undefined');
+    const nonUndef = parts.filter(p => p !== 'undefined');
+    if (nonUndef.length !== canonical.length) return run;
+    if (!nonUndef.every(p => canonicalSet.has(p))) return run;
+    const ordered = hasUndefined ? [...canonical, 'undefined'] : canonical;
+    return ordered.join(' | ');
+  });
+}
+
+// Locate the best span for a route diagnostic in the source line. TS
+// reports the span on the generated `__ripEl`/`__ripRoute` call, which
+// source-maps back to imprecise positions. We snap to the meaningful
+// token in the source:
+//   - 'el'    → the `href` attribute name
+//   - 'route' → the method name `push`/`replace`
+export function locateRouteDiagnosticSpan(entry, start, srcLine) {
+  const kind = classifyRouteDiagnostic(entry, start);
+  if (kind === 'el') {
+    const m = srcLine.match(/\bhref\b/);
+    if (m) return { col: m.index, len: 4 };
+  } else if (kind === 'route') {
+    const m = srcLine.match(/\.(push|replace)\b/);
+    if (m) return { col: m.index + 1, len: m[1].length };
+  }
+  return null;
+}
+
 // Base TypeScript compiler settings for type-checking. Callers can
 // pass overrides (e.g. { strict: true } when a project opts in).
 //
@@ -612,8 +904,8 @@ export function cleanDiagnosticMessage(msg) {
 // ("optional, design scaffolding, not safety rails") and matches the
 // gradual-typing default of comparable systems (Sorbet's `# typed: false`,
 // mypy's permissive default, Hack's `partial`, TypeScript's own pre-strict
-// default). Projects opt UP to strict via rip.json's `strict: true`, which
-// implies noImplicitAny, strictNullChecks, and the rest of TS's strict
+// default). Projects opt UP to strict via package.json's `rip.strict: true`,
+// which implies noImplicitAny, strictNullChecks, and the rest of TS's strict
 // family. Do NOT pin those flags to `false` here — that would shadow the
 // strict-family inference when an opt-in caller passes `{ strict: true }`.
 export function createTypeCheckSettings(ts, overrides = {}) {
@@ -629,6 +921,35 @@ export function createTypeCheckSettings(ts, overrides = {}) {
   };
 }
 
+// Collect ambient type packages (e.g. `@types/bun`, `@types/node`) by
+// walking up from rootPath gathering every `node_modules/@types` dir.
+// TS's default typeRoots only checks `<cwd>/node_modules/@types`, so a
+// sub-package check would miss workspace-root ambients. Accepts symlinks
+// because bun's nested-package layout symlinks `@types/bun` to
+// `.bun/@types+bun@.../node_modules/@types/bun`.
+export function collectAmbientTypes(rootPath) {
+  const typeRoots = [];
+  const types = [];
+  let dir = rootPath;
+  while (true) {
+    const cand = resolve(dir, 'node_modules/@types');
+    if (existsSync(cand)) {
+      typeRoots.push(cand);
+      try {
+        for (const entry of readdirSync(cand, { withFileTypes: true })) {
+          if ((entry.isDirectory() || entry.isSymbolicLink()) && !entry.name.startsWith('.') && !types.includes(entry.name)) {
+            types.push(entry.name);
+          }
+        }
+      } catch {}
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { typeRoots, types };
+}
+
 // ── Param helpers ──────────────────────────────────────────────────
 
 // Extract the text between the first balanced ( ) — handles nested parens
@@ -824,9 +1145,9 @@ function injectTypeParams(line, typeParams) {
 // Compile a .rip file for type-checking. Prepends DTS declarations to
 // compiled JS, detects type annotations, and builds bidirectional
 // source maps. Returns everything both the CLI and LSP need.
-// When opts.strict is true, all non-nocheck files are type-checked.
+// When opts.checkAll is true, all non-nocheck files are type-checked.
 export function compileForCheck(filePath, source, compiler, opts = {}) {
-  const result = compiler.compile(source, { sourceMap: true, types: 'emit', skipPreamble: true, stubComponents: true });
+  const result = compiler.compile(source, { sourceMap: true, types: 'emit', skipPreamble: true, stubComponents: true, inlineTypes: true });
   let code = result.code || '';
   const dts = result.dts ? result.dts.trimEnd() + '\n' : '';
 
@@ -838,7 +1159,7 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
   // that probe is a raw-source regex that fires on `schema :input` inside
   // heredoc string literals (e.g. test files), flooding the LSP with TS2304
   // false positives. Schema files still get their DTS via the schema pass.
-  const hasOwnTypes = !nocheck && (hasTypeAnnotations(source) || !!opts.strict);
+  const hasOwnTypes = !nocheck && (hasTypeAnnotations(source) || !!opts.checkAll);
   let importsTyped = false;
   if (!hasOwnTypes && !nocheck) {
     const ripImports = [...source.matchAll(/from\s+['"]([^'"]*\.rip)['"]/g)];
@@ -969,11 +1290,20 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
       // intended source. Strip the DTS line so it doesn't bleed into
       // the wrong scope; the locals fall back to per-binding inference.
       if (multipleLocals) { localTypedLetIdxs.add(dtsIdx); continue; }
-      // No local site found: this is genuinely a module-scope typed
-      // declaration (no function-local to hoist into). Leave the DTS
-      // line in place — it's the `let name: T;` declaration the body's
-      // top-level `name = value` needs to type-check.
-      if (localLine < 0) continue;
+      // No untyped local site found. Before assuming this is a
+      // module-scope decl, check for an *already-typed* function-local
+      // `let X: T` — the compiler emits the type inline on the body's
+      // hoisted `let` for typed locals, which makes `localPat`'s
+      // `(?!\s*:)` look-ahead skip the line. In that case the DTS
+      // header decl is redundant and would otherwise show up as a
+      // bogus "declared but never read" hint at the top of the file.
+      if (localLine < 0) {
+        const typedLocalPat = new RegExp(`^\\s+let\\s+[^;]*\\b${name}\\b\\s*:`);
+        for (let j = 0; j < cl.length; j++) {
+          if (typedLocalPat.test(cl[j])) { localTypedLetIdxs.add(dtsIdx); break; }
+        }
+        continue;
+      }
       // Single unambiguous match — perform the hoist.
       cl[localLine] = cl[localLine].replace(
         new RegExp(`(\\blet\\s[^;]*?\\b${name}\\b)(?!\\s*:)`),
@@ -1032,6 +1362,47 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
           return depth === 0 && sig.slice(i).includes(':');
         }
 
+        // Check if any parameter in a DTS signature lacks a type annotation.
+        // Used to suppress overload-sig injection: if a param is untyped, TS
+        // will fire TS7006 on both the injected sig and the impl (same source
+        // position, same code) — let it fire on the impl only.
+        //
+        // Each top-level param part is "typed" iff it contains a top-level `:`
+        // outside of any nested (), [], {}, or <> groups. Destructured-rename
+        // colons inside `{a: aliased}` don't count because they're nested.
+        // Empty param lists are trivially "all typed".
+        function hasUntypedParam(sig) {
+          const params = extractFnParams(sig);
+          if (params === null || params.trim() === '') return false;
+          const parts = splitTopLevelParams(params);
+          for (const part of parts) {
+            if (!part) continue;
+            // Skip TS `this: T` pseudo-param if it appears.
+            if (/^this\s*:/.test(part)) continue;
+            let depth = 0, angle = 0, hasColon = false;
+            for (let i = 0; i < part.length; i++) {
+              const c = part[i];
+              if (c === '"' || c === "'" || c === '`') {
+                // skip string literal
+                const q = c; i++;
+                while (i < part.length && part[i] !== q) {
+                  if (part[i] === '\\') i++;
+                  i++;
+                }
+                continue;
+              }
+              if (c === '(' || c === '[' || c === '{') { depth++; continue; }
+              if (c === ')' || c === ']' || c === '}') { depth--; continue; }
+              if (c === '=' && part[i + 1] === '>') { i++; continue; }
+              if (c === '<' && i > 0 && /[A-Za-z_$0-9>\]]/.test(part[i - 1])) { angle++; continue; }
+              if (c === '>' && angle > 0) { angle--; continue; }
+              if (c === ':' && depth === 0 && angle === 0) { hasColon = true; break; }
+            }
+            if (!hasColon) return true;
+          }
+          return false;
+        }
+
         // Extract the return type from a DTS signature (e.g. ": number" from
         // "function add(a: number, b: number): number;").
         function extractReturnType(sig) {
@@ -1081,10 +1452,13 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
           }
         }
 
-        // Only inject overload signatures for functions with explicit return types.
-        // Functions without a return type annotation let TS infer the return from
-        // the implementation body — injecting an overload would force it to `any`.
-        const overloads = injections.filter(inj => hasExplicitReturn(inj.sig));
+        // Only inject overload signatures for functions with explicit return types
+        // AND fully-typed params. Functions without a return type annotation let
+        // TS infer the return from the implementation body — injecting an overload
+        // would force it to `any`. Functions with any untyped param would fire
+        // TS7006 twice (once on the injected sig, once on the impl) at the same
+        // source position — skip the injection so the user sees a single error.
+        const overloads = injections.filter(inj => hasExplicitReturn(inj.sig) && !hasUntypedParam(inj.sig));
 
         // Adjust reverseMap: each overload injection shifts subsequent code lines down by 1.
         // Compare against the original genLine (not genLine + offset) because bottom-up
@@ -1162,7 +1536,7 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
             const existingFields = new Set();
             for (let k = j + 1; k < cl.length; k++) {
               if (cl[k].match(/^(?:export\s+)?(?:class|const)\s+\w+/) && k > j + 1) break;
-              const fm = cl[k].match(/^\s+(?:declare\s+)?(\w+):\s+.+;$/);
+              const fm = cl[k].match(/^\s+(?:declare\s+)?(\w+):\s+.+;(?:\s*\/\/.*)?$/);
               if (fm) existingFields.add(fm[1]);
               // Also match field assignments (e.g. `name = __computed(...)` in component stubs)
               const am = cl[k].match(/^\s+(\w+)\s*=\s+/);
@@ -1336,7 +1710,16 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
 
     for (let i = 0; i < dl.length; i++) {
       const m = dl[i].match(/^(?:export\s+)?declare\s+const\s+(\w+):\s+(.+);$/);
-      if (m) constTypes.set(m[1], { type: m[2], idx: i });
+      if (m) { constTypes.set(m[1], { type: m[2], idx: i }); continue; }
+      // Also merge `(export )?let X: T;` forward-decls from the DTS header
+      // into matching body `(export )?const X = expr` declarations. dts.js
+      // emits the `let` form for typed module-scope value bindings declared
+      // via `name:: T = expr`. Without this merge, TS sees two separate
+      // declarations (header `let` + body `const`) and loses the typed
+      // identity on property access — e.g. `getStore()` returns `unknown`
+      // instead of the declared `AsyncLocalStorage<T>`'s element type.
+      const lm = dl[i].match(/^(?:export\s+)?let\s+(\w+):\s+(.+);$/);
+      if (lm) constTypes.set(lm[1], { type: lm[2], idx: i });
     }
 
     if (constTypes.size > 0) {
@@ -1363,9 +1746,10 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
   // but files that import from typed modules may have untyped reactive vars whose
   // compiled code still references __state/__computed/__effect.
   if (hasTypes) {
-    const needSignal = /\b__state\(/.test(code) && !/\bdeclare function __state\b/.test(headerDts);
-    const needComputed = /\b__computed\(/.test(code) && !/\bdeclare function __computed\b/.test(headerDts);
-    const needEffect = /\b__effect\(/.test(code) && !/\bdeclare function __effect\b/.test(headerDts);
+    const bound = ripDestructuredNames(source);
+    const needSignal = /\b__state\(/.test(code) && !/\bdeclare function __state\b/.test(headerDts) && !bound.has('__state');
+    const needComputed = /\b__computed\(/.test(code) && !/\bdeclare function __computed\b/.test(headerDts) && !bound.has('__computed');
+    const needEffect = /\b__effect\(/.test(code) && !/\bdeclare function __effect\b/.test(headerDts) && !bound.has('__effect');
     if (needSignal || needComputed || needEffect) {
       const decls = [];
       if (needSignal) {
@@ -1492,22 +1876,37 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
     for (let i = 0; i < cl.length; i++) {
       const m = cl[i].match(/^(\s*)let\s+([A-Za-z_$][\w$]*(?:\s*,\s*[A-Za-z_$][\w$]*)*)\s*;\s*$/);
       if (!m) continue;
-      // Only process hoist-position lets (first non-blank line after `{` or start of file)
+      // Only process hoist-position lets (first non-blank line after `{`, start
+      // of file, or the module's import block — the compiler emits the
+      // module-scope hoist right after the imports).
       let prev = null;
       for (let k = i - 1; k >= 0; k--) { if (cl[k].trim() !== '') { prev = cl[k]; break; } }
-      if (prev !== null && !/\{\s*$/.test(prev)) continue;
+      if (prev !== null && !/\{\s*$/.test(prev) && !/^\s*import\b/.test(prev)) continue;
 
       const baseIndent = m[1];
       const vars = m[2].split(/\s*,\s*/);
       const inlined = new Set();
       const bailed = new Set();
-      const scopeEndRe = new RegExp('^' + reEsc(baseIndent) + '}');
+      // Scope-end detection by indent: the enclosing block ends at the first
+      // non-empty line whose indent is strictly less than baseIndent. This is
+      // correct for compiler-generated JS where indentation reliably reflects
+      // nesting. Regex-matching `}` at baseIndent was wrong because inner
+      // block-closing braces (e.g. `  }` ending a nested `if`) sit at exactly
+      // baseIndent and would terminate the scan prematurely. For top-level
+      // hoists (baseIndent === ''), the scope is the whole file — never end.
+      const baseIndentLen = baseIndent.length;
+      const isScopeEnd = (line) => {
+        if (baseIndentLen === 0) return false;
+        if (line.trim() === '') return false;
+        const li = line.match(/^(\s*)/)[1].length;
+        return li < baseIndentLen;
+      };
 
       // Phase 1: straight-line scan at base indent
       for (let j = i + 1; j < cl.length; j++) {
         const line = cl[j];
         if (line.trim() === '') continue;
-        if (scopeEndRe.test(line)) break;
+        if (isScopeEnd(line)) break;
         // Skip deeper-indented lines
         if (line.startsWith(baseIndent + '  ')) continue;
         // Stop at structural statements (if/for/while/switch/try/do/function/class)
@@ -1539,7 +1938,7 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
         for (let j = i + 1; j < cl.length; j++) {
           const line = cl[j];
           if (line.trim() === '') continue;
-          if (scopeEndRe.test(line)) break;
+          if (isScopeEnd(line)) break;
           if (!vRe.test(line)) continue;
           if (firstRefLine < 0) firstRefLine = j;
           if (!foundAssign) {
@@ -1560,7 +1959,7 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
         for (let j = foundAssign.line + 1; j < cl.length; j++) {
           const line = cl[j];
           if (line.trim() === '') continue;
-          if (scopeEndRe.test(line)) { blockEndLine = j; break; }
+          if (isScopeEnd(line)) { blockEndLine = j; break; }
           const li = line.match(/^(\s*)/)[1];
           if (li.length < foundAssign.indent.length) { blockEndLine = j; break; }
         }
@@ -1571,7 +1970,7 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
           for (let j = blockEndLine + 1; j < cl.length; j++) {
             const line = cl[j];
             if (line.trim() === '') continue;
-            if (scopeEndRe.test(line)) break;
+            if (isScopeEnd(line)) break;
             if (vRe.test(line)) { hasRefAfterBlock = true; break; }
           }
         }
@@ -1583,8 +1982,23 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
       }
 
       const remaining = vars.filter(v => !inlined.has(v));
-      if (remaining.length) cl[i] = `${baseIndent}let ${remaining.join(', ')};`;
-      else cl[i] = '';
+      // Module-scope only: drop any var that still has a DTS-header decl
+      // (`let name: T;`) from this untyped hoist. These are chiefly module-level
+      // function bindings, whose assignment spans multiple lines
+      // (`proxy = function(c) {` … `};`) and so never folds into a single
+      // `let name: T = value;` line. The header decl is the single,
+      // correctly-typed declaration and the body's later `name = …` assigns it;
+      // leaving name in this hoist too would duplicate the module-scope binding,
+      // and TS resolves to the untyped copy — dropping contextual typing for the
+      // function's params and `this` (the redeclare is auto-suppressed, so the
+      // symptom surfaces elsewhere). We deliberately keep the type on the header
+      // decl rather than re-emitting it onto this synthetic hoist line: the
+      // compiler source-maps the header's type name back to the real `name:: T`
+      // annotation, so diagnostics/quick-fixes land on it — re-emitting here
+      // would map them to the hoist's position instead. Function-body hoists are
+      // left alone: their locals get types from the compiler's inline hoist.
+      const kept = baseIndent === '' ? remaining.filter(v => !letTypes.has(v)) : remaining;
+      cl[i] = kept.length ? `${baseIndent}let ${kept.join(', ')};` : '';
     }
     code = cl.join('\n');
 
@@ -1633,20 +2047,147 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
     if (typedApp) code = code.replace(/declare app: any/g, typedApp);
   }
 
+  // `declare router: any` in the component stub is rewritten to the Router
+  // type exported by @rip-lang/app. Always available — the package ships its
+  // own DTS. Gated on a typed project (same `findEntryFile` check the stash
+  // splice uses) to avoid touching untyped sources.
+  if (code.includes('declare router: any') && findEntryFile(filePath)) {
+    code = code.replace(
+      /declare router: any/g,
+      `declare router: import('@rip-lang/app').Router`,
+    );
+  }
+
+  // ── Typed routes ─────────────────────────────────────────────────
+  //
+  // Three splices, all keyed off the project's `<routesDir>/` tree:
+  //   1. Entry file — append `export type __RipRoutes = ...;` so every
+  //      file in the project can reach it via
+  //      `import('<entry>').__RipRoutes`.
+  //   2. Per-route file (anything under <routesDir>/) — tighten the
+  //      `params: any` slot in the typed `declare app:` line so
+  //      `routes/users/[id].rip` sees `params: { id: string }`.
+  //   3. Any typed file that uses `<a>` elements — override the
+  //      INTRINSIC `__ripEl` declaration so anchor `href` is typed via
+  //      a `const H extends string` conditional: if H is a literal
+  //      starting with `/`, it must satisfy `__RipRoutes`; otherwise
+  //      (external URLs `https:`/`mailto:`, fragments `#x`, dynamic
+  //      `string`) it falls through to plain H. Also narrow
+  //      `router.push` to `__RipRoutes` for typo-catching.
+  const entryFile = findEntryFile(filePath);
+  const routesDir = findRoutesDir(filePath);
+  const isEntry   = entryFile && entryFile === filePath;
+  const isRoute   = routesDir && filePath.startsWith(routesDir + pathSep);
+
+  if (isEntry && routesDir) {
+    const { union } = walkRoutesDir(routesDir);
+    code += `\nexport type __RipRoutes = ${union};\n`;
+  }
+
+  // Per-route @params tightening: the component stub declares
+  // `declare params: Record<string, string>`. For route files whose
+  // filename carries dynamic segments (`[id].rip`, `[...rest].rip`),
+  // replace that with a precise shape so typos like `@params.bogu`
+  // are caught and `@params.id` narrows to `string` (the literal).
+  if (isRoute && entryFile) {
+    const { entries } = walkRoutesDir(routesDir);
+    const me = entries.find(e => e.file === filePath);
+    if (me && me.dynamic.length > 0) {
+      const paramFields = me.dynamic
+        .map(d => `${d.name}: string`)
+        .join('; ');
+      code = code.replace(
+        /declare params: Record<string, string>/g,
+        `declare params: { ${paramFields} }`,
+      );
+    }
+  }
+
+  // Anchor href + typed router.push/replace overrides. Spliced into the
+  // DTS header (where `__RipProps` is defined) and the `declare router`
+  // line (already rewritten above). Gated on the project having a
+  // routes dir at all — without routes there's no `__RipRoutes` to
+  // intersect with, so the default `string` href is what users get.
+  if (routesDir && entryFile && findStashFile(filePath)) {
+    // Reach __RipRoutes via the entry file's virtual module.
+    const entrySpec = entryImportSpec(filePath, entryFile);
+    const anchorRouteType = `import('${entrySpec}').__RipRoutes`;
+    // Inline the routes union for diagnostics on __ripRoute (dynamic
+    // interpolated hrefs). The static __ripEl path resolves the alias
+    // already; for the helper-call path we inline so error messages
+    // read "Argument of type '`/x/${number}`' is not assignable to
+    // parameter of type '<actual route union>'" instead of '__RipRoutes'.
+    const { union: inlineRoutesUnion } = walkRoutesDir(routesDir);
+
+    // Declare a clean local alias for NavOpts so hover shows `NavOpts`
+    // instead of `import("@rip-lang/app").NavOpts`. We *don't* alias
+    // __RipRoutes — inlining the union directly into the push signature
+    // makes hover and errors both show the actual list of routes,
+    // avoiding the leak of an implementation-detail name.
+    if (headerDts) {
+      headerDts = `type NavOpts = import('@rip-lang/app').NavOpts;\n` + headerDts;
+    }
+
+    // (a) Constrain <a href>: replace the INTRINSIC __ripEl declaration
+    // with a const-H-generic version whose href slot conditionally
+    // narrows to __RipRoutes for slash-prefixed literals. External
+    // URLs (https:, mailto:, #frag) and dynamic `string` values fall
+    // through to H. Error reads:
+    //   Type '"/foo"' is not assignable to type '__RipRoutes | undefined'.
+    if (headerDts) {
+      const newFnDecl = `declare function __ripEl<K extends __RipTag, const H extends string = string>(tag: K, props?: __RipProps<K> & (K extends 'a' ? { href?: H extends \`/\${string}\` ? ${inlineRoutesUnion} : H } : {})): void;`;
+      headerDts = headerDts.replace(
+        /declare function __ripEl<K extends __RipTag>\(tag: K, props\?: __RipProps<K>\): void;/,
+        newFnDecl,
+      );
+      // Strengthen __ripRoute: compiler wraps interpolated /-prefixed
+      // anchor href values in __ripRoute(...) so TS checks the dynamic
+      // template against __RipRoutes. Without this strengthening the
+      // baseline passthrough lets every string through.
+      headerDts = headerDts.replace(
+        /declare function __ripRoute<const T extends string>\(s: T\): T;/,
+        `declare function __ripRoute<const T extends ${inlineRoutesUnion}>(s: T): T;`,
+      );
+    }
+
+    // (b) Narrow router.push argument to __RipRoutes for typo-catching
+    // on programmatic navigation. Leave `router.replace` accepting plain
+    // `string` (the base Router signature) — it's commonly used to
+    // mutate the current URL with query strings, where the result is
+    // built dynamically and can't satisfy a literal-route union. Use
+    // Omit + re-add instead of intersection because intersecting
+    // overloaded methods makes the parameter type a union
+    // (contravariance), which loses the narrowing.
+    if (code.includes(`declare router: import('@rip-lang/app').Router`)) {
+      const typedRouter = `declare router: Omit<import('@rip-lang/app').Router, 'push'> & { push(url: ${inlineRoutesUnion}, opts?: NavOpts): void; }`;
+      code = code.replace(
+        /declare router: import\('@rip-lang\/app'\)\.Router(?![ &])/g,
+        typedRouter,
+      );
+    }
+  }
+
   // Dedupe imports: when the DTS header and the body import from the same
   // module specifier, TypeScript reports TS2300 (Duplicate identifier) for
   // every shared binding, which cascades and corrupts type resolution
-  // elsewhere (e.g. `typeof <stateIdent>` collapses to `any`). The DTS-side
-  // import is sufficient for type-checking; blank out matching body imports
-  // (preserve line count so source maps stay aligned).
+  // elsewhere (e.g. `typeof <stateIdent>` collapses to `any`).
+  //
+  // We prefer to drop the *DTS-header* duplicate and keep the body's import:
+  // the body import carries per-specifier source-map mappings (needed for
+  // hover and go-to-definition on each imported name), while the DTS header
+  // import has none. Dropping the body import would leave the source-map
+  // entries pointing at a blanked line, breaking hover for type-only
+  // imports like `import { RetryConfig } from '@rip-lang/http'`.
+  //
+  // Preserve line count on both sides so source maps stay aligned.
   if (hasTypes && headerDts && code) {
-    const dtsSpecs = new Set();
-    for (const m of headerDts.matchAll(/^\s*import\s+[^;]*?from\s+['"]([^'"]+)['"]\s*;?\s*$/gm)) {
-      dtsSpecs.add(m[1]);
+    const bodySpecs = new Set();
+    for (const m of code.matchAll(/^\s*import\s+[^;]*?from\s+['"]([^'"]+)['"]\s*;?\s*$/gm)) {
+      bodySpecs.add(m[1]);
     }
-    if (dtsSpecs.size > 0) {
-      code = code.replace(/^(\s*)import\s+[^;]*?from\s+(['"])([^'"]+)\2\s*;?\s*$/gm, (full, _ws, _q, spec) => {
-        return dtsSpecs.has(spec) ? '' : full;
+    if (bodySpecs.size > 0) {
+      headerDts = headerDts.replace(/^(\s*)import\s+[^;]*?from\s+(['"])([^'"]+)\2\s*;?\s*$/gm, (full, _ws, _q, spec) => {
+        return bodySpecs.has(spec) ? '' : full;
       });
     }
   }
@@ -1732,10 +2273,16 @@ export function compileForCheck(filePath, source, compiler, opts = {}) {
     const genGap = genB - genA;
     if (srcGap > 1 && genGap > 1 && srcGap <= genGap + 2) {
       for (let d = 1; d < srcGap; d++) {
-        if (!srcToGen.has(srcA + d) && genA + d < genB) {
-          srcToGen.set(srcA + d, genA + d);
-          if (!genToSrc.has(genA + d)) {
-            genToSrc.set(genA + d, srcA + d);
+        const gen = genA + d;
+        if (!srcToGen.has(srcA + d) && gen < genB) {
+          // Don't interpolate INTO the DTS header. Header lines must only
+          // carry explicit DTS-back-mappings (or none); fabricating a mapping
+          // here causes go-to-def to land on whatever source line happens to
+          // fall in the gap (typically a doc comment).
+          if (gen < headerLines) continue;
+          srcToGen.set(srcA + d, gen);
+          if (!genToSrc.has(gen)) {
+            genToSrc.set(gen, srcA + d);
           }
         }
       }
@@ -1890,13 +2437,27 @@ export function findNearestWord(text, word, approx) {
 
 // Check whether an offset falls on an injected function overload signature line
 // (generated by compileForCheck, not from user code).  These are body lines that
-// match `function NAME(...): TYPE;` and have no genToSrc entry.
+// match `[export ][async ]function NAME(...): TYPE;` and are immediately followed
+// by the matching implementation `[export ][async ]function NAME(...) ... {`.
+//
+// Note: we can't rely on `!genToSrc.has(line)` as a discriminator — the gap-fill
+// interpolation in buildLineMap will fabricate a mapping for the injected line.
 export function isInjectedOverload(entry, offset) {
   const tsLine = offsetToLine(entry.tsContent, offset);
   if (tsLine < entry.headerLines) return false;
-  if (entry.genToSrc.get(tsLine) !== undefined) return false;
   const lineText = getLineText(entry.tsContent, tsLine);
-  return /^(?:async\s+)?function\s+\w+\s*\(/.test(lineText) && lineText.trimEnd().endsWith(';');
+  const m = lineText.match(/^(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/);
+  if (!m) return false;
+  if (!lineText.trimEnd().endsWith(';')) return false;
+  // Confirm the next non-empty line is the implementation of the same function.
+  const allLines = entry.tsContent.split('\n');
+  for (let i = tsLine + 1; i < allLines.length; i++) {
+    const next = allLines[i];
+    if (next.trim() === '') continue;
+    const nm = next.match(/^(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/);
+    return !!nm && nm[1] === m[1] && !next.trimEnd().endsWith(';');
+  }
+  return false;
 }
 
 export function offsetToLine(text, offset) {
@@ -2162,6 +2723,39 @@ export function mapToSourcePos(entry, offset) {
     }
   }
   const srcText = entry.source ? getLineText(entry.source, srcLine) : '';
+  // Synthetic anchor: `__ripRoute(...)` wraps an anchor href value for
+  // dynamic route type-checking. The TS diagnostic span starts at the
+  // call argument (a template literal), which has no clean source token
+  // to land on — landing instead on the source `href:` keyword keeps
+  // dynamic anchor diagnostics visually consistent with the static
+  // `__ripEl` `href` case (TS2820 lands on the property identifier).
+  // Map both the start and end offsets that fall anywhere inside a
+  // `__ripRoute(...)` call to the bounds of the `href` keyword so the
+  // squiggle length matches the static case (4 chars) instead of
+  // spanning the whole compiled call expression.
+  if (srcText) {
+    const callStart = genText.lastIndexOf('__ripRoute(', genCol);
+    if (callStart >= 0) {
+      // Find matching `)` after the call
+      let depth = 0, callEnd = -1;
+      for (let i = callStart + '__ripRoute('.length - 1; i < genText.length; i++) {
+        const ch = genText[i];
+        if (ch === '(') depth++;
+        else if (ch === ')') { depth--; if (depth === 0) { callEnd = i; break; } }
+      }
+      if (callEnd >= 0 && genCol <= callEnd + 1) {
+        const m = srcText.match(/\bhref\b/);
+        if (m) {
+          // Heuristic for end offset: anchor at end of `href` (start + 4)
+          // when the gen offset is inside the call body (past the opening
+          // paren). For the start offset (at the opening paren or first
+          // arg char), anchor at the start of `href`.
+          const atOrBeforeArg = genCol <= callStart + '__ripRoute('.length;
+          return { line: srcLine, col: atOrBeforeArg ? m.index : m.index + 4 };
+        }
+      }
+    }
+  }
   // Text-match: find the word at genCol in the gen line, then locate it in the source line
   if (srcText) {
     let wordAt = genText.slice(genCol).match(/^\w+/);
@@ -2270,6 +2864,90 @@ export function mapToSourcePos(entry, offset) {
   return { line: srcLine, col: srcCol };
 }
 
+// Count top-level commas in `s` (depth 0 w.r.t. ()/[]/{}). Used to map a
+// cursor onto the Nth argument / Nth property when retargeting completion
+// offsets into object-literal call arguments.
+function countTopLevelCommas(s) {
+  let depth = 0, n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+    else if (ch === ',' && depth === 0) n++;
+  }
+  return n;
+}
+
+// Completion-offset fixup for inline object-literal call arguments, e.g.
+// `@router.push('/', { ▮ })`. At a non-identifier cursor (empty slot, after
+// a comma) the word-anchored `srcToOffset` has nothing to grab and lands on
+// the call name, so TS returns the receiver's *members* (push, replace, …)
+// instead of the object's contextually-typed *properties* (noScroll, …).
+//
+// Given the gen offset `srcToOffset` produced (which sits at/near the call
+// name on the gen line), this walks the gen call to the same argument index
+// and property slot the source cursor occupies and returns the corrected
+// absolute offset. Returns the original offset unchanged when the cursor
+// isn't in this situation, so callers can apply it unconditionally.
+export function retargetObjectArgOffset(entry, srcLine, srcCol, genOffset) {
+  if (!entry || genOffset == null || !srcLine) return genOffset;
+  const before = srcLine.slice(0, srcCol);
+  // On an identifier? Word-anchoring already mapped it precisely — leave it.
+  if (/\w$/.test(before) || /^\w/.test(srcLine.slice(srcCol))) return genOffset;
+
+  // Walk back to the enclosing object-literal `{`, tracking bracket depth.
+  let depth = 0, objOpen = -1;
+  for (let i = srcCol - 1; i >= 0; i--) {
+    const ch = before[i];
+    if (ch === '}' || ch === ')' || ch === ']') depth++;
+    else if (ch === '{') { if (depth === 0) { objOpen = i; break; } depth--; }
+    else if (ch === '(' || ch === '[') { if (depth === 0) return genOffset; depth--; }
+  }
+  if (objOpen < 0) return genOffset;
+  // The object must be a call argument: a `name(` must precede it with only
+  // argument text (no nested braces) between the `(` and this `{`.
+  const head = before.slice(0, objOpen);
+  const callM = head.match(/\.\s*\w+\s*\(([^(){}]*)$/);
+  if (!callM) return genOffset;
+  const argIndex = countTopLevelCommas(callM[1]);                 // object is this call-arg
+  const propSlot = countTopLevelCommas(before.slice(objOpen + 1)); // commas before cursor in object
+
+  // Gen side: locate the call paren near the mapped offset, then walk to the
+  // same argument and the same property slot inside its object literal.
+  const tsText = entry.tsContent;
+  const lc = offsetToLineCol(tsText, genOffset);
+  const genLine = tsText.split('\n')[lc.line];
+  if (genLine == null) return genOffset;
+  const callRe = /\.\s*\w+\s*\(/g;
+  callRe.lastIndex = Math.max(0, lc.col - 4);
+  const gm = callRe.exec(genLine);
+  if (!gm) return genOffset;
+  let i = gm.index + gm[0].length;  // just inside the call's `(`
+  let d = 1, args = 0;
+  // Advance to the start of argument `argIndex`.
+  while (i < genLine.length && args < argIndex) {
+    const ch = genLine[i];
+    if (ch === '(' || ch === '[' || ch === '{') d++;
+    else if (ch === ')' || ch === ']' || ch === '}') { d--; if (d === 0) return genOffset; }
+    else if (ch === ',' && d === 1) args++;
+    i++;
+  }
+  while (i < genLine.length && /\s/.test(genLine[i])) i++;
+  if (genLine[i] !== '{') return genOffset;                       // arg isn't an object literal
+  i++;                                                            // step inside the object
+  // Skip `propSlot` top-level properties within the object.
+  let pd = 1, props = 0;
+  while (i < genLine.length && props < propSlot) {
+    const ch = genLine[i];
+    if (ch === '(' || ch === '[' || ch === '{') pd++;
+    else if (ch === ')' || ch === ']' || ch === '}') { pd--; if (pd === 0) break; }
+    else if (ch === ',' && pd === 1) props++;
+    i++;
+  }
+  while (i < genLine.length && /\s/.test(genLine[i])) i++;
+  return genOffset - lc.col + i;
+}
+
 // Map a Rip source (line, col) to a TypeScript virtual file byte offset.
 // This is the forward direction: source → generated (used for hover, definition, etc.)
 //
@@ -2285,6 +2963,17 @@ export function srcToOffset(entry, line, col) {
   if (entry.srcColToGen) {
     const colEntries = entry.srcColToGen.get(line);
     if (colEntries && colEntries.length > 0) {
+      // Exact-column match wins regardless of genLine.  Sub-mapping anchors
+      // for identifiers in arrow bodies, spreads, etc. legitimately land on
+      // a different genLine than the statement's primary anchor; preferring
+      // them when they line up exactly with the queried column avoids the
+      // line-anchor filter (below) from discarding a precise mapping.
+      const exact = colEntries.find(e => e.srcCol === col);
+      if (exact) {
+        genLine = exact.genLine;
+        genColHint = exact.genCol;
+        bestSrcCol = exact.srcCol;
+      } else {
       // When srcToGen anchors this source line to a specific genLine, only
       // consider colEntries on that same genLine.  Stray entries on other
       // genLines (caused by upstream sub-mapping contamination across
@@ -2307,6 +2996,7 @@ export function srcToOffset(entry, line, col) {
       genLine = best.genLine;
       genColHint = best.genCol;
       bestSrcCol = best.srcCol;
+      }
     }
   }
 
@@ -2367,7 +3057,17 @@ export function srcToOffset(entry, line, col) {
         const dist = Math.abs(m.index - expectedGenCol) + (inStr ? STRING_PENALTY : 0);
         if (dist < bestDist) { bestDist = dist; bestCol = m.index; }
       }
-      if (bestCol >= 0) return lineColToOffset(entry.tsContent, targetLine, bestCol);
+      if (bestCol >= 0) {
+        // If every match for `word` in the target line is inside a string
+        // literal (so hover would return nothing) but we have a precise
+        // mapping hint for this source position, prefer the hint. This is
+        // what makes hover on `:foo` (which compiles to `Symbol.for("foo")`)
+        // resolve to the `Symbol` identifier instead of the dead string.
+        if (useHint && bestDist >= STRING_PENALTY) {
+          return lineColToOffset(entry.tsContent, targetLine, genColHint);
+        }
+        return lineColToOffset(entry.tsContent, targetLine, bestCol);
+      }
 
       // Fall back to original genLine if overload didn't match
       if (targetLine !== genLine) {
@@ -2458,23 +3158,32 @@ export function mapToSource(entry, offset) {
 
 // ── Project config ─────────────────────────────────────────────────
 
-// Read project config: rip.json in the given directory, or "rip" key in
-// the nearest ancestor package.json.  Returns { strict, exclude }.
+// Read project config from the "rip" key in the nearest ancestor
+// package.json. Returns { strict, checkAll, exclude, ... } merged from
+// `package.json#rip`, plus `_configDir` marking where it was found.
+//
+// `strict`   — TS strictness family (noImplicitAny, strictNullChecks, …)
+// `checkAll` — coverage policy: check every non-@nocheck file, not just
+//              annotated ones. Independent of `strict`.
 export function readProjectConfig(dir) {
   const config = {};
   try {
     let d = resolve(dir);
     while (true) {
-      const ripJsonPath = resolve(d, 'rip.json');
-      if (existsSync(ripJsonPath)) {
-        Object.assign(config, JSON.parse(readFileSync(ripJsonPath, 'utf8')));
-        config._configDir = d;
-        break;
-      }
       const pkgPath = resolve(d, 'package.json');
       if (existsSync(pkgPath)) {
+        // The first package.json walking up is the project boundary — matching
+        // the LSP's findProjectRoot and TypeScript's nearest-config resolution.
+        // Apply its `rip` config if present, otherwise fall back to defaults;
+        // either way stop here. We deliberately do NOT walk past it into
+        // ancestors: a parent repo's config must not silently leak across a
+        // project boundary (e.g. a standalone app nested inside a larger git
+        // repo inheriting that repo's `strict`). Inheritance, if ever wanted,
+        // should be opt-in and explicit rather than positional.
         const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-        if (pkg.rip && typeof pkg.rip === 'object') { Object.assign(config, pkg.rip); config._configDir = d; break; }
+        if (pkg.rip && typeof pkg.rip === 'object') Object.assign(config, pkg.rip);
+        config._configDir = d;
+        break;
       }
       const parent = dirname(d);
       if (parent === d) break;
@@ -2532,6 +3241,7 @@ function findRipFiles(dir, files = [], excludePatterns = [], rootDir = dir) {
 
 const isColor = process.stdout.isTTY !== false;
 const red     = (s) => isColor ? `\x1b[31m${s}\x1b[0m` : s;
+const green   = (s) => isColor ? `\x1b[32m${s}\x1b[0m` : s;
 const yellow  = (s) => isColor ? `\x1b[33m${s}\x1b[0m` : s;
 const cyan    = (s) => isColor ? `\x1b[36m${s}\x1b[0m` : s;
 const dim     = (s) => isColor ? `\x1b[2m${s}\x1b[0m`  : s;
@@ -2557,9 +3267,8 @@ export async function runCheck(targetDir, opts = {}) {
   }
 
   const ripConfig = readProjectConfig(rootPath);
-
-  // Merge: CLI flags override config file
-  const strict = opts.strict || ripConfig.strict === true;
+  const strict   = ripConfig.strict   === true;
+  const checkAll = ripConfig.checkAll === true;
   const excludeGlobs = Array.isArray(ripConfig.exclude) ? ripConfig.exclude : [];
   const excludePatterns = excludeGlobs.map(globToRegex);
 
@@ -2577,7 +3286,7 @@ export async function runCheck(targetDir, opts = {}) {
     const source = readFileSync(fp, 'utf8');
     sourcesByPath.set(fp, source);
     const nocheck = /^#\s*@nocheck\b/m.test(source.slice(0, NOCHECK_SCAN_LIMIT));
-    if (!nocheck && (hasTypeAnnotations(source) || strict)) typedFiles.add(fp);
+    if (!nocheck && (hasTypeAnnotations(source) || checkAll)) typedFiles.add(fp);
   }
 
   // Include imports of typed files (files imported BY typed files)
@@ -2613,7 +3322,7 @@ export async function runCheck(targetDir, opts = {}) {
   for (const fp of typedFiles) {
     try {
       const source = sourcesByPath.get(fp);
-      compiled.set(fp, compileForCheck(fp, source, new Compiler(), { strict }));
+      compiled.set(fp, compileForCheck(fp, source, new Compiler(), { checkAll }));
     } catch (e) {
       compileErrors++;
       const rel = relative(rootPath, fp);
@@ -2633,7 +3342,7 @@ export async function runCheck(targetDir, opts = {}) {
     if (compiled.has(stashFile) || !existsSync(stashFile)) continue;
     try {
       const src = sourcesByPath.get(stashFile) ?? readFileSync(stashFile, 'utf8');
-      const compiledStash = compileForCheck(stashFile, src, new Compiler(), { strict });
+      const compiledStash = compileForCheck(stashFile, src, new Compiler(), { checkAll });
       compiledStash._typeOnly = true; // skip diagnostics — only here for cross-module types
       compiled.set(stashFile, compiledStash);
     } catch (e) {
@@ -2641,6 +3350,30 @@ export async function runCheck(targetDir, opts = {}) {
     }
   }
 
+  // Always compile the project's entry file when routes exist, so its
+  // `__RipRoutes` export is resolvable from typed route/layout files. The
+  // entry file (server bin) is typically untyped — it just calls `start()` —
+  // so it wouldn't otherwise be pulled into the typed set, and
+  // `import('<entry>').__RipRoutes` would silently resolve to `any`,
+  // disabling the route-typo check. Diagnostics from the entry are
+  // suppressed via `_typeOnly` — only here as a cross-module type carrier.
+  const seenEntry = new Set();
+  for (const fp of typedFiles) {
+    const entryFile = findEntryFile(fp);
+    if (!entryFile || seenEntry.has(entryFile)) continue;
+    seenEntry.add(entryFile);
+    if (!findRoutesDir(fp)) continue;
+    if (compiled.has(entryFile) || !existsSync(entryFile)) continue;
+    try {
+      const src = sourcesByPath.get(entryFile) ?? readFileSync(entryFile, 'utf8');
+      const compiledEntry = compileForCheck(entryFile, src, new Compiler(), { checkAll });
+      compiledEntry._typeOnly = true;
+      compiled.set(entryFile, compiledEntry);
+    } catch (e) {
+      console.warn(`[rip] entry compile failed for ${entryFile}: ${e.message}`);
+    }
+  }
+
   // Also compile any .rip files imported from typed files that aren't yet compiled
   for (const [fp, entry] of [...compiled.entries()]) {
     if (!entry.hasTypes) continue;
@@ -2658,6 +3391,92 @@ export async function runCheck(targetDir, opts = {}) {
     }
   }
 
+  // ── @rip-lang/* package resolution ─────────────────────────────────
+  //
+  // When a typed file imports from `@rip-lang/foo` (or `@rip-lang/foo/sub`),
+  // resolve the specifier via Node module resolution rooted at the project,
+  // and if it lands on a `.rip` entry, compile that entry with
+  // compileForCheck so its exported annotations become visible to TS as
+  // a virtual `.rip.ts` module. Diagnostics from the package itself are
+  // suppressed (`_typeOnly = true`) — package internals are checked when
+  // the package is checked, not when its consumers are.
+  const pkgRequire = createRequire(resolve(rootPath, 'package.json'));
+  const pkgSpecCache = new Map(); // spec → resolved abs path | null
+  function resolvePkgSpec(spec) {
+    if (pkgSpecCache.has(spec)) return pkgSpecCache.get(spec);
+    let resolved = null;
+    try {
+      const r = pkgRequire.resolve(spec);
+      if (typeof r === 'string' && r.endsWith('.rip') && existsSync(r)) resolved = r;
+    } catch {}
+    pkgSpecCache.set(spec, resolved);
+    return resolved;
+  }
+
+  // ── Undeclared-import diagnostic (`rip check` surface) ──
+  // Same check as the loader and bundler — surfaced earlier when typing is on.
+  // The project's own `package.json#name` is treated as a self-import (covers
+  // in-package fixtures/tests like `packages/server/bench/index.rip`).
+  let undeclaredCount = 0;
+  try {
+    const projPkgPath = resolve(rootPath, 'package.json');
+    if (existsSync(projPkgPath)) {
+      const projPkg = JSON.parse(readFileSync(projPkgPath, 'utf8'));
+      const declared = new Set([
+        ...Object.keys(projPkg.dependencies         || {}),
+        ...Object.keys(projPkg.devDependencies      || {}),
+        ...Object.keys(projPkg.peerDependencies     || {}),
+        ...Object.keys(projPkg.optionalDependencies || {}),
+      ]);
+      const selfName = projPkg.name || null;
+      const reported = new Set();
+      for (const [fp, entry] of compiled) {
+        if (entry._typeOnly) continue;
+        for (const spec of scanRipPkgImports(entry.tsContent || entry.source)) {
+          const pkgKey = ripPkgRoot(spec);
+          if (pkgKey === selfName) continue;
+          if (declared.has(pkgKey)) continue;
+          const key = `${fp}::${pkgKey}`;
+          if (reported.has(key)) continue;
+          reported.add(key);
+          const rel = relative(rootPath, fp);
+          console.error(`${red('error')} ${cyan(rel)}: import of '${pkgKey}' is not declared in package.json. Run \`bun add ${pkgKey}\` (or use \`workspace:*\` inside this monorepo).`);
+          undeclaredCount++;
+        }
+      }
+    }
+  } catch (e) {
+    console.warn(`[rip] undeclared-import check failed: ${e.message}`);
+  }
+  const pendingPkgFiles = new Set();
+  for (const [, entry] of compiled) {
+    const text = entry.tsContent || entry.source;
+    for (const spec of [...scanRipPkgImports(text), ...scanRipPkgImportTypes(text)]) {
+      const r = resolvePkgSpec(spec);
+      if (r && !compiled.has(r)) pendingPkgFiles.add(r);
+    }
+  }
+  // Iterate transitively: package files may themselves import other
+  // @rip-lang/* entries. Bounded by the number of unique resolved paths.
+  while (pendingPkgFiles.size) {
+    const next = pendingPkgFiles.values().next().value;
+    pendingPkgFiles.delete(next);
+    if (compiled.has(next)) continue;
+    try {
+      const pkgSrc = readFileSync(next, 'utf8');
+      const compiledPkg = compileForCheck(next, pkgSrc, new Compiler());
+      compiledPkg._typeOnly = true;
+      compiled.set(next, compiledPkg);
+      const pkgText = compiledPkg.tsContent || pkgSrc;
+      for (const spec of [...scanRipPkgImports(pkgText), ...scanRipPkgImportTypes(pkgText)]) {
+        const r = resolvePkgSpec(spec);
+        if (r && !compiled.has(r)) pendingPkgFiles.add(r);
+      }
+    } catch (e) {
+      console.warn(`[rip] @rip-lang package compile failed for ${next}: ${e.message}`);
+    }
+  }
+
   // Check for unresolved relative imports in all files (not just typed ones)
   const fileResults = [];
   let totalErrors = 0, totalWarnings = 0;
@@ -2680,16 +3499,25 @@ export async function runCheck(targetDir, opts = {}) {
 
   // Create TypeScript language service
   //
-  // Project-scope `strict` (rip.json / package.json `rip.strict: true`, or
-  // CLI --strict) opts the project UP to TypeScript's `strict` family,
-  // which implies noImplicitAny, strictNullChecks, strictFunctionTypes,
-  // and friends. With strict on: `T` excludes null/undefined, untyped
-  // params error, etc. Without strict: lenient gradual-typing defaults —
-  // annotations are accepted as documentation but not enforced as
-  // contracts. The default is lenient to match Rip's "scaffolding, not
-  // safety rails" philosophy; projects opt up when they want the
-  // contract enforced.
-  const settings = createTypeCheckSettings(ts, strict ? { strict: true } : {});
+  // Project-scope `strict` (package.json `rip.strict: true`)
+  // opts the project UP to TypeScript's `strict` family, which implies
+  // noImplicitAny, strictNullChecks, strictFunctionTypes, and friends.
+  // With strict on: `T` excludes null/undefined, untyped params error,
+  // etc. Without strict: lenient gradual-typing defaults — annotations
+  // are accepted as documentation but not enforced as contracts. The
+  // default is lenient to match Rip's "scaffolding, not safety rails"
+  // philosophy; projects opt up when they want the contract enforced.
+  // Collect `node_modules/@types` directories walking up from rootPath so
+  // ambient type packages (e.g. `@types/bun`) installed at the workspace
+  // root are picked up even when `rip check` runs in a sub-package. TS's
+  // default `typeRoots` only looks at `<cwd>/node_modules/@types`.
+  const { typeRoots, types: ambientTypes } = collectAmbientTypes(rootPath);
+
+  const settings = createTypeCheckSettings(ts, {
+    ...(strict ? { strict: true } : {}),
+    ...(typeRoots.length ? { typeRoots } : {}),
+    ...(ambientTypes.length ? { types: ambientTypes } : {}),
+  });
 
   const host = {
     getScriptFileNames: () => [...compiled.keys()].map(toVirtual),
@@ -2708,6 +3536,14 @@ export async function runCheck(targetDir, opts = {}) {
     getDirectories: (...a) => ts.sys.getDirectories(...a),
     directoryExists: (...a) => ts.sys.directoryExists(...a),
 
+    resolveTypeReferenceDirectives(typeDirectiveNames, containingFile, redirectedReference, options) {
+      return typeDirectiveNames.map((name) => {
+        const n = typeof name === 'string' ? name : name.name;
+        const r = ts.resolveTypeReferenceDirective(n, containingFile, options || settings, ts.sys, redirectedReference);
+        return r.resolvedTypeReferenceDirective;
+      });
+    },
+
     resolveModuleNames(names, containingFile) {
       return names.map((name) => {
         if (name.endsWith('.rip')) {
@@ -2716,6 +3552,12 @@ export async function runCheck(targetDir, opts = {}) {
             return { resolvedFileName: toVirtual(resolved), extension: '.ts', isExternalLibraryImport: false };
           }
         }
+        if (name.startsWith('@rip-lang/')) {
+          const r = resolvePkgSpec(name);
+          if (r && compiled.has(r)) {
+            return { resolvedFileName: toVirtual(r), extension: '.ts', isExternalLibraryImport: false };
+          }
+        }
         const r = ts.resolveModuleName(name, containingFile, settings, {
           fileExists: host.fileExists,
           readFile: host.readFile,
@@ -2783,12 +3625,18 @@ export async function runCheck(targetDir, opts = {}) {
       if (adj) { pos.line = adj.line; pos.col = adj.col; }
 
       const endPos = adj ? { line: adj.line, col: adj.col + adj.len } : (d.length ? mapToSourcePos(entry, d.start + d.length) : null);
-      const len = endPos && endPos.line === pos.line ? endPos.col - pos.col : 1;
+      let len = endPos && endPos.line === pos.line ? endPos.col - pos.col : 1;
 
       const message = cleanDiagnosticMessage(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
       const severity = d.category === 1 ? 'error' : d.category === 0 ? 'warning' : 'info';
       const srcLine = srcLines[pos.line] || '';
 
+      const { code: finalCode, message: finalMessage } = unifyRouteDiagnostic(d.code, message, entry, d.start, fp);
+
+      // Snap route diagnostics to the meaningful token (`href` / `push`).
+      const routeSpan = locateRouteDiagnosticSpan(entry, d.start, srcLine);
+      if (routeSpan) { pos.col = routeSpan.col; len = routeSpan.len; }
+
       // Collect related information
       const related = [];
       if (d.relatedInformation) {
@@ -2835,7 +3683,7 @@ export async function runCheck(targetDir, opts = {}) {
         }
       }
 
-      errors.push({ line: pos.line + 1, col: pos.col + 1, len: Math.max(1, len), message, severity, code: d.code, srcLine, related });
+      errors.push({ line: pos.line + 1, col: pos.col + 1, len: Math.max(1, len), message: finalMessage, severity, code: finalCode, srcLine, related });
       if (severity === 'error') totalErrors++;
       else if (severity === 'warning') totalWarnings++;
     }
@@ -2942,6 +3790,12 @@ export async function runCheck(targetDir, opts = {}) {
   // round-trip: srcToOffset must resolve, and getQuickInfoAtPosition must
   // return hover info for it.  Failures indicate source map gaps that make
   // hover/definition/completion silently break in the editor.
+  //
+  // Opt-in via `rip check --sourcemap`.  This is a compiler-development
+  // diagnostic — gaps usually mean the audit's skip list is incomplete or
+  // that codegen lost a binding, both compiler-side concerns rather than
+  // anything a package author can fix.  Not run as part of `--audit` (which
+  // is the package-author-facing public-API check).
 
   const AUDIT_SKIP = new Set([
     'if', 'else', 'then', 'unless', 'switch', 'when', 'for', 'while', 'until',
@@ -3009,7 +3863,7 @@ export async function runCheck(targetDir, opts = {}) {
   let auditGaps = 0;
   const auditResults = [];
 
-  for (const [fp, entry] of compiled) {
+  if (opts.sourceMapAudit) for (const [fp, entry] of compiled) {
     if (!entry.hasTypes) continue;
     if (entry._typeOnly) continue;
     const srcLines = entry.source.split('\n');
@@ -3106,19 +3960,6 @@ export async function runCheck(targetDir, opts = {}) {
     }
   }
 
-  // Print audit results
-  if (auditResults.length > 0) {
-    console.log(bold('\n── Source Map Audit ──\n'));
-    for (const { file, gaps } of auditResults) {
-      const rel = relative(rootPath, file);
-      for (const g of gaps) {
-        const loc = `${cyan(rel)}${dim(':')}${yellow(String(g.line))}${dim(':')}${yellow(String(g.col))}`;
-        console.log(`${loc} ${dim('-')} ${yellow('warning')} ${dim('audit:')} ${g.issue} for '${g.word}'`);
-      }
-    }
-    console.log(`\n${yellow(String(auditGaps))} source map gap${auditGaps === 1 ? '' : 's'} found\n`);
-  }
-
   // Print results — tsc format with Rip source positions
   for (const { file, errors } of fileResults) {
     const rel = relative(rootPath, file);
@@ -3158,7 +3999,8 @@ export async function runCheck(targetDir, opts = {}) {
   // Summary — tsc format
   const totalFound = totalErrors + totalWarnings;
   if (totalFound === 0) {
-    return compileErrors > 0 ? 1 : 0;
+    printSourceMapAudit();
+    return compileErrors > 0 || undeclaredCount > 0 ? 1 : 0;
   }
 
   const s = totalFound === 1 ? '' : 's';
@@ -3180,5 +4022,418 @@ export async function runCheck(targetDir, opts = {}) {
     console.log('');
   }
 
-  return totalErrors > 0 ? 1 : 0;
+  printSourceMapAudit();
+  return totalErrors > 0 || undeclaredCount > 0 ? 1 : 0;
+
+  function printSourceMapAudit() {
+    if (!opts.sourceMapAudit || auditResults.length === 0) return;
+    console.log(bold('── Source Map Audit ──\n'));
+    for (const { file, gaps } of auditResults) {
+      const rel = relative(rootPath, file);
+      for (const g of gaps) {
+        const loc = `${cyan(rel)}${dim(':')}${yellow(String(g.line))}${dim(':')}${yellow(String(g.col))}`;
+        console.log(`${loc} ${dim('-')} ${yellow('warning')} ${dim('audit:')} ${g.issue} for '${g.word}'`);
+      }
+    }
+    console.log(`\n${yellow(String(auditGaps))} source map gap${auditGaps === 1 ? '' : 's'} found\n`);
+  }
+}
+
+// ── Public-surface `any` audit ─────────────────────────────────────
+//
+// `rip check --audit [pkgDir]` walks a package's public exports and
+// flags any export whose type contains `any` (in parameters, return
+// types, or own properties of types declared in the package).
+// External types (e.g. lib.es5, @types/*) are treated as opaque —
+// we don't dive into `Promise<Response>` looking for `any` inside
+// `Response`. The package can only control its own surface; this
+// audit measures exactly that.
+//
+// Exit code: 0 if every export is `any`-free, 1 otherwise.
+
+// Resolve a package's public entries from its package.json. Handles
+// `main`, `module`, string `exports`, and the subpath/conditional
+// `exports` map. Returns [{ subpath, file }] with absolute paths.
+function collectPackageEntries(pkg, pkgDir) {
+  const entries = new Map(); // subpath → abs file
+  const add = (subpath, p) => {
+    if (typeof p !== 'string') return;
+    if (entries.has(subpath)) return;
+    entries.set(subpath, resolve(pkgDir, p));
+  };
+  const walkConditional = (subpath, v) => {
+    if (typeof v === 'string') { add(subpath, v); return; }
+    if (!v || typeof v !== 'object') return;
+    // Prefer `import` then `default`, fall back to any string value.
+    if (typeof v.import === 'string') { add(subpath, v.import); return; }
+    if (typeof v.default === 'string') { add(subpath, v.default); return; }
+    for (const k of Object.keys(v)) walkConditional(subpath, v[k]);
+  };
+
+  if (typeof pkg.exports === 'string') {
+    add('.', pkg.exports);
+  } else if (pkg.exports && typeof pkg.exports === 'object') {
+    const keys = Object.keys(pkg.exports);
+    const isSubpathMap = keys.some(k => k.startsWith('.'));
+    if (isSubpathMap) {
+      for (const sp of keys) walkConditional(sp, pkg.exports[sp]);
+    } else {
+      walkConditional('.', pkg.exports);
+    }
+  }
+  if (!entries.has('.') && typeof pkg.module === 'string') add('.', pkg.module);
+  if (!entries.has('.') && typeof pkg.main   === 'string') add('.', pkg.main);
+  return [...entries.entries()].map(([subpath, file]) => ({ subpath, file }));
+}
+
+// True if `type`'s declarations all live outside the package's
+// compiled set (i.e. it's a lib/`@types`/external type). Anonymous
+// types (no symbol or no declarations) are treated as local — they
+// are inline shapes from the package's own annotations.
+function isExternalType(type, compiled) {
+  const sym = type.aliasSymbol || type.symbol;
+  if (!sym || !sym.declarations || sym.declarations.length === 0) return false;
+  for (const d of sym.declarations) {
+    const sf = d.getSourceFile?.();
+    if (!sf) continue;
+    if (compiled.has(fromVirtual(sf.fileName))) return false;
+  }
+  return true;
+}
+
+// Walk a TS type looking for `any`. Returns null if no leak, or a
+// breadcrumb string describing where the `any` lives.
+//
+// Scoping rule: EXTERNAL types are fully opaque. We don't walk into
+// their unions, type arguments, signatures, or properties. The
+// package is only accountable for shapes it directly wrote. If a
+// package's export references another local exported type, that
+// referenced type gets audited on its own export — not transitively
+// through every place it's referenced.
+//
+// Why so strict: lib.dom types like `BodyInit` resolve to unions
+// including `ReadableStream<R = any>`. Walking into the expansion
+// blames the package for `any` it never wrote. Same for `Promise<T>`,
+// `Array<T>`, `Record<K, V>`, etc. — diving into them surfaces
+// internals the package doesn't control.
+//
+// Trade-off: `Promise<any>` written literally in package source is
+// also opaque under this rule, so we miss it. Acceptable: such a
+// pattern is rare and easy to spot in review.
+function findAnyLeaks(type, ts, checker, compiled, seen = new WeakSet(), depth = 0, exportedSymbols = null, rootSymbol = null) {
+  if (!type || depth > 12) return null;
+  if (type.flags & ts.TypeFlags.Any) return '';
+  if (isExternalType(type, compiled)) return null;
+  // On recursion (depth > 0), stop at any other exported symbol.
+  // Each export is audited on its own line — don't double-count
+  // leaks through cross-references.
+  if (depth > 0 && exportedSymbols) {
+    const sym = type.aliasSymbol || type.symbol;
+    if (sym && sym !== rootSymbol && exportedSymbols.has(sym)) return null;
+  }
+  if (seen.has(type)) return null;
+  seen.add(type);
+
+  const named = (type.aliasSymbol || type.symbol)?.getName?.();
+  const label = named && named !== '__type' && named !== '__object' ? named : null;
+
+  if (type.isUnion?.() || type.isIntersection?.()) {
+    for (let i = 0; i < type.types.length; i++) {
+      const p = findAnyLeaks(type.types[i], ts, checker, compiled, seen, depth + 1, exportedSymbols, rootSymbol);
+      if (p !== null) return joinPath(label, `|${i}`, p);
+    }
+  }
+
+  const args = checker.getTypeArguments?.(type) || type.typeArguments || [];
+  for (let i = 0; i < args.length; i++) {
+    const p = findAnyLeaks(args[i], ts, checker, compiled, seen, depth + 1, exportedSymbols, rootSymbol);
+    if (p !== null) return joinPath(label, `<${i}>`, p);
+  }
+
+  const walkParams = (sig) => {
+    for (const p of sig.parameters) {
+      const decl = p.valueDeclaration || p.declarations?.[0];
+      if (!decl) continue;
+      const pt = checker.getTypeOfSymbolAtLocation(p, decl);
+      const sub = findAnyLeaks(pt, ts, checker, compiled, seen, depth + 1, exportedSymbols, rootSymbol);
+      if (sub !== null) return joinPath(null, `(${p.getName()})`, sub);
+    }
+    return null;
+  };
+
+  for (const sig of type.getCallSignatures?.() || []) {
+    const ps = walkParams(sig);
+    if (ps !== null) return joinPath(label, '', ps);
+    const rs = findAnyLeaks(sig.getReturnType(), ts, checker, compiled, seen, depth + 1, exportedSymbols, rootSymbol);
+    if (rs !== null) return joinPath(label, '=>', rs);
+  }
+  for (const sig of type.getConstructSignatures?.() || []) {
+    const ps = walkParams(sig);
+    if (ps !== null) return joinPath(label, 'new', ps);
+    const rs = findAnyLeaks(sig.getReturnType(), ts, checker, compiled, seen, depth + 1, exportedSymbols, rootSymbol);
+    if (rs !== null) return joinPath(label, 'new=>', rs);
+  }
+
+  if (type.getProperties) {
+    for (const p of type.getProperties()) {
+      const decl = p.valueDeclaration || p.declarations?.[0];
+      if (!decl) continue;
+      const sf = decl.getSourceFile?.();
+      if (!sf) continue;
+      if (!compiled.has(fromVirtual(sf.fileName))) continue;
+      const pt = checker.getTypeOfSymbolAtLocation(p, decl);
+      const sub = findAnyLeaks(pt, ts, checker, compiled, seen, depth + 1, exportedSymbols, rootSymbol);
+      if (sub !== null) return joinPath(label, `.${p.getName()}`, sub);
+    }
+  }
+
+  return null;
+}
+
+function joinPath(label, step, rest) {
+  const head = label ? `${label}${step}` : step;
+  if (!rest) return head || '<any>';
+  if (rest.startsWith('|') || rest.startsWith('<') || rest.startsWith('(') || rest.startsWith('.') || rest.startsWith('=>') || rest.startsWith('new')) {
+    return head + rest;
+  }
+  return head ? `${head}.${rest}` : rest;
+}
+
+export async function runAudit(targetDir) {
+  const rootPath = resolve(targetDir);
+
+  let ts;
+  try {
+    const req = createRequire(resolve(rootPath, 'package.json'));
+    ts = req('typescript');
+  } catch {
+    try { ts = await import('typescript').then(m => m.default || m); } catch {
+      console.error('TypeScript is required for --audit. Install with: bun add -d typescript');
+      return 1;
+    }
+  }
+
+  const pkgJsonPath = resolve(rootPath, 'package.json');
+  if (!existsSync(pkgJsonPath)) {
+    console.error(red(`No package.json found at ${rootPath}`));
+    return 1;
+  }
+  const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+  const pkgName = pkg.name || basename(rootPath);
+
+  const allEntries = collectPackageEntries(pkg, rootPath);
+  const ripEntries = allEntries.filter(e => e.file.endsWith('.rip') && existsSync(e.file));
+  if (ripEntries.length === 0) {
+    console.error(red(`No .rip entry points found in ${pkgName}`));
+    if (allEntries.length > 0) {
+      console.error(dim(`  package.json declares entries, but none point to a .rip file:`));
+      for (const e of allEntries) console.error(dim(`    ${e.subpath} → ${relative(rootPath, e.file)}`));
+    }
+    return 1;
+  }
+
+  // Compile each entry plus its transitive `.rip` imports so the
+  // language service can resolve cross-module types. Only entries
+  // themselves are audited; imported files exist purely so types
+  // referenced from the entry can be expanded.
+  const compiled = new Map();
+  const queue = ripEntries.map(e => e.file);
+  while (queue.length) {
+    const fp = queue.shift();
+    if (compiled.has(fp)) continue;
+    try {
+      const source = readFileSync(fp, 'utf8');
+      // Compile with strict: true so every export's annotations are
+      // emitted into the DTS — without strict, partially-annotated
+      // exports could fall back to inferred types that look cleaner
+      // than they really are.
+      compiled.set(fp, compileForCheck(fp, source, new Compiler(), { checkAll: true }));
+      for (const m of source.matchAll(/from\s+['"]([^'"]+)['"]/g)) {
+        const spec = m[1];
+        if (spec.endsWith('.rip')) {
+          const r = resolve(dirname(fp), spec);
+          if (existsSync(r) && !compiled.has(r)) queue.push(r);
+        }
+      }
+    } catch (e) {
+      console.error(`${red('error')} ${cyan(relative(rootPath, fp))}: compile error — ${e.message}`);
+      return 1;
+    }
+  }
+
+  // Resolve @rip-lang/* package imports (siblings in the workspace)
+  // so cross-package re-exports type correctly.
+  const pkgRequire = createRequire(resolve(rootPath, 'package.json'));
+  const pkgSpecCache = new Map();
+  function resolvePkgSpec(spec) {
+    if (pkgSpecCache.has(spec)) return pkgSpecCache.get(spec);
+    let resolved = null;
+    try {
+      const r = pkgRequire.resolve(spec);
+      if (typeof r === 'string' && r.endsWith('.rip') && existsSync(r)) resolved = r;
+    } catch {}
+    pkgSpecCache.set(spec, resolved);
+    return resolved;
+  }
+  const pkgQueue = new Set();
+  for (const [, entry] of compiled) {
+    for (const spec of scanRipPkgImports(entry.tsContent || entry.source)) {
+      const r = resolvePkgSpec(spec);
+      if (r && !compiled.has(r)) pkgQueue.add(r);
+    }
+  }
+  while (pkgQueue.size) {
+    const next = pkgQueue.values().next().value;
+    pkgQueue.delete(next);
+    if (compiled.has(next)) continue;
+    try {
+      const src = readFileSync(next, 'utf8');
+      const compiledPkg = compileForCheck(next, src, new Compiler());
+      compiled.set(next, compiledPkg);
+      for (const spec of scanRipPkgImports(compiledPkg.tsContent || src)) {
+        const r = resolvePkgSpec(spec);
+        if (r && !compiled.has(r)) pkgQueue.add(r);
+      }
+    } catch (e) {
+      console.warn(`[rip] @rip-lang package compile failed for ${next}: ${e.message}`);
+    }
+  }
+
+  const { typeRoots, types: ambientTypes } = collectAmbientTypes(rootPath);
+  const settings = createTypeCheckSettings(ts, {
+    strict: true,
+    ...(typeRoots.length    ? { typeRoots }              : {}),
+    ...(ambientTypes.length ? { types: ambientTypes }    : {}),
+  });
+
+  const host = {
+    getScriptFileNames: () => [...compiled.keys()].map(toVirtual),
+    getScriptVersion:   () => '1',
+    getScriptSnapshot(f) {
+      const c = compiled.get(fromVirtual(f));
+      if (c) return ts.ScriptSnapshot.fromString(c.tsContent);
+      try { return ts.ScriptSnapshot.fromString(readFileSync(f, 'utf8')); } catch { return undefined; }
+    },
+    getCompilationSettings: () => settings,
+    getDefaultLibFileName:  (o) => ts.getDefaultLibFilePath(o),
+    getCurrentDirectory:    () => rootPath,
+    fileExists(f) { return compiled.has(fromVirtual(f)) || ts.sys.fileExists(f); },
+    readFile(f)   { return compiled.get(fromVirtual(f))?.tsContent || ts.sys.readFile(f); },
+    readDirectory:   (...a) => ts.sys.readDirectory(...a),
+    getDirectories:  (...a) => ts.sys.getDirectories(...a),
+    directoryExists: (...a) => ts.sys.directoryExists(...a),
+    resolveTypeReferenceDirectives(names, containingFile, redirectedReference, options) {
+      return names.map(n => {
+        const name = typeof n === 'string' ? n : n.name;
+        const r = ts.resolveTypeReferenceDirective(name, containingFile, options || settings, ts.sys, redirectedReference);
+        return r.resolvedTypeReferenceDirective;
+      });
+    },
+    resolveModuleNames(names, containingFile) {
+      return names.map(name => {
+        if (name.endsWith('.rip')) {
+          const r = resolve(dirname(fromVirtual(containingFile)), name);
+          if (compiled.has(r)) return { resolvedFileName: toVirtual(r), extension: '.ts', isExternalLibraryImport: false };
+        }
+        if (name.startsWith('@rip-lang/')) {
+          const r = resolvePkgSpec(name);
+          if (r && compiled.has(r)) return { resolvedFileName: toVirtual(r), extension: '.ts', isExternalLibraryImport: false };
+        }
+        const r = ts.resolveModuleName(name, containingFile, settings, {
+          fileExists:          host.fileExists,
+          readFile:            host.readFile,
+          directoryExists:     host.directoryExists,
+          getCurrentDirectory: host.getCurrentDirectory,
+          getDirectories:      host.getDirectories,
+        });
+        return r.resolvedModule;
+      });
+    },
+  };
+
+  const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+  const program = service.getProgram();
+  const checker = program.getTypeChecker();
+  const fmtFlags = ts.TypeFormatFlags.NoTruncation
+    | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope
+    | ts.TypeFormatFlags.WriteArrayAsGenericType;
+
+  let totalExports = 0, totalLeaks = 0;
+
+  // First pass: collect ALL exported symbols across all entries.
+  // The walker treats these as opaque on recursion — each export is
+  // audited only on its own direct shape. If export A references
+  // export B and B leaks, the leak surfaces on B's audit line, not
+  // by polluting every type that mentions B.
+  const exportedSymbols = new Set();
+  const entryData = [];
+  for (const entry of ripEntries) {
+    const vf = toVirtual(entry.file);
+    const sourceFile = program.getSourceFile(vf);
+    if (!sourceFile) { entryData.push(null); continue; }
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    if (!moduleSymbol) { entryData.push({ sourceFile, exports: null }); continue; }
+    const exps = checker.getExportsOfModule(moduleSymbol);
+    for (const s of exps) exportedSymbols.add(s);
+    entryData.push({ sourceFile, exports: exps });
+  }
+
+  for (let idx = 0; idx < ripEntries.length; idx++) {
+    const entry = ripEntries[idx];
+    const data = entryData[idx];
+    const rel = relative(rootPath, entry.file);
+
+    if (!data) {
+      console.log(`  ${red('error')} could not load ${cyan(rel)}`);
+      continue;
+    }
+    const { sourceFile, exports } = data;
+    if (!exports) {
+      console.log(`  ${dim('(no exports)')}`);
+      continue;
+    }
+
+    const header = entry.subpath === '.' ? rel : `${rel}  ${dim('('+entry.subpath+')')}`;
+    console.log(`\n  ${cyan(header)}`);
+
+    // Compute max name width for column alignment.
+    const names = exports.map(s => s.getName());
+    const colW = Math.min(28, names.reduce((m, n) => Math.max(m, n.length), 0));
+
+    for (const sym of exports) {
+      totalExports++;
+      let t;
+      if (sym.flags & ts.SymbolFlags.Value) {
+        t = checker.getTypeOfSymbolAtLocation(sym, sourceFile);
+      } else {
+        t = checker.getDeclaredTypeOfSymbol(sym);
+      }
+      // Pass `sym` as the rootSymbol so recursion into OTHER exported
+      // symbols stops, but recursion into the export's own self-named
+      // type (e.g. typeof Class → the class itself) doesn't immediately
+      // bail out.
+      const leakPath = findAnyLeaks(t, ts, checker, compiled, new WeakSet(), 0, exportedSymbols, sym);
+      const leaks = leakPath !== null;
+      const typeStr = checker.typeToString(t, sourceFile, fmtFlags);
+      const name = sym.getName();
+      const mark = leaks ? red('✗') : green('✓');
+      console.log(`    ${mark} ${name.padEnd(colW)}  ${dim(typeStr)}`);
+      if (leaks) {
+        totalLeaks++;
+        console.log(`      ${dim('└─ any at: ')}${yellow(leakPath || '<root>')}`);
+      }
+    }
+  }
+
+  const typed = totalExports - totalLeaks;
+  const pct = totalExports > 0 ? (100 * typed / totalExports).toFixed(1) : '100.0';
+
+  console.log('');
+  if (totalLeaks === 0) {
+    console.log(`${green('✓')} ${bold(pkgName)}: ${typed}/${totalExports} exports fully typed (${pct}%).`);
+  } else {
+    console.log(`${red('✗')} ${bold(pkgName)}: ${typed}/${totalExports} exports fully typed (${pct}%). ${red(String(totalLeaks))} export${totalLeaks === 1 ? '' : 's'} leak \`any\`.`);
+  }
+
+  return totalLeaks > 0 ? 1 : 0;
 }