@akanjs/devkit 3.1.0-rc.2 → 3.1.0-rc.20

package/commandDecorators/command.ts

@@ -186,20 +186,21 @@ const assignCommandContext = (context: CommandContext, argMeta: ArgMeta | Intern
   else context.values[argMeta.type.toLowerCase()] = value;
 };
 
+//? Not `.env`, which a fresh clone lacks; an app or a package folder has a package.json and tsconfig.json of its own.
 const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   const cwd = process.cwd();
-  const [hasPackageJson, hasTsConfig, hasEnv] = await Promise.all([
+  const [hasPackageJson, hasTsConfig, ...hasMemberDirs] = await Promise.all([
     FileSys.fileExists(`${cwd}/package.json`),
     FileSys.fileExists(`${cwd}/tsconfig.json`),
-    FileSys.fileExists(`${cwd}/.env`),
+    ...["apps", "libs", "pkgs"].map((dir) => FileSys.dirExists(`${cwd}/${dir}`)),
   ]);
-  if (hasPackageJson && hasTsConfig && hasEnv) return;
+  if (hasPackageJson && hasTsConfig && hasMemberDirs.some(Boolean)) return;
 
   throw new Error(
     [
       "Akan CLI commands must be run from the workspace root.",
       `Current directory: ${cwd}`,
-      "Move to the directory that contains package.json, tsconfig.json, and .env, then run the command again.",
+      "Move to the directory that contains package.json, tsconfig.json, and an apps/, libs/ or pkgs/ folder, then run the command again.",
     ].join("\n"),
   );
 };

package/createTunnel.test.ts

@@ -48,4 +48,18 @@ describe("createTunnel", () => {
       expect(failure.message).toContain(reason.message);
     }
   });
+
+  test("refuses to dial a cluster host built on the local default serve domain", async () => {
+    const { app } = track(await createTempApp("demo"));
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    const connect = spyOn(Client.prototype, "connect");
+    try {
+      await expect(createTunnel("redis", { app, environment: "debug" })).rejects.toThrow(
+        'The redis tunnel for the "debug" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+      );
+      expect(connect).not.toHaveBeenCalled();
+    } finally {
+      connect.mockRestore();
+    }
+  });
 });

package/createTunnel.ts

@@ -10,7 +10,9 @@ export const createTunnel = async (
   service: "redis" | "postgres",
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
-  const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
+  const baseDevEnv = WorkspaceExecutor.getBaseDevEnv();
+  WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, `The ${service} tunnel`);
+  const { serveDomain, repoName } = baseDevEnv;
   const host = `${app.name}-${environment}.${serveDomain}`;
   const sshPort = process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767;
   const dstHost = `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`;

package/dependencyScanner.ts

@@ -107,7 +107,7 @@ export class TypeScriptDependencyScanner {
     return {
       npmDeps: [...runtimeDeps].sort(),
       npmDevDeps: [...devDeps].sort(),
-      missingDeps: missingDeps.sort(),
+      missingDeps: missingDeps.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
     };
   }
 

package/devkitUtils.test.ts

@@ -76,7 +76,7 @@ describe("TypeScriptDependencyScanner", () => {
     });
     expect(deps.pkgDeps).toEqual(["akanjs/tool"]);
     expect(deps.libDeps).toEqual(["shared"]);
-    expect(deps.npmDeps.sort()).toEqual(["lodash", "react"]);
+    expect(deps.npmDeps.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(["lodash", "react"]);
     expect(deps.npmDevDeps).toEqual(["typescript"]);
 
     const graph = scanner.generateDependencyGraph();

package/executors.test.ts

@@ -99,6 +99,29 @@ describe("Executor filesystem helpers", () => {
     expect(entries.dirs).toContain("nested");
   });
 
+  test("lists a folder in name order, whatever order the filesystem keeps it in", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    for (const name of ["summary", "file", "banner", "_noti", "admin"]) await exec.mkdir(`lib/${name}`);
+    for (const name of ["st.ts", "cnst.ts", "dict.ts"]) await exec.writeFile(`lib/${name}`, "");
+
+    expect(await exec.readdir("lib")).toEqual([
+      "_noti",
+      "admin",
+      "banner",
+      "cnst.ts",
+      "dict.ts",
+      "file",
+      "st.ts",
+      "summary",
+    ]);
+    expect(await exec.getFilesAndDirs("lib")).toEqual({
+      files: ["cnst.ts", "dict.ts", "st.ts"],
+      dirs: ["_noti", "admin", "banner", "file", "summary"],
+    });
+    expect(await exec.getAllFiles("**/*", { cwd: exec.getPath("lib") })).toEqual(["cnst.ts", "dict.ts", "st.ts"]);
+  });
+
   test("a refreshed tsconfig re-reads the config it extends", async () => {
     const root = await makeTempRoot();
     const appDir = path.join(root, "apps/demo");
@@ -312,7 +335,7 @@ describe("Executor filesystem helpers", () => {
 });
 
 describe("Workspace and app executor environment contracts", () => {
-  test("reads base development environment and reports required missing values", () => {
+  test("reads base development environment", () => {
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
     process.env.AKAN_PUBLIC_ENV = "local";
@@ -328,10 +351,53 @@ describe("Workspace and app executor environment contracts", () => {
       env: "local",
       portOffset: 10,
       workspaceId: undefined,
+      defaulted: [],
     });
+  });
 
-    delete process.env.AKAN_PUBLIC_REPO_NAME;
-    expect(() => WorkspaceExecutor.getBaseDevEnv()).toThrow("AKAN_PUBLIC_REPO_NAME is not set");
+  test("unset, the repo name is the origin remote's and the serve domain localhost, both marked defaulted", async () => {
+    const root = await makeTempRoot();
+    for (const args of [
+      ["init", "-q"],
+      ["remote", "add", "origin", "git@github.com:akan-team/fixture-repo.git"],
+    ])
+      expect(Bun.spawnSync(["git", ...args], { cwd: root }).exitCode).toBe(0);
+    for (const key of ["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN", "AKAN_PUBLIC_ENV", "AKAN_WORKSPACE_ROOT"])
+      delete process.env[key];
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      repoName: "fixture-repo",
+      serveDomain: "localhost",
+      env: "debug",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"],
+    });
+
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      repoName: "fixture-repo",
+      serveDomain: "example.com",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME"],
+    });
+  });
+
+  test("a build or tunnel for a real environment refuses a defaulted value, and a local one takes it", () => {
+    const baseDevEnv = {
+      repoName: "fixture-repo",
+      serveDomain: "localhost",
+      env: "debug" as const,
+      portOffset: 0,
+      workspaceRoot: undefined,
+    };
+    const defaulted = { ...baseDevEnv, defaulted: ["AKAN_PUBLIC_SERVE_DOMAIN" as const] };
+
+    expect(() => WorkspaceExecutor.assertDeployableEnv(defaulted, "main", "akan build")).toThrow(
+      'akan build for the "main" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+    );
+    expect(() => WorkspaceExecutor.assertDeployableEnv(defaulted, "local", "akan build")).not.toThrow();
+    expect(() =>
+      WorkspaceExecutor.assertDeployableEnv({ ...baseDevEnv, defaulted: [] }, "main", "akan build"),
+    ).not.toThrow();
+    expect(() => WorkspaceExecutor.assertDeployableEnv(baseDevEnv, "main", "akan build")).not.toThrow();
   });
 
   test("reads base development environment from an explicit env file", async () => {
@@ -359,6 +425,7 @@ describe("Workspace and app executor environment contracts", () => {
       env: "develop",
       portOffset: 7,
       workspaceId: undefined,
+      defaulted: [],
     });
   });
 
@@ -417,6 +484,21 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  test("the app command env hands the dev server the local defaults that stood in for unset values", async () => {
+    const root = await makeTempRoot();
+    delete process.env.AKAN_PUBLIC_REPO_NAME;
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    process.env.AKAN_WORKSPACE_ROOT = root;
+    const app = AppExecutor.from(new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }), "defaults");
+
+    const env = app.getCommandEnv();
+    expect(env.AKAN_PUBLIC_SERVE_DOMAIN).toBe("localhost");
+    expect(env.AKAN_PUBLIC_REPO_NAME).toBe(WorkspaceExecutor.getBaseDevEnv().repoName);
+
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    expect(app.getCommandEnv().AKAN_PUBLIC_SERVE_DOMAIN).toBe("example.com");
+  });
+
   test("akan start clears the dev output and keeps the bin downloads and a native folder from before dist/native", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";

package/executors.ts

@@ -54,7 +54,7 @@ import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
 import type { TypeChecker } from "./typeChecker";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
-import type { FileContent, PackageJson, TsConfigJson } from "./types";
+import type { BaseDevEnv, FileContent, PackageJson, TsConfigJson } from "./types";
 import { barrelFacetDirs } from "./workspaceLayout";
 
 export interface PageRoot {
@@ -271,20 +271,20 @@ export class Executor {
     const readPath = this.getPath(dirPath);
     try {
       const glob = new Bun.Glob("*");
-      return Array.from(glob.scanSync({ cwd: readPath, onlyFiles: false }));
+      return Array.from(glob.scanSync({ cwd: readPath, onlyFiles: false })).sort();
     } catch {
       return [];
     }
   }
   async getAllFiles(pattern = "**/*", { cwd }: { cwd?: string } = {}): Promise<string[]> {
     const glob = new Bun.Glob(pattern);
-    return Array.from(glob.scanSync({ cwd: cwd ?? this.cwdPath, onlyFiles: true }));
+    return Array.from(glob.scanSync({ cwd: cwd ?? this.cwdPath, onlyFiles: true })).sort();
   }
   async getFilesAndDirs(dirPath: string): Promise<{ files: string[]; dirs: string[] }> {
     const fullDirPath = this.getPath(dirPath);
     const glob = new Bun.Glob("*");
-    const files = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: true }));
-    const allEntries = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: false }));
+    const files = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: true })).sort();
+    const allEntries = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: false })).sort();
     const dirs = allEntries.filter((entry) => !files.includes(entry));
     return { files, dirs };
   }
@@ -662,6 +662,7 @@ export class WorkspaceExecutor extends Executor {
   }
   /** The public env a native build was told to reproduce (`--public-env`): it outranks `.env`, which outranks the rest. */
   static publicEnvPin: Record<string, string> | null = null;
+  static readonly localServeDomain = "localhost";
   static getBaseDevEnv(envPath?: string) {
     // Bun auto-loads .env, so we use process.env directly
     const sourceEnv = {
@@ -673,11 +674,11 @@ export class WorkspaceExecutor extends Executor {
     const workspaceRoot = sourceEnv.AKAN_WORKSPACE_ROOT;
     const workspaceId = sourceEnv.AKAN_WORKSPACE_ID;
 
-    const repoName = sourceEnv.AKAN_PUBLIC_REPO_NAME;
-    if (!repoName) throw new Error("AKAN_PUBLIC_REPO_NAME is not set");
-
-    const serveDomain = sourceEnv.AKAN_PUBLIC_SERVE_DOMAIN;
-    if (!serveDomain) throw new Error("AKAN_PUBLIC_SERVE_DOMAIN is not set");
+    const repoName =
+      sourceEnv.AKAN_PUBLIC_REPO_NAME ||
+      resolveRepoName(envPath ? path.dirname(envPath) : (workspaceRoot ?? process.cwd()));
+    const serveDomain = sourceEnv.AKAN_PUBLIC_SERVE_DOMAIN || WorkspaceExecutor.localServeDomain;
+    const defaulted = (["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const).filter((key) => !sourceEnv[key]);
 
     const portOffset = parseInt(sourceEnv.PORT_OFFSET ?? "0");
 
@@ -697,8 +698,20 @@ export class WorkspaceExecutor extends Executor {
       env,
       portOffset,
       workspaceId,
+      defaulted,
     };
   }
+  //? A build or tunnel for a real environment carries these into an image, a bundle or a host name it dials.
+  static assertDeployableEnv(baseDevEnv: BaseDevEnv, environment: string, purpose: string) {
+    const defaulted = environment === "local" ? [] : (baseDevEnv.defaulted ?? []);
+    if (!defaulted.length) return;
+    const values = { AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName, AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain };
+    const standIns = defaulted.map((key) => `${key} (would be "${values[key]}")`).join(" and ");
+    throw new Error(
+      `${purpose} for the "${environment}" environment needs ${standIns} set, not a local default. ` +
+        `Set ${defaulted.length > 1 ? "them" : "it"} in the workspace .env or the shell, or use AKAN_PUBLIC_ENV=local.`,
+    );
+  }
   getWorkspaceId<AllowEmpty extends boolean = false>({
     allowEmpty,
   }: {
@@ -1159,10 +1172,12 @@ export class AppExecutor extends SysExecutor {
     return basePort + appIndex + portOffset;
   }
   getCommandEnv(env: Record<string, string> = {}): Record<string, string> {
-    const { portOffset } = WorkspaceExecutor.getBaseDevEnv();
+    const { portOffset, repoName, serveDomain } = WorkspaceExecutor.getBaseDevEnv();
     const PORT = (8282 + portOffset).toString();
     return {
       ...process.env,
+      AKAN_PUBLIC_REPO_NAME: repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: serveDomain,
       AKAN_PUBLIC_APP_NAME: this.name,
       AKAN_WORKSPACE_ROOT: this.workspace.workspaceRoot,
       NODE_NO_WARNINGS: "1",
@@ -1323,7 +1338,7 @@ export class AppExecutor extends SysExecutor {
         pageKeys.push(key);
       }
     }
-    pageKeys.sort();
+    pageKeys.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     this.#pageKeys = this.#excludeDevOnlyPages ? this.#dropDevOnlyPages(pageKeys, devOnlyKeys, devOnlyDirs) : pageKeys;
     return this.#pageKeys;
   }
@@ -1581,7 +1596,9 @@ export class PkgExecutor extends Executor {
     devDependencies: string[] = [],
   ): Promise<Pick<PackageJson, "dependencies" | "devDependencies">> {
     const dependencyNames = [...new Set(dependencies)].sort();
-    const devDependencyNames = [...new Set(devDependencies)].filter((dep) => !dependencyNames.includes(dep)).sort();
+    const devDependencyNames = [...new Set(devDependencies)]
+      .filter((dep) => !dependencyNames.includes(dep))
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     const dependencyVersions = new Map<string, string>();
     const missingDeps: string[] = [];
     for (const dep of [...dependencyNames, ...devDependencyNames]) {

package/frontendBuild/autoImportSync.test.ts

@@ -253,7 +253,9 @@ describe("AutoImportSync.syncForBatch", () => {
 
     const result = await sync.syncForBatch([uiFile, pageFile, webkitFile]);
     expect(result.errors).toEqual([]);
-    expect(result.changedFiles.sort()).toEqual([pageFile, webkitFile, uiFile].sort());
+    expect(result.changedFiles.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(
+      [pageFile, webkitFile, uiFile].sort(),
+    );
     expect(await readFile(uiFile, "utf8")).toContain(`import { st } from "@apps/akan/client";`);
     expect(await readFile(pageFile, "utf8")).toContain(`import { cnst } from "@apps/akan/client";`);
     expect(await readFile(webkitFile, "utf8")).toContain(`import { fetch } from "@libs/shared/client";`);

package/frontendBuild/clientEntryDiscovery.ts

@@ -6,7 +6,7 @@ import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
 import type { AkanConfig, ClientEntryDiscovery, ScannedImport } from "./clientBuildTypes";
 
-const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
+const USE_CLIENT_RE = /^\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
 const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
 // Bun's scanImports also surfaces CSS and asset imports, none of which can be a client component.

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText } from "../testHelpers";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
 
 const makeTempRoot = tempDirs("akan-csr-artifact-");
 
@@ -31,4 +32,33 @@ console.info(await result.outputs[0].text());
     expect(stdout).toContain("envmark:debug");
     expect(stdout).not.toContain("envmark:local");
   });
+
+  //? An OTA release is keyed on the bundle's hash, so a no-op build from another checkout must not stage one.
+  test("bundles the same app identically from two checkout paths", async () => {
+    const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: "main" }) };
+    const buildFrom = async (root: string) => {
+      await writeText(
+        path.join(root, "node_modules/wasmdep/package.json"),
+        '{ "name": "wasmdep", "main": "index.js" }\n',
+      );
+      await writeText(
+        path.join(root, "node_modules/wasmdep/index.js"),
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: the fixture module's own source holds a template literal
+        'var isNode = typeof process == "object" && !!process.versions?.node;\nmodule.exports = isNode ? `${__dirname}/` : "";\n',
+      );
+      await writeText(path.join(root, "entry.ts"), 'import dir from "wasmdep";\nconsole.info(dir);\n');
+      const result = await Bun.build({
+        ...CsrArtifactBuilder.bundleOptions(app as never, "build"),
+        entrypoints: [path.join(root, "entry.ts")],
+      });
+      expect(result.success).toBe(true);
+      return await result.outputs[0]?.text();
+    };
+    const [first, second] = [await makeTempRoot(), await makeTempRoot()];
+
+    const [firstOutput, secondOutput] = [await buildFrom(first), await buildFrom(second)];
+
+    expect(firstOutput).toBe(secondOutput);
+    expect(firstOutput).not.toContain(path.basename(first));
+  });
 });

package/frontendBuild/csrArtifactBuilder.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
@@ -90,7 +91,7 @@ export class CsrArtifactBuilder {
       define: bundleDefine(app, command, "csr"),
       optimizeImports,
       // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
-      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+      plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin()],
     };
   }
 
@@ -234,7 +235,7 @@ void bootCsr(pages);
     for await (const filePath of glob.scan({ cwd: this.#outputDir, absolute: true })) {
       if (predicate(filePath)) files.push(filePath);
     }
-    return files.sort();
+    return files.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   }
 
   // Bun hoists the module script into <head> and a React bundle contains "</head>" as text, so positions come from a
@@ -248,9 +249,10 @@ void bootCsr(pages);
     return `${html}\n${snippet}`;
   }
 
+  // An unclosed body runs to EOF, as the HTML tokenizer reads it; that also keeps the scan linear.
   static blankEmbeddedContent(html: string): string {
     return html.replace(
-      /<script\b[^>]*>[\s\S]*?<\/script\s*>|<style\b[^>]*>[\s\S]*?<\/style\s*>|<!--[\s\S]*?-->/gi,
+      /<script\b[^>]*>[\s\S]*?(?:<\/script(?:[\s/][^<>]*)?>|$)|<style\b[^>]*>[\s\S]*?(?:<\/style(?:[\s/][^<>]*)?>|$)|<!--[\s\S]*?(?:--!?>|$)/gi,
       (match) => " ".repeat(match.length),
     );
   }

package/frontendBuild/csrDevPatcher.test.ts

@@ -379,7 +379,10 @@ describe("CsrDevPatcher", () => {
     await expect(patcher.update([], { roots: [file("ui/E1.tsx")], onlyRoots: true })).rejects.toThrow();
     await expect(patcher.update([], { roots: [file("ui/E4.tsx")], onlyRoots: true })).rejects.toThrow();
     const graph = (await bundler.writer.readJson<CsrDevGraph>("graph.json")) as CsrDevGraph;
-    expect(graph.pending.sort()).toEqual(["apps/demo/ui/E1.tsx", "apps/demo/ui/E4.tsx"]);
+    expect(graph.pending.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "apps/demo/ui/E1.tsx",
+      "apps/demo/ui/E4.tsx",
+    ]);
   });
 
   test("a route's check that adds its own root leaves another route's failed root pending", async () => {

package/frontendBuild/cssBlockParser.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import { type CssBlock, CssBlockParser, type CssNode } from "./cssBlockParser";
+
+const blocksOf = (block: CssBlock) => block.nodes.filter((node): node is CssBlock => node.kind === "block");
+const declarationsOf = (block: CssBlock) =>
+  block.nodes.flatMap((node) => (node.kind === "declaration" ? [[node.property, node.value]] : []));
+
+const expectLinear = (run: () => unknown) => {
+  const started = performance.now();
+  run();
+  expect(performance.now() - started).toBeLessThan(1000);
+};
+
+describe("CssBlockParser.parse", () => {
+  test("reads consecutive blocks with their preludes and declarations", () => {
+    const root = CssBlockParser.parse(`a { --x: 1; } b { --y: 2 } c{--z:3}`);
+    expect(blocksOf(root).map((block) => block.prelude)).toEqual(["a", "b", "c"]);
+    expect(blocksOf(root).map(declarationsOf)).toEqual([[["--x", "1"]], [["--y", "2"]], [["--z", "3"]]]);
+  });
+
+  test("nests at-rules and nested rules, keeping a block's own declarations apart from its children's", () => {
+    const root = CssBlockParser.parse(
+      `@media (min-width: 1px) { :root { --a: 1; } } .card { color: red; &:hover { color: blue; } --b: 2; }`,
+    );
+    const [media, card] = blocksOf(root);
+    expect(media.atRule).toBe("@media");
+    expect(media.prelude).toBe("@media (min-width: 1px)");
+    expect(declarationsOf(blocksOf(media)[0])).toEqual([["--a", "1"]]);
+    expect(card.atRule).toBeNull();
+    expect(declarationsOf(card)).toEqual([
+      ["color", "red"],
+      ["--b", "2"],
+    ]);
+    expect(blocksOf(card).map((block) => block.prelude)).toEqual(["&:hover"]);
+  });
+
+  test("treats at-rule statements as neither blocks nor declarations", () => {
+    const root = CssBlockParser.parse(
+      `@source "./**/*";\n@import "tailwindcss";\n@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));\n:root { --a: 1; }`,
+    );
+    expect(root.nodes).toEqual([
+      { kind: "block", prelude: ":root", atRule: null, nodes: [{ kind: "declaration", property: "--a", value: "1" }] },
+    ]);
+  });
+
+  test("ignores braces, semicolons and comment markers inside strings, comments and escapes", () => {
+    const root = CssBlockParser.parse(
+      [
+        `/* :root { --commented: 1; } */`,
+        `.a::before { content: "} ; /* {"; --q: 'x;y'; }`,
+        `.w-\\[10px\\]\\{ { --escaped: 1; }`,
+        `.b { background: url(data:image/png;base64,AAAA); --after: 2; }`,
+      ].join("\n"),
+    );
+    expect(blocksOf(root).map((block) => block.prelude)).toEqual([".a::before", ".w-\\[10px\\]\\{", ".b"]);
+    expect(blocksOf(root).map(declarationsOf)).toEqual([
+      [
+        ["content", `"} ; /* {"`],
+        ["--q", "'x;y'"],
+      ],
+      [["--escaped", "1"]],
+      [
+        ["background", "url(data:image/png;base64,AAAA)"],
+        ["--after", "2"],
+      ],
+    ]);
+  });
+
+  test("drops comments from preludes and values", () => {
+    const root = CssBlockParser.parse(`/* lead */ :root /* mid */ , [data-theme="dark"] { --a: /* x */ #fff; }`);
+    const [block] = blocksOf(root);
+    expect(block.prelude).toBe(`:root  , [data-theme="dark"]`);
+    expect(declarationsOf(block)).toEqual([["--a", "#fff"]]);
+  });
+
+  test("closes what the input leaves open and tolerates a stray closing brace", () => {
+    const root = CssBlockParser.parse(`} :root { --a: 1; .x { --b: 2`);
+    const [rootBlock] = blocksOf(root);
+    expect(declarationsOf(rootBlock)).toEqual([["--a", "1"]]);
+    expect(declarationsOf(blocksOf(rootBlock)[0])).toEqual([["--b", "2"]]);
+    expect(CssBlockParser.parse(`.a { content: "unterminated\n--b: 2; }`).nodes).toHaveLength(1);
+    expect(CssBlockParser.parse(`.a { --b: 1 } /* unterminated`).nodes).toHaveLength(1);
+  });
+});
+
+describe("CssBlockParser.walk", () => {
+  test("visits in source order, passing each block's context to its children", () => {
+    const root = CssBlockParser.parse(
+      `.a { --x: 1; @media m { --y: 2; } --z: 3; } @theme { --skipped: 1; } .b { --w: 4 }`,
+    );
+    const visited: string[] = [];
+    CssBlockParser.walk(root, "", (node: CssNode, path: string) => {
+      if (node.kind === "declaration") {
+        visited.push(`${path}${node.property}`);
+        return null;
+      }
+      return node.atRule === "@theme" ? null : `${path}${node.prelude}>`;
+    });
+    expect(visited).toEqual([".a>--x", ".a>@media m>--y", ".a>--z", ".b>--w"]);
+  });
+
+  test("walks a deeply nested tree without recursion", () => {
+    const root = CssBlockParser.parse(`${"@media x{".repeat(100_000)}:root{--deep:1}`);
+    let found = "";
+    CssBlockParser.walk(root, true, (node) => {
+      if (node.kind === "declaration") found = node.property;
+      return true;
+    });
+    expect(found).toBe("--deep");
+  });
+});
+
+describe("CssBlockParser linear time", () => {
+  test("adversarial runs finish well under a second", () => {
+    expectLinear(() => CssBlockParser.parse(`}${" ".repeat(100_000)}`));
+    expectLinear(() => CssBlockParser.parse(`:root{${"--".repeat(100_000)}`));
+    expectLinear(() => CssBlockParser.parse("@theme".repeat(100_000)));
+    expectLinear(() => CssBlockParser.parse("/*".repeat(100_000)));
+    expectLinear(() => CssBlockParser.parse(`"${"\\".repeat(100_000)}`));
+    expectLinear(() => CssBlockParser.parse("(".repeat(100_000)));
+    expectLinear(() => CssBlockParser.parse(":root{--a:#fff}".repeat(100_000)));
+  });
+});