@akanjs/devkit 3.1.2-rc.3 → 3.2.0-rc.0

package/structureScanner.ts

@@ -0,0 +1,164 @@
+import ts from "typescript";
+
+export interface FunctionSize {
+  name: string;
+  line: number;
+  lineCount: number;
+}
+
+export interface ClassSize {
+  name: string;
+  line: number;
+  memberCount: number;
+}
+
+type FunctionNode =
+  | ts.FunctionDeclaration
+  | ts.MethodDeclaration
+  | ts.ConstructorDeclaration
+  | ts.GetAccessorDeclaration
+  | ts.SetAccessorDeclaration
+  | ts.FunctionExpression
+  | ts.ArrowFunction;
+
+export class StructureScanner {
+  measure(sourceFile: ts.SourceFile): { functions: FunctionSize[]; classes: ClassSize[] } {
+    const functions: FunctionSize[] = [];
+    const classes: ClassSize[] = [];
+    const lineOf = (pos: number) => sourceFile.getLineAndCharacterOfPosition(pos).line + 1;
+    const visit = (node: ts.Node, owners: string[]) => {
+      if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+        const name = StructureScanner.#classNameOf(node);
+        classes.push({
+          name: [...owners, name].join("."),
+          line: lineOf(node.getStart(sourceFile)),
+          memberCount: StructureScanner.#memberCountOf(node),
+        });
+        ts.forEachChild(node, (child) => visit(child, [...owners, name]));
+        return;
+      }
+      if (StructureScanner.#isFunction(node)) {
+        const name = StructureScanner.#functionNameOf(node);
+        const line = lineOf(node.getStart(sourceFile));
+        functions.push({
+          name: [...owners, name].join("."),
+          line,
+          lineCount: lineOf(node.getEnd()) - line + 1,
+        });
+        ts.forEachChild(node, (child) => visit(child, [...owners, name]));
+        return;
+      }
+      if (ts.isObjectLiteralExpression(node)) {
+        const name = StructureScanner.#boundNameOf(node);
+        ts.forEachChild(node, (child) => visit(child, name === "<anonymous>" ? owners : [...owners, name]));
+        return;
+      }
+      ts.forEachChild(node, (child) => visit(child, owners));
+    };
+    ts.forEachChild(sourceFile, (child) => visit(child, []));
+    return { functions, classes };
+  }
+
+  static #memberCountOf(node: ts.ClassDeclaration | ts.ClassExpression) {
+    const methods = new Set<string>();
+    return node.members.filter((member) => {
+      if (
+        ts.isSemicolonClassElement(member) ||
+        ts.isIndexSignatureDeclaration(member) ||
+        ts.isClassStaticBlockDeclaration(member)
+      )
+        return false;
+      if (!ts.isMethodDeclaration(member) && !ts.isConstructorDeclaration(member)) return true;
+      const isStatic = ts.getModifiers(member)?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword);
+      const key = `${isStatic ? "static " : ""}${ts.isConstructorDeclaration(member) ? "constructor" : StructureScanner.#textOf(member.name)}`;
+      if (methods.has(key)) return false;
+      methods.add(key);
+      return true;
+    }).length;
+  }
+
+  static #isFunction(node: ts.Node): node is FunctionNode {
+    return (
+      (ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node)) &&
+      node.body !== undefined
+    );
+  }
+
+  static #functionNameOf(node: FunctionNode) {
+    if (ts.isConstructorDeclaration(node)) return "constructor";
+    if (ts.isGetAccessorDeclaration(node)) return `get ${StructureScanner.#textOf(node.name)}`;
+    if (ts.isSetAccessorDeclaration(node)) return `set ${StructureScanner.#textOf(node.name)}`;
+    if (node.name) return StructureScanner.#textOf(node.name);
+    return ts.isFunctionDeclaration(node) ? "default" : StructureScanner.#boundNameOf(node);
+  }
+
+  static #classNameOf(node: ts.ClassDeclaration | ts.ClassExpression) {
+    if (node.name) return node.name.text;
+    return ts.isClassDeclaration(node) ? "default" : StructureScanner.#boundNameOf(node);
+  }
+
+  static #boundNameOf(node: ts.Node) {
+    let current: ts.Node = StructureScanner.#outerOf(node);
+    let call: string | null = null;
+    while (ts.isCallExpression(current.parent) || ts.isNewExpression(current.parent)) {
+      const callee = current.parent.expression;
+      if (current === callee) break;
+      call ??= `${ts.isPropertyAccessExpression(callee) ? callee.name.text : ts.isIdentifier(callee) ? callee.text : "call"}()`;
+      current = StructureScanner.#outerOf(current.parent);
+    }
+    const { parent } = current;
+    if (
+      (ts.isVariableDeclaration(parent) ||
+        ts.isPropertyAssignment(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isParameter(parent) ||
+        ts.isBindingElement(parent)) &&
+      parent.name &&
+      !ts.isObjectBindingPattern(parent.name) &&
+      !ts.isArrayBindingPattern(parent.name)
+    )
+      return StructureScanner.#textOf(parent.name);
+    if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+      return ts.isPropertyAccessExpression(parent.left)
+        ? parent.left.name.text
+        : ts.isIdentifier(parent.left)
+          ? parent.left.text
+          : "assigned";
+    if (ts.isExportAssignment(parent)) return "default";
+    if (ts.isJsxExpression(parent))
+      return ts.isJsxAttribute(parent.parent)
+        ? ts.isIdentifier(parent.parent.name)
+          ? parent.parent.name.text
+          : parent.parent.name.getText()
+        : "children";
+    return call ?? "<anonymous>";
+  }
+
+  static #outerOf(node: ts.Node) {
+    let current = node;
+    while (
+      ts.isParenthesizedExpression(current.parent) ||
+      ts.isAsExpression(current.parent) ||
+      ts.isSatisfiesExpression(current.parent) ||
+      ts.isNonNullExpression(current.parent) ||
+      ts.isTypeAssertionExpression(current.parent) ||
+      (ts.isPropertyAccessExpression(current.parent) && current.parent.expression === current) ||
+      (ts.isCallExpression(current.parent) && current.parent.expression === current)
+    )
+      current = current.parent;
+    return current;
+  }
+
+  static #textOf(name: ts.PropertyName | ts.BindingName) {
+    if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+    if (ts.isNumericLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text;
+    if (ts.isComputedPropertyName(name)) return `[${name.expression.getText()}]`;
+    return "<pattern>";
+  }
+}

package/transforms/barrelAnalyzer.ts

@@ -5,6 +5,8 @@ import { parseNamedList } from "./moduleSyntax";
 export interface BarrelExportTarget {
   subpath: string;
   originalName: string;
+  /** `export * as name from`: an import of the name binds the whole module at `subpath`. */
+  namespace?: boolean;
 }
 
 export type BarrelExportMap = Map<string, BarrelExportTarget>;
@@ -100,9 +102,14 @@ export class BarrelAnalyzer {
       if (!isRelative(spec)) continue;
 
       if (star) {
-        // A namespace re-export cannot be flattened into subpath imports, nor is it a local declaration.
-        if (nsAs) authoritative.delete(nsAs);
-        else starSpecs.push(spec);
+        if (!nsAs) starSpecs.push(spec);
+        else if (authoritative.has(nsAs)) {
+          attributed.add(nsAs);
+          const targetAbs = await this.#resolveRel(absFile, spec);
+          const targetSubpath = targetAbs ? this.#subpathFor(pkg, targetAbs) : null;
+          if (targetSubpath && !map.has(nsAs))
+            map.set(nsAs, { subpath: targetSubpath, originalName: nsAs, namespace: true });
+        }
         continue;
       }
 

package/transforms/barrelImportsPlugin.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import ts from "typescript";
+import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer, type BarrelExportMap, type PackageEntry } from "./barrelAnalyzer";
 import { loaderFor, type NamedItem, parseNamedList } from "./moduleSyntax";
@@ -101,8 +102,9 @@ export const createTsconfigPackageResolver = async (
         if (!repl) continue;
         const replPath = repl.endsWith("/*") ? repl.slice(0, -1) : repl;
         const candidate = path.resolve(app.workspace.workspaceRoot, replPath + suffix);
-        // A sibling file (`apps/minimal/client.ts`) is a facet barrel too: parent specifier, as above.
-        for (const ext of CANDIDATE_EXTS) {
+        // A sibling file (`apps/minimal/client.ts`), or the file a specifier names with its extension
+        // (`akanjs/ui/System/index.tsx`), is a facet barrel too: parent specifier, as above.
+        for (const ext of CANDIDATE_EXTS.includes(path.extname(candidate)) ? ["", ...CANDIDATE_EXTS] : CANDIDATE_EXTS) {
           const file = `${candidate}${ext}`;
           if (await Bun.file(file).exists()) {
             const lastSlash = pkgName.lastIndexOf("/");
@@ -339,6 +341,7 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
 
   const remaining: NamedItem[] = [];
   const rewrites = new Map<string, NamedItem[]>();
+  const namespaceLines: string[] = [];
   for (const item of clause.named) {
     if (item.isType) {
       remaining.push(item);
@@ -349,15 +352,19 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
       remaining.push(item);
       continue;
     }
+    if (target.namespace) {
+      namespaceLines.push(`import * as ${item.local} from "${target.subpath}";`);
+      continue;
+    }
     const list = rewrites.get(target.subpath) ?? [];
     list.push({ imported: target.originalName, local: item.local, isType: false });
     rewrites.set(target.subpath, list);
   }
 
-  if (rewrites.size === 0) return null;
+  if (rewrites.size === 0 && namespaceLines.length === 0) return null;
 
-  const lines: string[] = [];
-  if (shouldPreserveBarrelSideEffects(stmt.specifier)) lines.push(`import "${stmt.specifier}";`);
+  //? An app or lib client barrel's import-time side effects are its client runtime and store, not its module UI.
+  const lines: string[] = [...(StoreBootstrap.ofClientBarrel(stmt.specifier, map) ?? [])];
 
   if (clause.defaultImport || remaining.length > 0) {
     const parts: string[] = [];
@@ -369,12 +376,11 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
   for (const [subpath, items] of rewrites) {
     lines.push(`import { ${items.map(serializeNamedItem).join(", ")} } from "${subpath}";`);
   }
+  lines.push(...namespaceLines);
 
   return lines.join("\n");
 };
 
-const shouldPreserveBarrelSideEffects = (specifier: string): boolean => /^@(apps|libs)\/[^/]+\/client$/.test(specifier);
-
 const serializeNamedItem = (item: NamedItem): string => {
   const prefix = item.isType ? "type " : "";
   if (item.imported === item.local) return `${prefix}${item.imported}`;

package/transforms/serverEnvPlugin.test.ts

@@ -86,7 +86,7 @@ describe("createServerEnvPlugin", () => {
       "env/env.server.develop.ts is not in this build: `akan build` bundles the server env of AKAN_PUBLIC_ENV=main alone",
     );
     expect(proc.stderr.toString()).toContain(
-      "To run develop, build for it: AKAN_PUBLIC_ENV=develop in the workspace's .env, which outranks the shell, or --env develop on a desktop or mobile build.",
+      "To run develop, build for it with `--env develop` (`akan build` or a desktop or mobile build), or AKAN_PUBLIC_ENV=develop in the shell or the workspace's .env.",
     );
   });
 

package/transforms/serverEnvPlugin.ts

@@ -54,7 +54,7 @@ export const createServerEnvPlugin = ({
         build.onLoad({ filter }, async (args) => {
           const name = path.basename(args.path, ".ts").slice("env.server.".length);
           const { exports } = new Bun.Transpiler({ loader: "ts" }).scan(await Bun.file(args.path).text());
-          const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. To run ${name}, build for it: AKAN_PUBLIC_ENV=${name} in the workspace's .env, which outranks the shell, or --env ${name} on a desktop or mobile build.`;
+          const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. To run ${name}, build for it with \`--env ${name}\` (\`akan build\` or a desktop or mobile build), or AKAN_PUBLIC_ENV=${name} in the shell or the workspace's .env.`;
           return {
             loader: "js",
             contents: [

package/transforms/transforms.test.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { ApplicationBuildReporter } from "../applicationBuildReporter";
 import { tempDirs, writeText as write } from "../testHelpers";
 import { BarrelAnalyzer, type BarrelExportTarget } from "./barrelAnalyzer";
-import { rewriteBarrelImports } from "./barrelImportsPlugin";
+import { createTsconfigPackageResolver, rewriteBarrelImports } from "./barrelImportsPlugin";
 import {
   hasUseClientDirective,
   scanUseClientExports,
@@ -140,7 +140,7 @@ describe('export * in a "use client" module', () => {
 });
 
 describe("BarrelAnalyzer and rewriteBarrelImports", () => {
-  test("analyzes local, named, aliased, and star re-exports while skipping type and namespace exports", async () => {
+  test("analyzes local, named, aliased, star and namespace re-exports while skipping type exports", async () => {
     const root = await makeTempRoot();
     const pkgDir = path.join(root, "pkg");
     await write(
@@ -149,6 +149,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
         'export { A, B as Bee, type TypeOnly } from "./leaf";',
         'export * from "./star";',
         'export * as ns from "./namespace";',
+        'export type * as typeNs from "./namespace";',
         "export const Local = 1;",
         "export type LocalType = string;",
         "",
@@ -171,7 +172,9 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     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);
+    expect(map?.get("ns")).toEqual({ subpath: "@scope/pkg/namespace", originalName: "ns", namespace: true });
+    expect(map?.has("typeNs")).toBe(false);
+    expect(map?.has("Hidden")).toBe(false);
   });
 
   test("a name a module exports itself wins over the same name its star re-exports bring, as ES decides", async () => {
@@ -284,17 +287,66 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     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 = fakeAnalyzer([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]);
+  test("keeps a client barrel's runtime and store, never its module UI, when flattening an app or lib import", async () => {
+    const root = await makeTempRoot();
+    for (const sys of ["apps/demo", "libs/kit"]) {
+      await write(
+        path.join(root, sys, "client.ts"),
+        [
+          'export * as cnst from "./lib/cnst";',
+          'export { msg, Err, usePage, fetch, sig } from "./lib/useClient";',
+          'export { st, RootStore } from "./lib/st";',
+          'export * as store from "./lib/st";',
+          'export { Memo } from "./lib/memo";',
+          "",
+        ].join("\n"),
+      );
+      await write(path.join(root, sys, "lib/cnst.ts"), "export const Sample = 1;\n");
+      await write(path.join(root, sys, "lib/useClient.ts"), "export const { msg, Err, usePage, fetch, sig } = {};\n");
+      await write(path.join(root, sys, "lib/st.ts"), "export class RootStore {}\nexport const st = {};\n");
+      await write(path.join(root, sys, "lib/memo/index.ts"), "export const Memo = {};\n");
+    }
+    await write(path.join(root, "libs/hand/client.ts"), 'export { thing } from "./lib/thing";\n');
+    await write(path.join(root, "libs/hand/lib/thing.ts"), "export const thing = 1;\n");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: await createTsconfigPackageResolver({
+        workspace: { workspaceRoot: root },
+        getTsConfig: async () => ({ compilerOptions: { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } } }),
+      } as never),
+    });
+    const barrels = ["@apps/demo/client", "@libs/kit/client", "@libs/hand/client"];
+    const rewrite = async (source: string) => await rewriteBarrelImports(source, barrels, analyzer);
 
-    const rewritten = await rewriteBarrelImports(
-      'import { st } from "@apps/demo/client";\nvoid st;\n',
-      ["@apps/demo/client"],
-      analyzer,
+    expect(await rewrite('import { Memo, st } from "@apps/demo/client";\n')).toBe(
+      [
+        'import "@apps/demo/lib/useClient";',
+        'import "@apps/demo/lib/st";',
+        'import { Memo } from "@apps/demo/lib/memo";',
+        'import { st } from "@apps/demo/lib/st";',
+        "",
+      ].join("\n"),
     );
-
-    expect(rewritten).toBe(
-      ['import "@apps/demo/client";', 'import { st } from "@apps/demo/lib/st";', "void st;\n"].join("\n"),
+    expect(await rewrite('import { cnst as c, st, store, type cnst as T } from "@apps/demo/client";\n')).toBe(
+      [
+        'import "@apps/demo/lib/useClient";',
+        'import "@apps/demo/lib/st";',
+        'import { type cnst as T } from "@apps/demo/client";',
+        'import { st } from "@apps/demo/lib/st";',
+        'import * as c from "@apps/demo/lib/cnst";',
+        'import * as store from "@apps/demo/lib/st";',
+        "",
+      ].join("\n"),
+    );
+    expect(await rewrite('import { RootStore as kit } from "@libs/kit/client";\n')).toBe(
+      [
+        'import "@libs/kit/lib/useClient";',
+        'import "@libs/kit/lib/st";',
+        'import { RootStore as kit } from "@libs/kit/lib/st";',
+        "",
+      ].join("\n"),
+    );
+    expect(await rewrite('import { thing } from "@libs/hand/client";\n')).toBe(
+      ['import "@libs/hand/client";', 'import { thing } from "@libs/hand/lib/thing";', ""].join("\n"),
     );
   });
 

package/transforms/tsconfigPackageResolver.test.ts

@@ -99,6 +99,18 @@ describe("createTsconfigPackageResolver — wildcard tsconfig mapping", () => {
     });
   });
 
+  test("resolves a specifier that names its file with an extension, as the generated root layout imports System", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "pkgs/akanjs/ui/System/index.tsx");
+    const resolve = await resolverFor(root, { "akanjs/ui/*": ["./pkgs/akanjs/ui/*"] });
+
+    expect(await resolve("akanjs/ui/System/index.tsx")).toEqual({
+      pkgName: "akanjs/ui/System",
+      entryFile,
+      pkgDir: path.join(root, "pkgs/akanjs/ui/System"),
+    });
+  });
+
   test("resolves a directory barrel and keeps the specifier", async () => {
     const root = await makeTempRoot();
     const entryFile = await write(root, "apps/minimal/index.tsx");

package/typeChecker.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import * as ts from "typescript";
+import { tempDirs, writeJson, writeText } from "./testHelpers";
+import { TypeChecker } from "./typeChecker";
+
+const makeTempRoot = tempDirs("akan-devkit-type-checker-");
+
+//? `lib: []` adds global diagnostics (TS2318), and `emitDecoratorMetadata` alone an options one (TS5052).
+const project = async (declaration: boolean) => {
+  const root = await makeTempRoot();
+  const configPath = path.join(root, "tsconfig.json");
+  await writeJson(configPath, {
+    compilerOptions: {
+      strict: true,
+      lib: [],
+      types: [],
+      target: "esnext",
+      module: "esnext",
+      moduleResolution: "bundler",
+      noEmit: true,
+      incremental: true,
+      tsBuildInfoFile: "./.cache/tsconfig.tsbuildinfo",
+      declaration,
+      emitDecoratorMetadata: true,
+    },
+    include: ["src/**/*.ts"],
+  });
+  await writeText(path.join(root, "src/port.ts"), "export const port: number = 8282;\n");
+  await writeText(
+    path.join(root, "src/next.ts"),
+    'import { port } from "./port";\nexport const next: number = port + 1;\n',
+  );
+  await writeText(path.join(root, "src/semantic.ts"), 'export const name: number = "akan";\n');
+  await writeText(path.join(root, "src/syntax.ts"), "export const broken = (;\n");
+  await writeText(path.join(root, "src/declaration.ts"), "export const make = () => class { private secret = 1; };\n");
+  return { root, configPath };
+};
+
+const describeAll = (root: string, diagnostics: readonly ts.Diagnostic[]) =>
+  diagnostics.map((diagnostic) => ({
+    file: diagnostic.file ? path.relative(root, diagnostic.file.fileName) : null,
+    start: diagnostic.start,
+    length: diagnostic.length,
+    code: diagnostic.code,
+    category: diagnostic.category,
+    message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+  }));
+
+const preEmitDiagnostics = (root: string, configPath: string) => {
+  const { fileNames, options } = TypeChecker.parseConfig(configPath);
+  return describeAll(root, ts.getPreEmitDiagnostics(ts.createProgram({ rootNames: fileNames, options })));
+};
+
+const nextFileToCheck = (configPath: string) => {
+  const { fileNames, options } = TypeChecker.parseConfig(configPath);
+  const next = ts
+    .createIncrementalProgram({ rootNames: fileNames, options })
+    .getSemanticDiagnosticsOfNextAffectedFile();
+  return next && ("fileName" in next.affected ? next.affected.fileName : "the whole program");
+};
+
+describe("TypeChecker.checkProject", () => {
+  test.each([true, false])(
+    "reports what getPreEmitDiagnostics does, cold and warm (declaration: %p)",
+    async (declaration) => {
+      const { root, configPath } = await project(declaration);
+      const expected = preEmitDiagnostics(root, configPath);
+      expect(new Set(expected.map((diagnostic) => diagnostic.code))).toEqual(
+        new Set([5052, 1109, 2318, 2322, ...(declaration ? [4094] : [])]),
+      );
+
+      expect(describeAll(root, TypeChecker.checkProject(configPath).diagnostics)).toEqual(expected);
+      expect(describeAll(root, TypeChecker.checkProject(configPath).diagnostics)).toEqual(expected);
+    },
+  );
+
+  test("leaves a cache from which a resumed build has no file left to check", async () => {
+    const { configPath } = await project(true);
+    TypeChecker.checkProject(configPath);
+    expect(nextFileToCheck(configPath)).toBeUndefined();
+    TypeChecker.checkProject(configPath);
+    expect(nextFileToCheck(configPath)).toBeUndefined();
+  });
+
+  test("reports an edit's new errors, and its importer's, and drops a fixed one on a warm run", async () => {
+    const { root, configPath } = await project(true);
+    TypeChecker.checkProject(configPath);
+    await writeText(path.join(root, "src/port.ts"), "export const port: string = 8282;\n");
+    await writeText(path.join(root, "src/semantic.ts"), 'export const name: string = "akan";\n');
+
+    const warm = describeAll(root, TypeChecker.checkProject(configPath).diagnostics);
+    expect(warm).toEqual(preEmitDiagnostics(root, configPath));
+    expect(warm.filter((diagnostic) => diagnostic.code === 2322).map((diagnostic) => diagnostic.file)).toEqual([
+      path.join("src", "next.ts"),
+      path.join("src", "port.ts"),
+    ]);
+    expect(nextFileToCheck(configPath)).toBeUndefined();
+  });
+});

package/typeChecker.ts

@@ -177,8 +177,7 @@ export class TypeChecker {
       configFileParsingDiagnostics: parsedConfig.errors,
       host,
     });
-    const program = builderProgram.getProgram();
-    const diagnostics = [...ts.getPreEmitDiagnostics(program), ...builderProgram.emit().diagnostics];
+    const diagnostics = [...TypeChecker.#preEmitDiagnostics(builderProgram), ...builderProgram.emit().diagnostics];
     const errors = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
     const warnings = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Warning);
     return {
@@ -190,6 +189,19 @@ export class TypeChecker {
     };
   }
 
+  //* getPreEmitDiagnostics on the Program re-checks every file; the builder answers unchanged ones from .tsbuildinfo.
+  static #preEmitDiagnostics(builderProgram: ts.BuilderProgram) {
+    const { declaration, composite } = builderProgram.getCompilerOptions();
+    return ts.sortAndDeduplicateDiagnostics([
+      ...builderProgram.getConfigFileParsingDiagnostics(),
+      ...builderProgram.getOptionsDiagnostics(),
+      ...builderProgram.getSyntacticDiagnostics(),
+      ...builderProgram.getGlobalDiagnostics(),
+      ...builderProgram.getSemanticDiagnostics(),
+      ...(declaration || composite ? builderProgram.getDeclarationDiagnostics() : []),
+    ]);
+  }
+
   static parseConfig(configPath: string): ts.ParsedCommandLine {
     const configFile = ts.readConfigFile(configPath, (fileName) => ts.sys.readFile(fileName));
     const configDiagnostics = configFile.error ? [configFile.error] : [];

package/workflow/plan.ts

@@ -1,11 +1,11 @@
 import { capitalize } from "akanjs/common";
-import type { Workspace } from "../commandDecorators";
+import type { Sys, Workspace } from "../commandDecorators";
 import { workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
-import { coerceFieldDefault, moduleSourcePaths } from "./source";
+import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
   WorkflowInputSpec,
@@ -479,25 +479,87 @@ const inspectRenameKeyPlan = async (workspace: Workspace, plan: WorkflowPlan): P
   };
 };
 
-export const inspectWorkflowPlan = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowPlan> => {
-  if (plan.workflow === "rename-key") return await inspectRenameKeyPlan(workspace, plan);
-  if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
-  const app = planString(plan.inputs, "app");
-  if (!app) return plan;
+const syssHolding = async (workspace: Workspace, module: string, except: Sys) => {
+  const [apps, libs] = await workspace.getSyss();
+  const others = await Promise.all(
+    [...apps, ...libs]
+      .filter((name) => name !== except.name)
+      .map(async (name) => await resolveWorkflowSys(workspace, name)),
+  );
+  const holding = await Promise.all(
+    others.map(async (other) => (other && (await other.readdir("lib")).includes(module) ? other : null)),
+  );
+  return holding.filter((other): other is Sys => other !== null);
+};
+
+const moduleMissing = async (workspace: Workspace, sys: Sys, module: string): Promise<WorkflowDiagnostic | null> => {
+  if ((await sys.readdir("lib")).includes(module)) return null;
+  const root = getSysRoot(sys);
+  const modules = [...(await sys.getDatabaseModules()), ...(await sys.getServiceModules())];
+  const sameName = modules.find((name) => name.replace(/^_/, "").toLowerCase() === module.toLowerCase());
+  const isScalar = (await sys.getScalarModules()).includes(module);
+  const [holder] = sameName || isScalar ? [] : await syssHolding(workspace, module, sys);
+  return {
+    severity: "error",
+    code: "workflow-module-missing",
+    input: "module",
+    message: [
+      `No module named ${module} in ${root}: ${root}/lib/${module} does not exist.`,
+      modules.length ? `Its modules are ${modules.join(", ")}.` : `${root} has no modules yet.`,
+      sameName
+        ? `Did you mean ${sameName}?`
+        : isScalar
+          ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
+          : holder
+            ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
+            : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+    ].join(" "),
+  };
+};
+
+export const workflowTargetDiagnostics = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): Promise<WorkflowDiagnostic[]> => {
+  const app = planString(inputs, "app");
+  if (!app) return [];
   const sys = await resolveWorkflowSys(workspace, app).catch(() => null);
-  if (!sys)
+  if (!sys) {
+    const [apps, libs] = await workspace.getSyss();
+    return [
+      {
+        severity: "error",
+        code: "workflow-target-missing",
+        input: "app",
+        message: `No app or library named ${app}. Apps: ${apps.join(", ") || "none"}. Libraries: ${libs.join(", ") || "none"}.`,
+      },
+    ];
+  }
+  const module = planString(inputs, "module");
+  const moduleSpec: WorkflowInputSpec | undefined = spec.inputs.module;
+  if (!module || !moduleSpec?.mustExist) return [];
+  const missing = await moduleMissing(workspace, sys, module);
+  return missing ? [missing] : [];
+};
+
+export const inspectWorkflowPlan = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  plan: WorkflowPlan,
+): Promise<WorkflowPlan> => {
+  const targetDiagnostics = await workflowTargetDiagnostics(workspace, spec, plan.inputs);
+  if (targetDiagnostics.length)
     return {
       ...plan,
-      diagnostics: [
-        ...plan.diagnostics,
-        {
-          severity: "error",
-          code: "workflow-target-missing",
-          input: "app",
-          message: `No app or library named ${app}.`,
-        },
-      ],
+      predictedChanges: [],
+      diagnostics: [...plan.diagnostics, ...targetDiagnostics],
+      recommendations: [],
     };
+  if (plan.workflow === "rename-key") return await inspectRenameKeyPlan(workspace, plan);
+  if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
+  const sys = await resolveWorkflowSys(workspace, planString(plan.inputs, "app")).catch(() => null);
+  if (!sys) return plan;
   const inspected =
     plan.workflow === "add-mutation"
       ? await MutationScaffold.build(