@akanjs/devkit 2.4.1-rc.1 → 2.4.1-rc.2

package/index.ts

@@ -39,6 +39,7 @@ export type * from "./getRelatedCnsts";
 export type * from "./guideline";
 export type * from "./incrementalBuilder";
 export type * from "./mobile";
+export type * from "./packageExportsMap";
 export type * from "./prompter";
 export type * from "./qualityScanner";
 export type * from "./scanInfo";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.1-rc.1",
+  "version": "2.4.1-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.1-rc.1",
+    "akanjs": "2.4.1-rc.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/packageExports.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { PackageExportsMap } from "@akanjs/devkit/packageExportsMap";
+
+// Guards the published shape of this package, which the monorepo cannot exercise on its own.
+//
+// Inside the monorepo Bun resolves `@akanjs/devkit/executors` through the root tsconfig `paths`
+// (`@akanjs/devkit/*` -> `pkgs/@akanjs/devkit/*`), and that resolver probes extensions and directory
+// indexes. A published consumer has no such mapping: it goes through this package's `exports` map,
+// whose targets are matched *exactly*. So `"./*": "./*"` type-checked, built, and passed every test
+// here while every subpath import failed at runtime for anyone installing the tarball:
+//
+//   error: Cannot find module '@akanjs/devkit/executors' from
+//     '<consumer>/node_modules/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts'
+//
+// `PackageRunner.verifyDistPackage` runs the same check against the built dist tree of every
+// publishable package at release time; these tests keep this package honest on every run.
+
+const packageDir = import.meta.dir;
+const exportsMap = await PackageExportsMap.from(packageDir);
+
+/** Every facet the root barrel re-exports, as the subpath a consumer would import. */
+const barrelFacets = async (): Promise<string[]> => {
+  const barrel = await Bun.file(path.join(packageDir, "index.ts")).text();
+  return [...barrel.matchAll(/^export (?:type )?\* from "\.\/([^"]+)";$/gm)].map((match) => `./${match[1]}`);
+};
+
+/** Every `@akanjs/devkit/<subpath>` specifier written anywhere in the two packages that use them. */
+const importedSubpaths = async (): Promise<string[]> => {
+  const repoRoot = path.resolve(packageDir, "../../..");
+  const glob = new Bun.Glob("pkgs/@akanjs/{cli,devkit}/**/*.{ts,tsx}");
+  const found = new Set<string>();
+  for await (const relative of glob.scan({ cwd: repoRoot })) {
+    if (relative.includes("node_modules/") || relative.includes("/dist/")) continue;
+    const source = await Bun.file(path.join(repoRoot, relative)).text();
+    for (const match of source.matchAll(/"@akanjs\/devkit\/([a-zA-Z0-9_./-]+)"/g)) found.add(`./${match[1]}`);
+  }
+  return [...found].sort();
+};
+
+describe("published exports map", () => {
+  test("resolves every facet the root barrel re-exports", async () => {
+    const facets = await barrelFacets();
+    expect(facets.length).toBeGreaterThan(30);
+    expect(exportsMap.findUnreachable(facets)).toEqual([]);
+  });
+
+  test("resolves every subpath the monorepo actually imports", async () => {
+    const subpaths = await importedSubpaths();
+    expect(subpaths.length).toBeGreaterThan(20);
+    expect(exportsMap.findUnreachable(subpaths)).toEqual([]);
+  });
+
+  test("covers both facet shapes and keeps explicit extensions intact", () => {
+    // A single wildcard cannot serve all three: `./*` -> `./*.ts` reaches bare files, directory
+    // facets need their own literal entry, and `./*.ts` -> `./*.ts` keeps an already-suffixed
+    // specifier from becoming `./cloud/cloudApi.ts.ts`.
+    expect(exportsMap.resolve("./executors")).toBe("./executors.ts");
+    expect(exportsMap.resolve("./frontendBuild")).toBe("./frontendBuild/index.ts");
+    expect(exportsMap.resolve("./cloud/cloudApi.ts")).toBe("./cloud/cloudApi.ts");
+    expect(exportsMap.resolve("./package.json")).toBe("./package.json");
+  });
+
+  test("every directory facet has a literal entry, since the wildcard cannot probe index.ts", async () => {
+    const facets = await barrelFacets();
+    const missing = facets.filter(
+      (subpath) =>
+        existsSync(path.join(packageDir, subpath, "index.ts")) && exportsMap.resolve(subpath) !== `${subpath}/index.ts`,
+    );
+    expect(missing).toEqual([]);
+  });
+});

package/packageExportsMap.ts

@@ -0,0 +1,96 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+
+export interface UnreachableSubpath {
+  subpath: string;
+  /** The path the `exports` map yields, or null when no entry matches the subpath at all. */
+  target: string | null;
+}
+
+/**
+ * The subset of Node's `exports` resolution that Bun applies to a published package.
+ *
+ * Exports targets are matched **exactly**: no extension is appended and no `index.ts` is probed. That
+ * is invisible inside this monorepo, where `@akanjs/devkit/*` and `akanjs/*` resolve through the root
+ * tsconfig `paths` instead — a resolver that *does* probe both. A map of `{"./*": "./*"}` therefore
+ * type-checks, builds, and passes every test while every subpath import fails for anyone who installs
+ * the tarball. This class exists so that gap can be asserted against before publishing.
+ */
+export class PackageExportsMap {
+  /** Reads `<packageDir>/package.json` and builds the map from its `exports` field. */
+  static async from(packageDir: string) {
+    const manifest = (await Bun.file(path.join(packageDir, "package.json")).json()) as { exports?: unknown };
+    return new PackageExportsMap(packageDir, manifest.exports);
+  }
+  /** Picks the target a runtime import would follow, walking conditional objects in Bun's order. */
+  static #runtimeTargetOf(value: unknown): string | null {
+    if (typeof value === "string") return value;
+    if (Array.isArray(value)) {
+      // Bun takes the first entry and stops; it does not fall through on a missing file.
+      for (const entry of value) {
+        const target = PackageExportsMap.#runtimeTargetOf(entry);
+        if (target) return target;
+      }
+      return null;
+    }
+    if (!value || typeof value !== "object") return null;
+    const conditions = value as Record<string, unknown>;
+    for (const condition of ["bun", "import", "default", "require", "types"]) {
+      if (!(condition in conditions)) continue;
+      const target = PackageExportsMap.#runtimeTargetOf(conditions[condition]);
+      if (target) return target;
+    }
+    return null;
+  }
+  #packageDir: string;
+  #literals = new Map<string, string>();
+  #patterns: { prefix: string; suffix: string; target: string }[] = [];
+  constructor(packageDir: string, exportsField: unknown) {
+    this.#packageDir = packageDir;
+    if (!exportsField || typeof exportsField !== "object") return;
+    for (const [key, value] of Object.entries(exportsField as Record<string, unknown>)) {
+      if (!key.startsWith(".")) continue; // a bare conditional map has no subpaths to check
+      const target = PackageExportsMap.#runtimeTargetOf(value);
+      if (!target) continue;
+      const star = key.indexOf("*");
+      if (star === -1) this.#literals.set(key, target);
+      else this.#patterns.push({ prefix: key.slice(0, star), suffix: key.slice(star + 1), target });
+    }
+    // Node picks the most specific pattern: longest prefix first, then longest suffix. So `./*.ts`
+    // wins over `./*`, which is what keeps an already-suffixed specifier from gaining a second `.ts`.
+    this.#patterns.sort((a, b) => b.prefix.length - a.prefix.length || b.suffix.length - a.suffix.length);
+  }
+  /** Returns the target an `exports` lookup yields, or null when the subpath is unexported. */
+  resolve(subpath: string): string | null {
+    const literal = this.#literals.get(subpath);
+    if (literal) return literal;
+    for (const { prefix, suffix, target } of this.#patterns) {
+      if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
+      if (subpath.length < prefix.length + suffix.length) continue;
+      return target.replace("*", subpath.slice(prefix.length, subpath.length - suffix.length));
+    }
+    return null;
+  }
+  /**
+   * Resolves a subpath and reports whether the target it yields is a readable file.
+   *
+   * A directory does not count. `{"./*": "./*"}` maps `./commandDecorators` onto the directory of
+   * that name, which exists but is not a module — an `existsSync` check here reports such a subpath
+   * as reachable while the import still fails.
+   */
+  resolveToFile(subpath: string): { target: string | null; exists: boolean } {
+    const target = this.resolve(subpath);
+    if (!target) return { target: null, exists: false };
+    const stat = statSync(path.join(this.#packageDir, target), { throwIfNoEntry: false });
+    return { target, exists: !!stat?.isFile() };
+  }
+  /** Returns the given subpaths that no consumer could import, in input order. */
+  findUnreachable(subpaths: Iterable<string>): UnreachableSubpath[] {
+    const unreachable: UnreachableSubpath[] = [];
+    for (const subpath of subpaths) {
+      const { target, exists } = this.resolveToFile(subpath);
+      if (!exists) unreachable.push({ subpath, target });
+    }
+    return unreachable;
+  }
+}