tempest-react-sdk 0.25.0 → 0.26.0

package/README.md

@@ -149,7 +149,7 @@ Via `package.json`:
 ```json
 {
   "dependencies": {
-    "tempest-react-sdk": "^0.1.0"
+    "tempest-react-sdk": "^0.26.0"
   }
 }
 ```
@@ -198,6 +198,17 @@ This injects the design tokens (`--tempest-primary`, `--tempest-radius-md`, ...)
 
 The styles ship hashed under the `tempest_` namespace — they do **not** collide with Tailwind, Stitches, Linaria, or app-level CSS Modules.
 
+**Rebranding.** The `--tempest-*` tokens are the only theming API, and `createTheme` writes them for you — `primary` alone yields the ten-step scale for **both** color schemes (dark inverts the ramp), plus the status families, the radius scale and the focus ring:
+
+```ts
+import { applyTheme, createTheme, themePresets } from "tempest-react-sdk";
+
+applyTheme(createTheme({ primary: "#7c3aed", radius: "lg" }));
+applyTheme(createTheme(themePresets.violet)); // or start from a preset
+```
+
+The ramp is derived in OKLCH (HSL lightness is not perceptual, which is what makes generated palettes look broken for some hues) and **anchored at step `500`**, so the color you pass is the color your buttons get. `--tempest-primary-foreground` and the text-on-soft step are picked by **measured** contrast, not convention — hardcoding white breaks a yellow brand. See [Theme › createTheme](https://mauriciobenjamin700.github.io/tempest-react-sdk/theme/).
+
 **Optional layout layer.** CSS Modules cover the inside of each component; the layer _around_ them (page shell, two-column form, action row, card, a region that scrolls sideways instead of the page) is a second, opt-in stylesheet:
 
 ```ts
@@ -232,6 +243,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                    |
 | `charts` _(subpath `tempest-react-sdk/charts`, opt. peer `recharts`)_                             | `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `DEFAULT_CHART_COLORS` — themed recharts wrappers (recharts externalized; install it only if you use charts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `icons` _(subpath `tempest-react-sdk/icons`)_                                                     | `Icon`, `IconProvider`, `createIconRegistry`, `useIcon`, `preloadIcons`, `iconStatus`, `peekIcon`, `loadIcon`, `resolveIconAlias`, `isIconName`, `iconNames`, `iconAliases`, type `IconName` — render any of lucide's **1997 icons by kebab-case slug**. A literal slug becomes a static import via the `tempestIcons()` Vite plugin (zero extra requests); a runtime slug loads **one chunk per initial letter** (25 max) instead of the ~2000 chunk boundaries `lucide-react`'s own `DynamicIcon` forces. Unknown slug renders `fallback` and never throws; lucide's 248 deprecated aliases keep resolving                                                                                                                                                                                                 |
 | `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore`                                                                                                                                                                                                                                                                                                          |
 | `error-boundary`                                                                                  | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -260,6 +272,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `ws`                                                                                              | `createWebSocket`, `useWebSocket`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                                                                                                                                                                 |
 | `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                   |
+| `icons` _(subpath `tempest-react-sdk/icons`)_                                                     | `Icon`, `IconProvider`, `createIconRegistry`, `useIcon`, `preloadIcons`, `iconStatus`, `peekIcon`, `loadIcon`, `resolveIconAlias`, `isIconName`, `iconNames`, `iconAliases`, type `IconName` — render any of lucide's **1997 icons by kebab-case slug**. A literal slug becomes a static import via the `tempestIcons()` Vite plugin (zero extra requests); a runtime slug loads **one chunk per initial letter** (25 max) instead of the ~2000 chunk boundaries `lucide-react`'s own `DynamicIcon` forces. Unknown slug renders `fallback` and never throws; lucide's 248 deprecated aliases keep resolving                                                                                                                                                                                                 |
 | `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                    |
 | `editor` _(subpath `tempest-react-sdk/editor`, opt. peers `@tiptap/react`+`@tiptap/starter-kit`)_ | `RichTextEditor` — themed tiptap v3 rich-text editor with toolbar (tiptap externalized; install it only if you use the editor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

package/bin/lib/alias/collect.mjs

@@ -0,0 +1,94 @@
+// Walk the paths the user asked for and keep the files the codemod can act on.
+import { readdirSync, statSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+
+import { isInsideBase } from "./specifier.mjs";
+
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+const STYLE_EXTS = new Set([".css"]);
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".git",
+    ".vite",
+    ".next",
+    ".turbo",
+]);
+
+/**
+ * Classify a file by extension.
+ *
+ * @param {string} path
+ * @returns {"source" | "style" | null}
+ */
+function kindOf(path) {
+    const ext = extname(path);
+    if (SOURCE_EXTS.has(ext)) return "source";
+    if (STYLE_EXTS.has(ext)) return "style";
+    return null;
+}
+
+/**
+ * Collect the files to rewrite, honoring the positional paths given to the CLI.
+ *
+ * Everything outside the alias base is dropped here as well as in the rewriters:
+ * the walk never leaves the base, so `tempest fix .` on a project root descends
+ * straight into `src/` and skips `vite.config.ts`, `e2e/` and `scripts/` without
+ * needing to open them. A target that is an ancestor of the base is narrowed to
+ * the base; a target that is merely *outside* it yields nothing, so
+ * `tempest fix e2e` rewrites nothing instead of quietly rewriting `src/`.
+ *
+ * Results are sorted so the report — and any diff a reviewer reads — is stable
+ * across runs and platforms.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root; relative targets resolve against it.
+ * @param {string[]} params.targets - Positional paths from the command line.
+ * @param {string} params.baseDir - Absolute alias base directory.
+ * @returns {Array<{ path: string, kind: "source" | "style" }>}
+ */
+export function collectFiles({ root, targets, baseDir }) {
+    const out = new Map();
+
+    const addFile = (path) => {
+        if (out.has(path) || !isInsideBase(path, baseDir)) return;
+        const kind = kindOf(path);
+        if (kind) out.set(path, { path, kind });
+    };
+
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+            if (SKIP_DIRS.has(entry.name)) continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) walk(full);
+            else if (entry.isFile()) addFile(full);
+        }
+    };
+
+    for (const target of targets) {
+        const full = resolve(root, target);
+        let stat;
+        try {
+            stat = statSync(full);
+        } catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            if (full === baseDir || isInsideBase(full, baseDir)) walk(full);
+            else if (isInsideBase(baseDir, full)) walk(baseDir);
+        } else if (stat.isFile()) {
+            addFile(full);
+        }
+    }
+
+    return [...out.values()].sort((a, b) => a.path.localeCompare(b.path));
+}

package/bin/lib/alias/collect.test.mjs

@@ -0,0 +1,95 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { collectFiles } from "./collect.mjs";
+
+let root;
+let baseDir;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-collect-"));
+    baseDir = join(root, "src");
+    for (const rel of [
+        "src/main.tsx",
+        "src/lib/api.ts",
+        "src/lib/api.test.ts",
+        "src/styles/tokens.css",
+        "src/legacy/old.js",
+        "src/legacy/old.mjs",
+        "src/assets/logo.svg",
+        "src/README.md",
+        "src/node_modules/dep/index.ts",
+        "src/.cache/x.ts",
+        "vite.config.ts",
+        "e2e/spec.ts",
+        "dist/bundle.js",
+    ]) {
+        const path = join(root, rel);
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(path, "");
+    }
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+/** Collect and return repo-relative paths with a POSIX separator. */
+function collect(targets) {
+    return collectFiles({ root, targets, baseDir }).map((f) => ({
+        path: relative(root, f.path).split("\\").join("/"),
+        kind: f.kind,
+    }));
+}
+
+describe("collectFiles — extensions", () => {
+    it("keeps source and style files, drops everything else", () => {
+        expect(collect(["."])).toEqual([
+            { path: "src/legacy/old.js", kind: "source" },
+            { path: "src/legacy/old.mjs", kind: "source" },
+            { path: "src/lib/api.test.ts", kind: "source" },
+            { path: "src/lib/api.ts", kind: "source" },
+            { path: "src/main.tsx", kind: "source" },
+            { path: "src/styles/tokens.css", kind: "style" },
+        ]);
+    });
+    it("drops an asset that carries no specifier of its own", () => {
+        expect(collect(["src/assets/logo.svg"])).toEqual([]);
+        expect(collect(["src/README.md"])).toEqual([]);
+    });
+});
+
+describe("collectFiles — scope", () => {
+    it("narrows a project-root target to the alias base", () => {
+        expect(collect(["."]).every((f) => f.path.startsWith("src/"))).toBe(true);
+    });
+    it("restricts to a positional subdirectory", () => {
+        expect(collect(["src/lib"]).map((f) => f.path)).toEqual([
+            "src/lib/api.test.ts",
+            "src/lib/api.ts",
+        ]);
+    });
+    it("accepts a single file target", () => {
+        expect(collect(["src/main.tsx"]).map((f) => f.path)).toEqual(["src/main.tsx"]);
+    });
+    it("yields nothing for a target outside the alias base", () => {
+        expect(collect(["e2e"])).toEqual([]);
+        expect(collect(["vite.config.ts"])).toEqual([]);
+    });
+    it("skips node_modules, dist and dot directories inside the base", () => {
+        const paths = collect(["."]).map((f) => f.path);
+        expect(paths.some((p) => p.includes("node_modules"))).toBe(false);
+        expect(paths.some((p) => p.includes(".cache"))).toBe(false);
+    });
+    it("ignores a target that does not exist", () => {
+        expect(collect(["src/nope"])).toEqual([]);
+    });
+    it("deduplicates overlapping targets", () => {
+        expect(collect(["src/lib", "src/lib/api.ts"]).map((f) => f.path)).toEqual([
+            "src/lib/api.test.ts",
+            "src/lib/api.ts",
+        ]);
+    });
+});

package/bin/lib/alias/discover.mjs

@@ -0,0 +1,77 @@
+// Work out which path alias a project uses (`@/*` → `src/*`) and where its base
+// directory is, so the codemod rewrites to the project's own convention.
+import { statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+import { readTsconfig } from "./tsconfig.mjs";
+
+/** True when `path` exists and is a directory. */
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Pick the first usable `<prefix>/*` → `<dir>/*` mapping from tsconfig `paths`.
+ *
+ * Entries are skipped rather than guessed at when they are ambiguous: more than
+ * one target (the compiler tries each in order, so there is no single directory
+ * to rewrite to), a non-wildcard key, or a target whose directory is missing.
+ * Insertion order decides between several usable entries, so the result is
+ * stable across runs.
+ *
+ * @param {object} paths - Raw `compilerOptions.paths`.
+ * @param {string} baseDir - Directory the targets resolve against.
+ * @returns {{ prefix: string, baseDir: string } | null}
+ */
+function fromPaths(paths, baseDir) {
+    for (const [key, targets] of Object.entries(paths)) {
+        if (!key.endsWith("/*") || !Array.isArray(targets) || targets.length !== 1) continue;
+        const target = targets[0];
+        if (typeof target !== "string" || !target.endsWith("/*")) continue;
+        const dir = resolve(baseDir, target.slice(0, -2));
+        if (!isDir(dir)) continue;
+        return { prefix: key.slice(0, -2), baseDir: dir };
+    }
+    return null;
+}
+
+/**
+ * Discover the alias prefix and its base directory for a project.
+ *
+ * The tsconfig `paths` entry is the *only* accepted source, deliberately: it is
+ * what the type-checker honors, so an alias found there is one `tsc --noEmit`
+ * will accept afterwards. Inferring `@` → `src` from the directory layout was
+ * tried and rejected — a project can perfectly well have a `src/` and no alias
+ * at all (the SDK's own `examples/gallery` is one), and rewriting its imports
+ * would produce specifiers that resolve nowhere.
+ *
+ * `extends` chains and JSONC comments are handled by `readTsconfig`, so a project
+ * that keeps `paths` in a shared base config is still recognized.
+ *
+ * Returning `null` is a normal outcome, not an error: the caller reports it and
+ * leaves the source untouched rather than inventing a convention.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root.
+ * @param {object | null} params.ts - The `typescript` module, or `null`.
+ * @returns {{ prefix: string, baseDir: string, source: "tsconfig" } | null}
+ */
+export function discoverAlias({ root, ts }) {
+    const tsconfig = readTsconfig({ root, ts });
+    const paths = tsconfig?.compilerOptions?.paths;
+    if (!paths || typeof paths !== "object") return null;
+
+    const baseUrl = tsconfig.compilerOptions.baseUrl;
+    const pathsBase =
+        typeof baseUrl === "string"
+            ? isAbsolute(baseUrl)
+                ? baseUrl
+                : resolve(tsconfig.pathsBaseDir, baseUrl)
+            : tsconfig.pathsBaseDir;
+    const found = fromPaths(paths, pathsBase);
+    return found ? { ...found, source: "tsconfig" } : null;
+}

package/bin/lib/alias/discover.test.mjs

@@ -0,0 +1,189 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { discoverAlias } from "./discover.mjs";
+import { readTsconfig } from "./tsconfig.mjs";
+import { loadTypeScript } from "./typescript.mjs";
+
+const ts = loadTypeScript(process.cwd());
+
+let root;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-alias-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+/** Write a file under the fixture root, creating parent directories. */
+function write(rel, contents) {
+    const path = join(root, rel);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, contents);
+}
+
+/** Create a directory under the fixture root. */
+function dir(rel) {
+    mkdirSync(join(root, rel), { recursive: true });
+}
+
+describe("readTsconfig", () => {
+    it("returns null when there is no tsconfig", () => {
+        expect(readTsconfig({ root, ts })).toBeNull();
+    });
+    it("reads plain JSON", () => {
+        write("tsconfig.json", JSON.stringify({ compilerOptions: { strict: true } }));
+        expect(readTsconfig({ root, ts }).compilerOptions.strict).toBe(true);
+    });
+    it("reads JSONC — comments and trailing commas", () => {
+        write(
+            "tsconfig.json",
+            `{
+    // the alias the SDK expects
+    "compilerOptions": {
+        "moduleResolution": "bundler", /* keeps subpath types resolvable */
+        "paths": { "@/*": ["./src/*"] },
+    },
+}`,
+        );
+        const cfg = readTsconfig({ root, ts });
+        expect(cfg.compilerOptions.moduleResolution).toBe("bundler");
+        expect(cfg.compilerOptions.paths).toEqual({ "@/*": ["./src/*"] });
+    });
+    it("keeps option values raw instead of normalizing them to enums", () => {
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { moduleResolution: "bundler", jsx: "react-jsx" } }),
+        );
+        const { compilerOptions } = readTsconfig({ root, ts });
+        expect(compilerOptions.moduleResolution).toBe("bundler");
+        expect(compilerOptions.jsx).toBe("react-jsx");
+    });
+    it("merges the extends chain with the extending file winning", () => {
+        write(
+            "tsconfig.base.json",
+            JSON.stringify({ compilerOptions: { strict: false, skipLibCheck: true } }),
+        );
+        write(
+            "tsconfig.json",
+            JSON.stringify({ extends: "./tsconfig.base.json", compilerOptions: { strict: true } }),
+        );
+        const { compilerOptions } = readTsconfig({ root, ts });
+        expect(compilerOptions.strict).toBe(true);
+        expect(compilerOptions.skipLibCheck).toBe(true);
+    });
+    it("resolves extends without the .json extension", () => {
+        write("base.json", JSON.stringify({ compilerOptions: { skipLibCheck: true } }));
+        write("tsconfig.json", JSON.stringify({ extends: "./base" }));
+        expect(readTsconfig({ root, ts }).compilerOptions.skipLibCheck).toBe(true);
+    });
+    it("falls back to JSON.parse when typescript is unavailable", () => {
+        write("tsconfig.json", JSON.stringify({ compilerOptions: { strict: true } }));
+        expect(readTsconfig({ root, ts: null }).compilerOptions.strict).toBe(true);
+    });
+    it("returns null for unparseable JSON without typescript", () => {
+        write("tsconfig.json", "{ not json");
+        expect(readTsconfig({ root, ts: null })).toBeNull();
+    });
+});
+
+describe("discoverAlias — from tsconfig paths", () => {
+    it("finds the @/* → src/* mapping", () => {
+        dir("src");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "@/*": ["./src/*"] } } }),
+        );
+        expect(discoverAlias({ root, ts })).toEqual({
+            prefix: "@",
+            baseDir: join(root, "src"),
+            source: "tsconfig",
+        });
+    });
+    it("honours a non-@ prefix", () => {
+        dir("src");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "~/*": ["./src/*"] } } }),
+        );
+        expect(discoverAlias({ root, ts }).prefix).toBe("~");
+    });
+    it("honours an app/ base", () => {
+        dir("app");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "@/*": ["./app/*"] } } }),
+        );
+        expect(discoverAlias({ root, ts }).baseDir).toBe(join(root, "app"));
+    });
+    it("resolves paths against baseUrl when one is set", () => {
+        dir("client/src");
+        write(
+            "tsconfig.json",
+            JSON.stringify({
+                compilerOptions: { baseUrl: "./client", paths: { "@/*": ["./src/*"] } },
+            }),
+        );
+        expect(discoverAlias({ root, ts }).baseDir).toBe(join(root, "client", "src"));
+    });
+    it("finds paths inherited through extends, resolved against the declaring file", () => {
+        dir("src");
+        write(
+            "tsconfig.base.json",
+            JSON.stringify({ compilerOptions: { paths: { "@/*": ["./src/*"] } } }),
+        );
+        write("tsconfig.json", JSON.stringify({ extends: "./tsconfig.base.json" }));
+        expect(discoverAlias({ root, ts })).toEqual({
+            prefix: "@",
+            baseDir: join(root, "src"),
+            source: "tsconfig",
+        });
+    });
+    it("skips an ambiguous entry with several targets", () => {
+        dir("src");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "@/*": ["./src/*", "./generated/*"] } } }),
+        );
+        expect(discoverAlias({ root, ts })).toBeNull();
+    });
+    it("skips a non-wildcard entry", () => {
+        dir("src");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "@shared": ["./src/shared.ts"] } } }),
+        );
+        expect(discoverAlias({ root, ts })).toBeNull();
+    });
+    it("skips an entry whose target directory does not exist", () => {
+        dir("src");
+        write(
+            "tsconfig.json",
+            JSON.stringify({
+                compilerOptions: { paths: { "#/*": ["./nope/*"], "@/*": ["./src/*"] } },
+            }),
+        );
+        expect(discoverAlias({ root, ts })).toMatchObject({ prefix: "@", source: "tsconfig" });
+    });
+});
+
+describe("discoverAlias — refuses to guess", () => {
+    it("returns null when a src/ exists but nothing declares an alias", () => {
+        dir("src");
+        expect(discoverAlias({ root, ts })).toBeNull();
+    });
+    it("returns null when there is no tsconfig at all", () => {
+        dir("src");
+        dir("app");
+        expect(discoverAlias({ root, ts })).toBeNull();
+    });
+    it("returns null when the tsconfig declares no paths", () => {
+        dir("src");
+        write("tsconfig.json", JSON.stringify({ compilerOptions: { strict: true } }));
+        expect(discoverAlias({ root, ts })).toBeNull();
+    });
+});

package/bin/lib/alias/index.mjs

@@ -0,0 +1,88 @@
+// The `tempest fix` alias pass: discover the convention, rewrite the files,
+// report what changed.
+import { readFileSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+
+import { collectFiles } from "./collect.mjs";
+import { discoverAlias } from "./discover.mjs";
+import { rewriteCss } from "./rewrite-css.mjs";
+import { rewriteSource } from "./rewrite.mjs";
+import { loadTypeScript } from "./typescript.mjs";
+
+export { collectFiles } from "./collect.mjs";
+export { discoverAlias } from "./discover.mjs";
+export { rewriteCss } from "./rewrite-css.mjs";
+export { rewriteSource } from "./rewrite.mjs";
+export { isInsideBase, toAlias } from "./specifier.mjs";
+export { readTsconfig } from "./tsconfig.mjs";
+export { loadTypeScript } from "./typescript.mjs";
+
+/**
+ * Convert relative imports that climb out of their directory into alias imports.
+ *
+ * Reports instead of throwing when the project is not set up for it — no
+ * TypeScript installed, no alias discoverable. Both are "nothing to do", not
+ * failures, so the surrounding `fix` keeps its exit code and still runs ESLint
+ * and Prettier.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root.
+ * @param {string[]} params.targets - Positional paths from the command line.
+ * @param {boolean} [params.dryRun] - Report the changes without writing them.
+ * @returns {{
+ *   status: "ok" | "no-typescript" | "no-alias" | "error",
+ *   prefix?: string,
+ *   baseDir?: string,
+ *   files: Array<{ path: string, changes: Array<{ from: string, to: string, line: number }> }>,
+ *   total: number,
+ *   errors: Array<{ path: string, message: string }>,
+ * }}
+ */
+export function aliasImports({ root, targets, dryRun = false }) {
+    const empty = { files: [], total: 0, errors: [] };
+
+    const ts = loadTypeScript(root);
+    if (!ts) return { status: "no-typescript", ...empty };
+
+    const alias = discoverAlias({ root, ts });
+    if (!alias) return { status: "no-alias", ...empty };
+
+    const { prefix, baseDir } = alias;
+    const files = [];
+    const errors = [];
+    let total = 0;
+
+    for (const { path, kind } of collectFiles({ root, targets, baseDir })) {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        } catch (err) {
+            errors.push({ path: relative(root, path), message: String(err?.message ?? err) });
+            continue;
+        }
+        const result =
+            kind === "style"
+                ? rewriteCss({ text, filePath: path, prefix, baseDir })
+                : rewriteSource({ text, filePath: path, prefix, baseDir, ts });
+        if (!result.changes.length) continue;
+        if (!dryRun) {
+            try {
+                writeFileSync(path, result.text);
+            } catch (err) {
+                errors.push({ path: relative(root, path), message: String(err?.message ?? err) });
+                continue;
+            }
+        }
+        files.push({ path: relative(root, path), changes: result.changes });
+        total += result.changes.length;
+    }
+
+    return {
+        status: errors.length ? "error" : "ok",
+        prefix,
+        baseDir,
+        files,
+        total,
+        errors,
+    };
+}