@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.10

package/transforms/barrelImportsPlugin.ts

@@ -4,7 +4,7 @@ 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";
+import { loaderFor, type NamedItem } from "./moduleSyntax";
 
 export interface BarrelImportsPluginOptions {
   /** Absolute paths whose content is returned unchanged (e.g. node_modules). */
@@ -234,10 +234,22 @@ const resolveFileCandidate = async (candidate: string): Promise<string | null> =
 
 const MACRO_ATTR_RE = /with\s*\{\s*type\s*:\s*["']macro["']\s*\}/;
 
+export interface RewriteBarrelImportsOptions {
+  /** Each replacement takes one line plus the newlines the statement spanned, so later lines keep their numbers. */
+  keepLines?: boolean;
+  specifierOf?: (subpath: string) => string;
+  /** Called for each import of a listed barrel with the value names whose rewrite reads its export map. */
+  onImport?: (barrel: string, names: string[]) => void;
+}
+
+export const workspaceBarrels = (barrels: readonly string[]): string[] =>
+  barrels.filter((barrel) => /^@(?:apps|libs)\//.test(barrel));
+
 export const rewriteBarrelImports = async (
   source: string,
   barrels: string[],
   analyzer: BarrelAnalyzer,
+  { keepLines = false, specifierOf = (subpath: string) => subpath, onImport }: RewriteBarrelImportsOptions = {},
 ): Promise<string | null> => {
   // Sound pre-filter before the costly parse: a static import cannot name a specifier absent from the text.
   if (!barrels.some((barrel) => source.includes(barrel))) return null;
@@ -251,20 +263,32 @@ export const rewriteBarrelImports = async (
     const stmt = statements[i];
     if (!stmt) continue;
     if (!barrels.includes(stmt.specifier)) continue;
+    const names = valueNamesOf(stmt.clause);
+    if (names.length > 0) onImport?.(stmt.specifier, names);
     const map = await analyzer.analyze(stmt.specifier);
     if (!map || map.size === 0) continue;
-    const replacement = rewriteSingleStatement(stmt, map);
-    if (replacement === null) continue;
+    const lines = rewriteSingleStatement(stmt, map, specifierOf);
+    if (lines === null) continue;
+    const replacement = keepLines
+      ? `${lines.join(" ")}${"\n".repeat(source.slice(stmt.start, stmt.end).split("\n").length - 1)}`
+      : lines.join("\n");
     out = out.slice(0, stmt.start) + replacement + out.slice(stmt.end);
     changed = true;
   }
   return changed ? out : null;
 };
 
+interface ParsedClause {
+  defaultImport?: string;
+  namespaceImport?: string;
+  named?: NamedItem[];
+  typeOnly: boolean;
+}
+
 interface ImportStatement {
   start: number;
   end: number;
-  clause: string;
+  clause: ParsedClause | null;
   specifier: string;
 }
 
@@ -286,52 +310,42 @@ const findImportStatements = (source: string): ImportStatement[] => {
     statements.push({
       start: statement.getStart(sourceFile),
       end: statement.end,
-      clause: source.slice(importClause.getStart(sourceFile), importClause.end).trim(),
+      clause: clauseOf(importClause),
       specifier: statement.moduleSpecifier.text,
     });
   }
   return statements;
 };
 
-interface ParsedClause {
-  defaultImport?: string;
-  namespaceImport?: string;
-  named?: NamedItem[];
-  typeOnly: boolean;
-}
-
-const parseImportClause = (clause: string): ParsedClause | null => {
-  let rest = clause.trim();
-  let typeOnly = false;
-  if (rest.startsWith("type ")) {
-    typeOnly = true;
-    rest = rest.slice(5).trim();
-  }
-  const parsed: ParsedClause = { typeOnly };
-  const commaMatch = /^(\w+)\s*,\s*(.+)$/.exec(rest);
-  if (commaMatch) {
-    parsed.defaultImport = commaMatch[1];
-    rest = commaMatch[2] ?? "";
-  } else if (/^\w+$/.test(rest)) {
-    parsed.defaultImport = rest;
-    return parsed;
-  }
-  if (rest.startsWith("*")) {
-    const ns = /^\*\s+as\s+(\w+)$/.exec(rest);
-    if (!ns) return null;
-    parsed.namespaceImport = ns[1];
-    return parsed;
-  }
-  if (rest.startsWith("{")) {
-    const close = rest.indexOf("}");
-    if (close === -1) return null;
-    parsed.named = parseNamedList(rest.slice(1, close));
+const clauseOf = (importClause: ts.ImportClause): ParsedClause | null => {
+  const parsed: ParsedClause = { typeOnly: importClause.phaseModifier === ts.SyntaxKind.TypeKeyword };
+  if (importClause.name) parsed.defaultImport = importClause.name.text;
+  const bindings = importClause.namedBindings;
+  if (!bindings) return parsed;
+  if (ts.isNamespaceImport(bindings)) return { ...parsed, namespaceImport: bindings.name.text };
+  const named: NamedItem[] = [];
+  for (const element of bindings.elements) {
+    if (element.propertyName && !ts.isIdentifier(element.propertyName)) return null;
+    named.push({
+      imported: (element.propertyName ?? element.name).text,
+      local: element.name.text,
+      isType: element.isTypeOnly,
+    });
   }
-  return parsed;
+  return { ...parsed, named };
 };
 
-const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): string | null => {
-  const clause = parseImportClause(stmt.clause);
+const valueNamesOf = (clause: ParsedClause | null): string[] => {
+  if (!clause || clause.namespaceImport || clause.typeOnly) return [];
+  return (clause.named ?? []).filter((item) => !item.isType).map((item) => item.imported);
+};
+
+const rewriteSingleStatement = (
+  stmt: ImportStatement,
+  map: BarrelExportMap,
+  specifierOf: (subpath: string) => string,
+): string[] | null => {
+  const { clause } = stmt;
   if (!clause) return null;
   // Namespace imports need the whole barrel — cannot rewrite safely.
   if (clause.namespaceImport) return null;
@@ -353,7 +367,7 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
       continue;
     }
     if (target.namespace) {
-      namespaceLines.push(`import * as ${item.local} from "${target.subpath}";`);
+      namespaceLines.push(`import * as ${item.local} from ${JSON.stringify(specifierOf(target.subpath))};`);
       continue;
     }
     const list = rewrites.get(target.subpath) ?? [];
@@ -364,7 +378,9 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
   if (rewrites.size === 0 && namespaceLines.length === 0) return null;
 
   //? 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) ?? [])];
+  const lines = (StoreBootstrap.ofClientBarrel(stmt.specifier, map) ?? []).map(
+    (specifier) => `import ${JSON.stringify(specifierOf(specifier))};`,
+  );
 
   if (clause.defaultImport || remaining.length > 0) {
     const parts: string[] = [];
@@ -374,11 +390,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(`import { ${items.map(serializeNamedItem).join(", ")} } from ${JSON.stringify(specifierOf(subpath))};`);
   }
   lines.push(...namespaceLines);
 
-  return lines.join("\n");
+  return lines;
 };
 
 const serializeNamedItem = (item: NamedItem): string => {

package/transforms/transforms.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
 import path from "node:path";
 import { ApplicationBuildReporter } from "../applicationBuildReporter";
 import { tempDirs, writeText as write } from "../testHelpers";
@@ -262,6 +263,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewriteBarrelImports(source, ["@libs/util/common"], analyzer)).toBeNull();
   });
 
+  test("forgets an analysis when a file beside one it read changes, under the link or the real path", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "real/ui/index.ts"), 'export * from "./Foo";\n');
+    await write(path.join(root, "real/ui/Foo.ts"), "export const Foo = 1;\n");
+    await write(path.join(root, "real/other/Bar.ts"), "export const Bar = 1;\n");
+    fs.symlinkSync(path.join(root, "real"), path.join(root, "linked"));
+    const pkgDir = path.join(root, "linked/ui");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@scope/ui", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+    const analyzed = async () => {
+      await analyzer.analyze("@scope/ui");
+      return analyzer;
+    };
+
+    expect([...(await analyzed()).forget([path.join(root, "real/other/Bar.ts")]).keys()]).toEqual([]);
+    expect([...(await analyzed()).forget([path.join(root, "real/ui/Foo.ts")]).keys()]).toEqual(["@scope/ui"]);
+    expect([...(await analyzed()).forget([path.join(pkgDir, "Created.ts")]).keys()]).toEqual(["@scope/ui"]);
+    expect([...analyzer.forget([path.join(pkgDir, "Foo.ts")]).keys()]).toEqual([]);
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
     const analyzer = fakeAnalyzer([
       ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
@@ -287,6 +309,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewriteBarrelImports('import { A } from "@other/pkg";', ["@scope/pkg"], analyzer)).toBeNull();
   });
 
+  test("reads every name of an import whose braces hold comments, aliases and type-only names", async () => {
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["st", { subpath: "@scope/pkg/store", originalName: "st" }],
+    ]);
+    const rewrite = async (source: string) => await rewriteBarrelImports(source, ["@scope/pkg"], analyzer);
+    const narrowed = 'import { A } from "@scope/pkg/leaf";\nimport { st } from "@scope/pkg/store";\n';
+
+    expect(await rewrite('import {\n  A, // the leaf\n  st,\n} from "@scope/pkg";\n')).toBe(narrowed);
+    expect(await rewrite('import { A, /* the store */ st } from "@scope/pkg";\n')).toBe(narrowed);
+    expect(await rewrite('import { type Shape, A as Leaf, st as store } from "@scope/pkg";\n')).toBe(
+      [
+        'import { type Shape } from "@scope/pkg";',
+        'import { A as Leaf } from "@scope/pkg/leaf";',
+        'import { st as store } from "@scope/pkg/store";',
+        "",
+      ].join("\n"),
+    );
+    expect(await rewrite('import { "A" as quoted } from "@scope/pkg";\n')).toBeNull();
+  });
+
   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"]) {
@@ -308,13 +351,15 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     }
     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");
+    await write(path.join(root, "libs/half/client.ts"), 'export { st } from "./lib/st";\n');
+    await write(path.join(root, "libs/half/lib/st.ts"), "export const st = {};\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 barrels = ["@apps/demo/client", "@libs/kit/client", "@libs/hand/client", "@libs/half/client"];
     const rewrite = async (source: string) => await rewriteBarrelImports(source, barrels, analyzer);
 
     expect(await rewrite('import { Memo, st } from "@apps/demo/client";\n')).toBe(
@@ -348,6 +393,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewrite('import { thing } from "@libs/hand/client";\n')).toBe(
       ['import "@libs/hand/client";', 'import { thing } from "@libs/hand/lib/thing";', ""].join("\n"),
     );
+    expect(await rewrite('import { st } from "@libs/half/client";\n')).toBe(
+      ['import "@libs/half/client";', 'import { st } from "@libs/half/lib/st";', ""].join("\n"),
+    );
+  });
+
+  test("keeps each statement's line count and writes the specifier specifierOf gives a target", async () => {
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["ns", { subpath: "@scope/pkg/namespace", originalName: "ns", namespace: true }],
+    ]);
+    const source = 'import {\n  A,\n  ns,\n} from "@scope/pkg";\nconsole.log(A, ns);\n';
+
+    const rewritten = await rewriteBarrelImports(source, ["@scope/pkg"], analyzer, {
+      keepLines: true,
+      specifierOf: (subpath) => `./${subpath.slice("@scope/pkg/".length)}.ts`,
+    });
+
+    expect(rewritten).toBe(
+      'import { A } from "./leaf.ts"; import * as ns from "./namespace.ts";\n\n\n\nconsole.log(A, ns);\n',
+    );
+    expect(rewritten?.split("\n")).toHaveLength(source.split("\n").length);
   });
 
   test("does not rewrite import-looking code inside template literals", async () => {

package/typecheck/projectTypecheck.ts

@@ -1,5 +1,6 @@
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import { CliError } from "../commandDecorators/cliError";
 import type { TypecheckRecord } from "../typeChecker";
 import { TypecheckFailure } from "./typecheckFailure";
 
@@ -69,7 +70,10 @@ export class ProjectTypecheck {
     if (exitCode === 0) return;
     const records = report === "records" ? ProjectTypecheck.#parseRecords(stdout) : null;
     if (records?.length) throw new TypecheckFailure(records);
-    throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+    const output = (stderr || stdout).trim();
+    if (exitCode === TypecheckFailure.workerExitCode && report === "pretty")
+      throw new CliError("checkFailed", output || "Typecheck failed");
+    throw new Error(output || `Typecheck failed with exit code ${exitCode}`);
   }
 
   static #parseRecords(stdout: string): TypecheckRecord[] | null {

package/typecheck/typecheck.proc.ts

@@ -1,5 +1,6 @@
 import { Logger } from "akanjs/common";
 import { TypeChecker } from "../typeChecker";
+import { TypecheckFailure } from "./typecheckFailure";
 
 try {
   const filePath = process.env.AKAN_TYPECHECK_FILE;
@@ -28,11 +29,11 @@ try {
     //? Not process.cwd(): that is the realpath (/private/var on macOS) while TypeScript keeps the spelling it was given.
     const root = process.env.AKAN_TYPECHECK_ROOT ?? process.cwd();
     process.stdout.write(JSON.stringify(TypeChecker.toRecords(result.errors, root)));
-    process.exit(result.errors.length > 0 ? 1 : 0);
+    process.exit(result.errors.length > 0 ? TypecheckFailure.workerExitCode : 0);
   }
   if (result.errors.length > 0) {
     console.error(result.message);
-    process.exit(1);
+    process.exit(TypecheckFailure.workerExitCode);
   }
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/typecheck/typecheckFailure.ts

@@ -1,8 +1,13 @@
+import { CliError } from "../commandDecorators/cliError";
 import type { TypecheckRecord } from "../typeChecker";
 
-export class TypecheckFailure extends Error {
+export class TypecheckFailure extends CliError<"checkFailed"> {
+  //? The worker's exit when the project has type errors, so its crash, which exits 1, is told apart.
+  static readonly workerExitCode = 3;
+
   constructor(readonly records: TypecheckRecord[]) {
     super(
+      "checkFailed",
       records
         .slice(0, 20)
         .map((record) => `${record.file ?? "-"}:${record.line}:${record.col} ${record.code} ${record.message}`)

package/workflow/artifacts.ts

@@ -16,6 +16,7 @@ import type {
   WorkflowNextActionCode,
   WorkflowOverallStatus,
   WorkflowPlan,
+  WorkflowRecommendation,
   WorkflowRunArtifact,
   WorkflowRunSource,
   WorkflowValidationCommandResult,
@@ -94,11 +95,11 @@ export const createWorkflowApplyReport = ({
   postApplyChecks?: WorkflowApplyReport["postApplyChecks"];
   recommendations?: WorkflowApplyReport["recommendations"];
 }): WorkflowApplyReport => {
-  const validationCommands = recommendedValidationCommands ?? commands;
-  const nextActionsWithIntent = nextActions.map((action) => ({
-    ...action,
-    action: inferNextActionCode(action, diagnostics),
-  }));
+  const status = workflowStatus(diagnostics);
+  const validationCommands = status === "failed" ? [] : (recommendedValidationCommands ?? commands);
+  const nextActionsWithIntent = nextActions
+    .map((action) => ({ ...action, action: inferNextActionCode(action, diagnostics) }))
+    .filter((action) => status !== "failed" || action.action !== "validate");
   if (sourceChangeBlocked(diagnostics) && !nextActionsWithIntent.some((action) => action.action === "blocked")) {
     nextActionsWithIntent.unshift({
       command: `akan workflow explain ${workflow}`,
@@ -110,12 +111,13 @@ export const createWorkflowApplyReport = ({
     (left, right) => nextActionPriority(left, diagnostics) - nextActionPriority(right, diagnostics),
   );
   const sourceFilesChanged = uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
-  const generatedFilesSynced = uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
+  const generatedFilesSynced =
+    status === "failed" ? [] : uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
   return {
     schemaVersion: 1,
     workflow,
     mode,
-    status: workflowStatus(diagnostics),
+    status,
     summary: {
       sourceFilesChanged,
       generatedFilesSynced,
@@ -133,6 +135,11 @@ export const createWorkflowApplyReport = ({
   };
 };
 
+export const withoutApplyHints = (recommendations: readonly WorkflowRecommendation[]) =>
+  recommendations.filter(
+    (recommendation) => recommendation.kind !== "auto-apply" && recommendation.kind !== "validation",
+  );
+
 export const resolveWorkflowCommand = (command: string, plan: WorkflowPlan) => {
   const target = typeof plan.inputs.app === "string" ? plan.inputs.app : "<app-or-lib>";
   return command
@@ -526,6 +533,17 @@ export const createWorkflowValidationRunReport = async ({
 };
 
 export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
+  if (workflowStatus(plan.diagnostics) === "failed")
+    return createWorkflowApplyReport({
+      workflow: plan.workflow,
+      mode: "dry-run",
+      changedFiles: [],
+      generatedFiles: [],
+      diagnostics: [...plan.diagnostics],
+      recommendations: withoutApplyHints(plan.recommendations),
+      nextActions: [],
+      plan,
+    });
   const changedFiles: PrimitiveChangedFile[] = plan.predictedChanges.flatMap((change) => {
     if (change.action !== "create" && change.action !== "modify") return [];
     return [

package/workflow/fieldType.ts

@@ -0,0 +1,92 @@
+import ts from "typescript";
+import type { Sys } from "../commandDecorators";
+import { ensureBaseImport, ensureNamedImport, getSysRoot, moduleComponentName, moduleSourcePaths } from "./source";
+import { sourceFileFor } from "./sourceAst";
+import type { WorkflowDiagnostic } from "./types";
+
+const builtInFieldTypes = new Set(["String", "Boolean", "Date", "Map"]);
+const baseFieldTypes = new Set(["Int", "Float", "ID", "Any", "Binary", "ImageResult"]);
+const fieldTypeReference = /^\[*([A-Za-z_$][\w$]*)((?:\.[A-Za-z_$][\w$]*)*)\]*$/;
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  const [, name = "", member] = fieldTypeReference.exec(typeName) ?? [];
+  if (member || !baseFieldTypes.has(name)) return content;
+  return ensureBaseImport(content, name);
+};
+
+const valueNamesOf = (content: string) => {
+  const names = new Set<string>();
+  for (const statement of sourceFileFor("source.ts", content).statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const clause = statement.importClause;
+      if (!clause || clause.isTypeOnly) continue;
+      if (clause.name) names.add(clause.name.text);
+      const bindings = clause.namedBindings;
+      if (bindings && ts.isNamespaceImport(bindings)) names.add(bindings.name.text);
+      else for (const element of bindings?.elements ?? []) if (!element.isTypeOnly) names.add(element.name.text);
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations)
+        if (ts.isIdentifier(declaration.name)) names.add(declaration.name.text);
+    } else if (
+      (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement) || ts.isFunctionDeclaration(statement)) &&
+      statement.name
+    )
+      names.add(statement.name.text);
+  }
+  return names;
+};
+
+export const fieldTypeSource = async (
+  sys: Sys,
+  module: string,
+  typeName: string,
+  constantContent: string,
+): Promise<{ import?: { name: string; from: string }; diagnostic?: WorkflowDiagnostic }> => {
+  const reference = fieldTypeReference.exec(typeName);
+  if (!reference)
+    return {
+      diagnostic: {
+        severity: "error",
+        code: "primitive-field-type-unknown",
+        input: "type",
+        message: `Field type "${typeName}" is not a type name field() takes. Name one type, such as Address, or a list of one, such as [Address], then plan this again.`,
+      },
+    };
+  const [, name = "", member] = reference;
+  if (builtInFieldTypes.has(name) || baseFieldTypes.has(name) || valueNamesOf(constantContent).has(name)) return {};
+  const [scalars, models] = await Promise.all([sys.getScalarModules(), sys.getDatabaseModules()]);
+  const scalar = member ? undefined : scalars.find((scalarName) => moduleComponentName(scalarName) === name);
+  if (scalar) return { import: { name, from: `../__scalar/${scalar}/${scalar}.constant` } };
+  const model = member ? undefined : models.find((modelName) => moduleComponentName(modelName) === name);
+  if (model) return { import: { name, from: `../${model}/${model}.constant` } };
+  const root = getSysRoot(sys);
+  const constantPath = `${root}/${moduleSourcePaths(module).constant}`;
+  const named = (kind: string, names: string[]) =>
+    names.length ? `Its ${kind} are ${names.map(moduleComponentName).join(", ")}.` : `It has no ${kind}.`;
+  return {
+    diagnostic: {
+      severity: "error",
+      code: "primitive-field-type-unknown",
+      input: "type",
+      message: [
+        `Field type "${typeName}" names ${name}, which is not a built-in or akanjs/base type, not imported by ${constantPath}, and not a scalar or model in ${root}.`,
+        named("scalars", scalars),
+        named("models", models),
+        `Create the scalar with the create-scalar workflow first, or import ${name} into ${constantPath}, then plan this again.`,
+      ].join(" "),
+    },
+  };
+};
+
+export const withFieldTypeImport = async (
+  sys: Sys,
+  module: string,
+  typeName: string,
+  content: string,
+  diagnostics: WorkflowDiagnostic[],
+) => {
+  const withBaseImport = ensureBaseTypeImport(content, typeName);
+  const source = await fieldTypeSource(sys, module, typeName, withBaseImport);
+  if (source.diagnostic) diagnostics.push(source.diagnostic);
+  return source.import ? ensureNamedImport(withBaseImport, source.import.from, source.import.name) : withBaseImport;
+};

package/workflow/index.ts

@@ -1,11 +1,13 @@
 export * from "./artifacts";
 export * from "./executor";
+export * from "./fieldType";
 export * from "./guardCatalog";
 export * from "./interactionScaffold";
 export * from "./keyRename";
 export * from "./moduleIndex";
 export * from "./mutationScaffold";
 export * from "./mutationSource";
+export * from "./plainName";
 export * from "./plan";
 export * from "./render";
 export * from "./rolloutGate";

package/workflow/plainName.ts

@@ -0,0 +1,28 @@
+export const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
+export const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
+const packageNamePattern = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+export type PlainNameKind = "app" | "lib" | "module" | "service" | "scalar";
+
+export const isWorkflowSysName = (value: unknown): value is string =>
+  typeof value === "string" && sysNamePattern.test(value);
+export const isWorkflowModuleName = (value: unknown): value is string =>
+  typeof value === "string" && identifierPattern.test(value);
+
+export const plainNameProblem = (kind: PlainNameKind, name: string) => {
+  const isSys = kind === "app" || kind === "lib";
+  if (isSys ? isWorkflowSysName(name) : isWorkflowModuleName(name)) return null;
+  return `${JSON.stringify(name)} is no ${kind} name; use letters, digits, - and _, starting with ${isSys ? "a lowercase letter or digit" : "a letter"}`;
+};
+
+export const assertPlainName = (kind: PlainNameKind, name: string) => {
+  const problem = plainNameProblem(kind, name);
+  if (problem) throw new Error(problem);
+};
+
+export const assertPackageName = (name: string) => {
+  if (packageNamePattern.test(name)) return;
+  throw new Error(
+    `${JSON.stringify(name)} is no package name; use name or @scope/name, each of lowercase letters, digits, -, . and _, starting with a letter or digit`,
+  );
+};