@akanjs/devkit 1.0.20 → 2.1.0-rc.1

package/transforms/index.ts

@@ -0,0 +1,5 @@
+export * from "./barrelAnalyzer";
+export * from "./barrelImportsPlugin";
+export * from "./externalizeFrameworkPlugin";
+export * from "./rscUseClientTransform";
+export * from "./useClientBundlePlugin";

package/transforms/rscUseClientTransform.ts

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+// Pure "use client" transform: when `source` starts with the `"use client"`
+// directive, replace its exports with `registerClientReference` stubs so the
+// RSC renderer can serialize them as client component references instead of
+// trying to run them on the server.
+
+// Matches `"use client"` or `'use client'` at the start of a file,
+// optionally after leading whitespace and JS comments.
+const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
+const IMPLICIT_ROOT_LAYOUT_RE =
+  /[/\\]\.akan[/\\]generated[/\\](?:implicit-root-layout|root-layouts[/\\].*__root_layout)\.(tsx|ts|jsx|js)$/;
+
+export interface UseClientTransformArgs {
+  path: string;
+  workspaceRoot?: string;
+}
+
+export function toClientReferencePath(absPath: string, workspaceRoot: string): string {
+  return path.relative(path.resolve(workspaceRoot), path.resolve(absPath)).split(path.sep).join("/");
+}
+
+/**
+ * Returns the stubbed module source if `source` is a client module, else null.
+ * The returned source is TypeScript-compatible (loader "ts" is safe).
+ */
+export function transformUseClient(source: string, args: UseClientTransformArgs): string | null {
+  if (!USE_CLIENT_RE.test(source)) return null;
+  if (IMPLICIT_ROOT_LAYOUT_RE.test(args.path)) return null;
+  const transpiler = new Bun.Transpiler({ loader: loaderFor(args.path) });
+  const { exports } = transpiler.scan(source);
+  if (exports.length === 0) return null;
+
+  const referencePath = args.workspaceRoot ? toClientReferencePath(args.path, args.workspaceRoot) : args.path;
+  const filePathLit = JSON.stringify(referencePath);
+  const lines: string[] = [`import { registerClientReference } from "react-server-dom-webpack/server.node";`];
+
+  for (const name of exports) {
+    const nameLit = JSON.stringify(name);
+    const errMsg = JSON.stringify(
+      `Attempted to call '${name}' from '${referencePath}' on the server, but it is a client-only export.`,
+    );
+    const proxy = `() => { throw new Error(${errMsg}); }`;
+    const binding =
+      name === "default"
+        ? `export default registerClientReference(${proxy}, ${filePathLit}, ${nameLit});`
+        : `export const ${name} = registerClientReference(${proxy}, ${filePathLit}, ${nameLit});`;
+    lines.push(binding);
+  }
+
+  return lines.join("\n");
+}
+
+function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
+  if (absPath.endsWith(".tsx")) return "tsx";
+  if (absPath.endsWith(".jsx")) return "jsx";
+  if (absPath.endsWith(".ts")) return "ts";
+  return "js";
+}

package/transforms/transforms.test.ts

@@ -0,0 +1,208 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { BarrelAnalyzer } from "./barrelAnalyzer";
+import { rewriteBarrelImports } from "./barrelImportsPlugin";
+import { toClientReferencePath, transformUseClient } from "./rscUseClientTransform";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-transform-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("transformUseClient", () => {
+  test("returns null for non-client modules and generated root layouts", () => {
+    expect(transformUseClient("export const value = 1;", { path: "/repo/app/page.tsx" })).toBeNull();
+    expect(
+      transformUseClient('"use client"; export const value = 1;', {
+        path: "/repo/apps/demo/.akan/generated/implicit-root-layout.tsx",
+      }),
+    ).toBeNull();
+    expect(
+      transformUseClient('"use client"; export const value = 1;', {
+        path: "/repo/apps/demo/.akan/generated/root-layouts/admin__root_layout.tsx",
+      }),
+    ).toBeNull();
+  });
+
+  test("stubs named and default exports as RSC client references", () => {
+    const source = [
+      "// comment before directive",
+      '"use client";',
+      "export const Button = () => null;",
+      "export function useThing() { return null; }",
+      "export default function DefaultButton() { return null; }",
+      "",
+    ].join("\n");
+
+    const transformed = transformUseClient(source, {
+      path: "/repo/apps/demo/components/Button.tsx",
+      workspaceRoot: "/repo",
+    });
+
+    expect(transformed).toContain('import { registerClientReference } from "react-server-dom-webpack/server.node";');
+    expect(transformed).toContain('"apps/demo/components/Button.tsx"');
+    expect(transformed).toContain("export const Button = registerClientReference");
+    expect(transformed).toContain("export const useThing = registerClientReference");
+    expect(transformed).toContain("export default registerClientReference");
+    expect(toClientReferencePath("/repo/apps/demo/Button.tsx", "/repo")).toBe("apps/demo/Button.tsx");
+  });
+});
+
+describe("BarrelAnalyzer and rewriteBarrelImports", () => {
+  test("analyzes local, named, aliased, and star re-exports while skipping type and namespace exports", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "pkg");
+    await write(
+      path.join(pkgDir, "index.ts"),
+      [
+        'export { A, B as Bee, type TypeOnly } from "./leaf";',
+        'export * from "./star";',
+        'export * as ns from "./namespace";',
+        "export const Local = 1;",
+        "export type LocalType = string;",
+        "",
+      ].join("\n"),
+    );
+    await write(
+      path.join(pkgDir, "leaf.ts"),
+      ["export const A = 1;", "export const B = 2;", "export type TypeOnly = string;", ""].join("\n"),
+    );
+    await write(path.join(pkgDir, "star.ts"), "export const Star = 3;\n");
+    await write(path.join(pkgDir, "namespace.ts"), "export const Hidden = 4;\n");
+
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@scope/pkg", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+
+    const map = await analyzer.analyze("@scope/pkg");
+    expect(map?.get("A")).toEqual({ subpath: "@scope/pkg/leaf", originalName: "A" });
+    expect(map?.get("Bee")).toEqual({ subpath: "@scope/pkg/leaf", originalName: "B" });
+    expect(map?.get("Star")).toEqual({ subpath: "@scope/pkg/star", originalName: "Star" });
+    expect(map?.get("Local")).toEqual({ subpath: "@scope/pkg", originalName: "Local" });
+    expect(map?.has("TypeOnly")).toBe(false);
+    expect(map?.has("ns")).toBe(false);
+  });
+
+  test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
+    const analyzer = {
+      analyze: async () =>
+        new Map([
+          ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+          ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
+        ]),
+    } as BarrelAnalyzer;
+
+    const rewritten = await rewriteBarrelImports(
+      'import DefaultExport, { A, Bee as LocalBee, type Shape, Missing } from "@scope/pkg";\nconsole.log(A);',
+      ["@scope/pkg"],
+      analyzer,
+    );
+
+    expect(rewritten).toBe(
+      [
+        'import DefaultExport, { type Shape, Missing } from "@scope/pkg";',
+        'import { A, B as LocalBee } from "@scope/pkg/leaf";',
+        "console.log(A);",
+      ].join("\n"),
+    );
+
+    expect(await rewriteBarrelImports('import * as pkg from "@scope/pkg";', ["@scope/pkg"], analyzer)).toBeNull();
+    expect(await rewriteBarrelImports('import type { A } from "@scope/pkg";', ["@scope/pkg"], analyzer)).toBeNull();
+    expect(await rewriteBarrelImports('import { A } from "@other/pkg";', ["@scope/pkg"], analyzer)).toBeNull();
+  });
+
+  test("preserves generated client barrel side effects when flattening app client imports", async () => {
+    const analyzer = {
+      analyze: async () => new Map([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]),
+    } as BarrelAnalyzer;
+
+    const rewritten = await rewriteBarrelImports(
+      'import { st } from "@apps/demo/client";\nvoid st;\n',
+      ["@apps/demo/client"],
+      analyzer,
+    );
+
+    expect(rewritten).toBe(
+      ['import "@apps/demo/client";', 'import { st } from "@apps/demo/lib/st";', "void st;\n"].join("\n"),
+    );
+  });
+
+  test("does not rewrite import-looking code inside template literals", async () => {
+    const analyzer = {
+      analyze: async () => new Map([["AkanApp", { subpath: "akanjs/server/akanApp", originalName: "AkanApp" }]]),
+    } as BarrelAnalyzer;
+
+    const source = [
+      'import { Code } from "@apps/docs/ui";',
+      "export const Example = () => (",
+      "  <Code.Snippet",
+      "    code={`",
+      'import { AkanApp } from "akanjs/server";',
+      "",
+      "void new AkanApp().start();",
+      "`}",
+      "  />",
+      ");",
+      "",
+    ].join("\n");
+
+    expect(await rewriteBarrelImports(source, ["akanjs/server"], analyzer)).toBeNull();
+  });
+
+  test("rewrites single-package Akan facet barrels to leaf subpaths", async () => {
+    const analyzer = {
+      analyze: async () =>
+        new Map([["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }]]),
+    } as BarrelAnalyzer;
+
+    const rewritten = await rewriteBarrelImports('import { BottomInset } from "akanjs/ui";\n', ["akanjs/ui"], analyzer);
+
+    expect(rewritten).toBe('import { BottomInset } from "akanjs/ui/Layout/BottomInset";\n');
+  });
+
+  test("preserves concrete file paths for package-exported barrels", async () => {
+    const root = await makeTempRoot();
+    await write(
+      path.join(root, "node_modules/akanjs/ui/index.ts"),
+      'export { Link } from "./Link";\nexport { System } from "./System";\n',
+    );
+    await write(path.join(root, "node_modules/akanjs/ui/Link/index.tsx"), "export const Link = () => null;\n");
+    await write(path.join(root, "node_modules/akanjs/ui/System/index.tsx"), "export const System = () => null;\n");
+
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({
+        pkgName: "akanjs/ui",
+        entryFile: path.join(root, "node_modules/akanjs/ui/index.ts"),
+        pkgDir: path.join(root, "node_modules/akanjs/ui"),
+        preserveFilePath: true,
+      }),
+    });
+
+    const rewritten = await rewriteBarrelImports(
+      'import { Link, System } from "akanjs/ui";\n',
+      ["akanjs/ui"],
+      analyzer,
+    );
+
+    expect(rewritten).toBe(
+      `${[
+        'import { Link } from "akanjs/ui/Link/index.tsx";',
+        'import { System } from "akanjs/ui/System/index.tsx";',
+      ].join("\n")}\n`,
+    );
+  });
+});

package/transforms/useClientBundlePlugin.ts

@@ -0,0 +1,47 @@
+import type { BunPlugin } from "bun";
+import { transformUseClient } from "./rscUseClientTransform";
+
+/**
+ * BunPlugin that stubs `"use client"` modules so the server bundle sees
+ * `registerClientReference(proxy, absPath, name)` stubs instead of the
+ * original client code.
+ *
+ * The bundle produced by `PagesBundleBuilder` is loaded in the RSC worker
+ * with `--conditions react-server`; client components are never supposed
+ * to execute there. The resulting stub references keep the client
+ * component manifest lookups working at render time while ensuring the
+ * server bundle never drags the real client source graph in.
+ *
+ * Important: the second argument to `registerClientReference` must match the
+ * key the client manifest uses. When `workspaceRoot` is provided, both sides
+ * use workspace-relative keys so production artifacts are portable.
+ */
+export function createUseClientBundlePlugin(options: { workspaceRoot?: string } = {}): BunPlugin {
+  return {
+    name: "akan-use-client-bundle",
+    setup(build) {
+      build.onLoad({ filter: /\.(tsx|ts|jsx|js)$/ }, async (args) => {
+        if (args.path.includes("/node_modules/")) return undefined;
+        let source: string;
+        try {
+          source = await Bun.file(args.path).text();
+        } catch {
+          return undefined;
+        }
+        const stubbed = transformUseClient(source, {
+          path: args.path,
+          workspaceRoot: options.workspaceRoot,
+        });
+        if (stubbed === null) return undefined;
+        return { contents: stubbed, loader: loaderFor(args.path) };
+      });
+    },
+  };
+}
+
+function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
+  if (absPath.endsWith(".tsx")) return "tsx";
+  if (absPath.endsWith(".jsx")) return "jsx";
+  if (absPath.endsWith(".ts")) return "ts";
+  return "js";
+}

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext",
+      "DOM"
+    ],
+    "target": "ESNext",
+    "module": "esnext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "types": [
+      "bun"
+    ],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": false,
+    "noUncheckedIndexedAccess": false,
+    "noImplicitOverride": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+    "experimentalDecorators": true,
+    "paths": {}
+  },
+  "extends": "../../../tsconfig.json",
+  "files": [],
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}

package/typeChecker.ts

@@ -0,0 +1,264 @@
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import chalk from "chalk";
+import * as ts from "typescript";
+
+import type { Executor } from "./executors";
+
+export interface ProjectTypecheckResult {
+  configPath: string;
+  diagnostics: ts.Diagnostic[];
+  errors: ts.Diagnostic[];
+  warnings: ts.Diagnostic[];
+  message: string;
+}
+
+export class TypeChecker {
+  readonly configPath: string;
+  readonly configFile: { config?: any; error?: ts.Diagnostic };
+  readonly config: ts.ParsedCommandLine;
+  constructor(executor: Executor) {
+    const configPath = this.#findConfigFile(executor.cwdPath);
+    if (!configPath) throw new Error("No tsconfig.json found in the project");
+    this.configPath = configPath;
+    this.configFile = ts.readConfigFile(this.configPath, (fileName) => ts.sys.readFile(fileName));
+    const parsedConfig = ts.parseJsonConfigFileContent(
+      this.configFile.config,
+      ts.sys,
+      path.dirname(this.configPath),
+      undefined,
+      this.configPath,
+    );
+
+    if (parsedConfig.errors.length > 0) {
+      const errorMessages = parsedConfig.errors
+        .map((error) => ts.flattenDiagnosticMessageText(error.messageText, "\n"))
+        .join("\n");
+      throw new Error(`Error parsing tsconfig.json:\n${errorMessages}`);
+    }
+    this.config = parsedConfig;
+  }
+  /**
+   * Find tsconfig.json by walking up the directory tree
+   */
+  #findConfigFile(searchPath: string): string | undefined {
+    return ts.findConfigFile(searchPath, (fileName) => ts.sys.fileExists(fileName), "tsconfig.json");
+  }
+
+  /**
+   * Type-check a single TypeScript file
+   * @param filePath - Path to the TypeScript file to check
+   * @returns Array of diagnostic messages
+   */
+  check(filePath: string): {
+    diagnostics: ts.Diagnostic[];
+    errors: ts.Diagnostic[];
+    warnings: ts.Diagnostic[];
+    fileDiagnostics: ts.Diagnostic[];
+    fileErrors: ts.Diagnostic[];
+    fileWarnings: ts.Diagnostic[];
+  } {
+    const program = ts.createProgram([filePath], this.config.options);
+    const diagnostics = [
+      ...program.getSemanticDiagnostics(),
+      ...program.getSyntacticDiagnostics(),
+      // Only check declaration diagnostics when declaration emit is enabled
+      ...(this.config.options.declaration ? program.getDeclarationDiagnostics() : []),
+    ];
+    const errors = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Warning);
+    const fileDiagnostics = diagnostics.filter((diagnostic) => diagnostic.file?.fileName === filePath);
+    const fileErrors = fileDiagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    const fileWarnings = fileDiagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Warning);
+    return { diagnostics, errors, warnings, fileDiagnostics, fileErrors, fileWarnings };
+  }
+
+  /**
+   * Format diagnostics for console output
+   * @param diagnostics - Array of TypeScript diagnostics
+   * @returns Formatted string
+   */
+  formatDiagnostics(diagnostics: ts.Diagnostic[]): string {
+    if (diagnostics.length === 0) return chalk.bold("✅ No type errors found");
+
+    const output: string[] = [];
+    let errorCount = 0;
+    let warningCount = 0;
+    let suggestionCount = 0;
+
+    // Group diagnostics by file
+    const diagnosticsByFile = new Map<string, ts.Diagnostic[]>();
+    diagnostics.forEach((diagnostic) => {
+      if (diagnostic.category === ts.DiagnosticCategory.Error) errorCount++;
+      else if (diagnostic.category === ts.DiagnosticCategory.Warning) warningCount++;
+      else if (diagnostic.category === ts.DiagnosticCategory.Suggestion) suggestionCount++;
+
+      if (diagnostic.file) {
+        const fileName = diagnostic.file.fileName;
+        if (!diagnosticsByFile.has(fileName)) diagnosticsByFile.set(fileName, []);
+        const fileDiagnostics = diagnosticsByFile.get(fileName);
+        if (fileDiagnostics) fileDiagnostics.push(diagnostic);
+      } else {
+        if (!diagnosticsByFile.has("")) diagnosticsByFile.set("", []);
+        const fileDiagnostics = diagnosticsByFile.get("");
+        if (fileDiagnostics) fileDiagnostics.push(diagnostic);
+      }
+    });
+
+    // Format diagnostics by file
+    diagnosticsByFile.forEach((fileDiagnostics, fileName) => {
+      if (fileName) output.push(`\n${chalk.cyan(fileName)}`);
+
+      fileDiagnostics.forEach((diagnostic) => {
+        const categoryText =
+          diagnostic.category === ts.DiagnosticCategory.Error
+            ? "error"
+            : diagnostic.category === ts.DiagnosticCategory.Warning
+              ? "warning"
+              : "suggestion";
+        const categoryColor =
+          diagnostic.category === ts.DiagnosticCategory.Error
+            ? chalk.red
+            : diagnostic.category === ts.DiagnosticCategory.Warning
+              ? chalk.yellow
+              : chalk.blue;
+        const icon =
+          diagnostic.category === ts.DiagnosticCategory.Error
+            ? "❌"
+            : diagnostic.category === ts.DiagnosticCategory.Warning
+              ? "⚠️"
+              : "💡";
+        const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+        const tsCode = chalk.dim(`(TS${diagnostic.code})`);
+
+        if (diagnostic.file && diagnostic.start !== undefined) {
+          const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+
+          output.push(`\n  ${icon} ${categoryColor(categoryText)}: ${message} ${tsCode}`);
+          output.push(`     ${chalk.gray("at")} ${fileName}:${chalk.bold(`${line + 1}:${character + 1}`)}`);
+
+          // Show source line with underline
+          const sourceLines = diagnostic.file.text.split("\n");
+          if (line < sourceLines.length) {
+            const sourceLine = sourceLines[line];
+            const lineNumber = (line + 1).toString().padStart(5, " ");
+
+            output.push(`\n${chalk.dim(`${lineNumber} |`)} ${sourceLine}`);
+
+            // Create underline with squiggly for TypeScript
+            const underlinePrefix = " ".repeat(character);
+            const length = diagnostic.length ?? 1;
+            const underline = "~".repeat(Math.max(1, length));
+
+            output.push(
+              `${chalk.dim(`${" ".repeat(lineNumber.length)} |`)} ${underlinePrefix}${categoryColor(underline)}`,
+            );
+          }
+        } else output.push(`\n  ${icon} ${categoryColor(categoryText)}: ${message} ${tsCode}`);
+      });
+    });
+
+    const summary = [] as string[];
+    if (errorCount > 0) summary.push(chalk.red(`${errorCount} error(s)`));
+    if (warningCount > 0) summary.push(chalk.yellow(`${warningCount} warning(s)`));
+    if (suggestionCount > 0) summary.push(chalk.blue(`${suggestionCount} suggestion(s)`));
+
+    return `\n${summary.join(", ")} found${output.join("\n")}`;
+  }
+
+  /**
+   * Get detailed diagnostic information with code snippet
+   * @param filePath - Path to the TypeScript file to check
+   * @returns Object containing diagnostics and detailed information
+   */
+  getDetailedDiagnostics(filePath: string): {
+    diagnostics: ts.Diagnostic[];
+    details: { line: number; column: number; message: string; code: number; codeSnippet?: string }[];
+  } {
+    const { diagnostics } = this.check(filePath);
+    const sourceFile = ts.createSourceFile(filePath, readFileSync(filePath, "utf8"), ts.ScriptTarget.Latest, true);
+
+    const details = diagnostics.map((diagnostic) => {
+      if (diagnostic.file && diagnostic.start !== undefined) {
+        const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+        const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+
+        const lines = sourceFile.text.split("\n");
+        const codeSnippet = line < lines.length ? lines[line] : undefined;
+        return { line: line + 1, column: character + 1, message, code: diagnostic.code, codeSnippet };
+      }
+
+      return {
+        line: 0,
+        column: 0,
+        message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+        code: diagnostic.code,
+      };
+    });
+
+    return { diagnostics, details };
+  }
+
+  /**
+   * Check if a file has type errors
+   * @param filePath - Path to the TypeScript file to check
+   * @returns true if there are no type errors, false otherwise
+   */
+  hasNoTypeErrors(filePath: string): boolean {
+    try {
+      const { diagnostics } = this.check(filePath);
+      return diagnostics.length === 0;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  static checkProject(configPath: string): ProjectTypecheckResult {
+    const parsedConfig = TypeChecker.parseConfig(configPath);
+    const host = ts.createIncrementalCompilerHost(parsedConfig.options);
+    const builderProgram = ts.createIncrementalProgram({
+      rootNames: parsedConfig.fileNames,
+      options: parsedConfig.options,
+      projectReferences: parsedConfig.projectReferences,
+      configFileParsingDiagnostics: parsedConfig.errors,
+      host,
+    });
+    const program = builderProgram.getProgram();
+    const diagnostics = [...ts.getPreEmitDiagnostics(program), ...builderProgram.emit().diagnostics];
+    const errors = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Warning);
+    return {
+      configPath,
+      diagnostics,
+      errors,
+      warnings,
+      message: TypeChecker.formatDiagnosticMessages(diagnostics),
+    };
+  }
+
+  static parseConfig(configPath: string): ts.ParsedCommandLine {
+    const configFile = ts.readConfigFile(configPath, (fileName) => ts.sys.readFile(fileName));
+    const configDiagnostics = configFile.error ? [configFile.error] : [];
+    if (!configFile.config) {
+      const message = TypeChecker.formatDiagnosticMessages(configDiagnostics);
+      throw new Error(message || `Error reading tsconfig.json: ${configPath}`);
+    }
+    const parsedConfig = ts.parseJsonConfigFileContent(
+      configFile.config,
+      ts.sys,
+      path.dirname(configPath),
+      undefined,
+      configPath,
+    );
+    if (parsedConfig.errors.length > 0) throw new Error(TypeChecker.formatDiagnosticMessages(parsedConfig.errors));
+    return parsedConfig;
+  }
+
+  static formatDiagnosticMessages(diagnostics: ts.Diagnostic[]): string {
+    return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+      getCanonicalFileName: (fileName) => fileName,
+      getCurrentDirectory: () => process.cwd(),
+      getNewLine: () => ts.sys.newLine,
+    });
+  }
+}

package/types.ts

@@ -0,0 +1,44 @@
+export interface PackageJson {
+  name: string;
+  type?: "module" | "commonjs";
+  version: string;
+  main?: string;
+  description: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  optionalDependencies?: Record<string, string>;
+  engines?: Record<string, string>;
+  exports?: Record<string, string | Record<string, string>>;
+  bun?: {
+    platform?: "node" | "browser" | "bun";
+  };
+  [key: string]: unknown;
+}
+
+export interface TsConfigJson {
+  extends?: string;
+  compilerOptions: {
+    target: string;
+    paths?: Record<string, string[]>;
+  };
+  references?: {
+    path: string;
+  }[];
+}
+
+export interface FileContent {
+  filePath: string;
+  content: string;
+}
+
+export interface BaseDevEnv {
+  workspaceRoot: string | undefined;
+  repoName: string;
+  serveDomain: string;
+  env: "testing" | "debug" | "develop" | "main" | "local";
+  portOffset: number;
+  appName?: string | undefined;
+}