@confect/cli 8.0.0 → 9.0.0-next.1

package/src/Bundler.ts

@@ -0,0 +1,144 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { Path } from "@effect/platform";
+import { Array, Effect, Option, pipe } from "effect";
+import * as esbuild from "esbuild";
+import { BundlerError } from "./BuildError";
+
+export interface Bundled {
+  readonly module: any;
+  readonly metafile: esbuild.Metafile;
+}
+
+export const EXTERNAL_PACKAGES = [
+  "@confect/core",
+  "@confect/server",
+  "effect",
+  "@effect/*",
+];
+
+const isExternalImport = (path: string) =>
+  EXTERNAL_PACKAGES.some((p) => {
+    if (p.endsWith("/*")) {
+      return path.startsWith(p.slice(0, -1));
+    }
+    return path === p || path.startsWith(p + "/");
+  });
+
+export const absoluteExternalsPlugin: esbuild.Plugin = {
+  name: "absolute-externals",
+  setup(build) {
+    build.onResolve({ filter: /.*/ }, async (args) => {
+      if (args.kind !== "import-statement" && args.kind !== "dynamic-import")
+        return;
+      if (!isExternalImport(args.path)) return;
+      // `import.meta.resolve`'s second argument is silently ignored in modern
+      // Node, so resolution would always walk up from the CLI's bundled file
+      // (`packages/cli/dist/utils.mjs`) instead of from the user's project.
+      // Use `createRequire` keyed on the importing file's directory so we
+      // resolve out of *their* `node_modules`. The synthetic filename is just
+      // a CommonJS resolution anchor; the file does not need to exist.
+      const parentFile = pathToFileURL(args.resolveDir + "/_").href;
+      const require_ = createRequire(parentFile);
+      const resolvedPath = require_.resolve(args.path);
+      const resolved = pathToFileURL(resolvedPath).href;
+      return { path: resolved, external: true };
+    });
+  },
+};
+
+const buildEntry = (entryPoint: string) =>
+  Effect.tryPromise({
+    try: () =>
+      esbuild.build({
+        entryPoints: [entryPoint],
+        bundle: true,
+        write: false,
+        platform: "node",
+        format: "esm",
+        logLevel: "silent",
+        metafile: true,
+        plugins: [absoluteExternalsPlugin],
+      }),
+    catch: (cause) => new BundlerError({ cause }),
+  });
+
+const importBundledModule = (result: esbuild.BuildResult) => {
+  const code = result.outputFiles![0]!.text;
+  const dataUrl =
+    "data:text/javascript;base64," + Buffer.from(code).toString("base64");
+  return import(dataUrl);
+};
+
+/**
+ * Bundle a TypeScript entry point with esbuild and import the result via a
+ * data URL. This handles extensionless `.ts` imports regardless of whether
+ * the user's project sets `"type": "module"` in package.json. The returned
+ * pair carries both the imported module and the esbuild metafile so callers
+ * can inspect the import graph (see {@link directlyImports}).
+ */
+export const bundle = (
+  entryPoint: string,
+): Effect.Effect<Bundled, BundlerError> =>
+  Effect.gen(function* () {
+    const result = yield* buildEntry(entryPoint);
+    const module = yield* Effect.tryPromise({
+      try: () => importBundledModule(result),
+      catch: (cause) => new BundlerError({ cause }),
+    });
+    if (!result.metafile) {
+      return yield* Effect.dieMessage("esbuild metafile missing");
+    }
+    return { module, metafile: result.metafile };
+  });
+
+const findMetafileInputKey = (
+  metafile: esbuild.Metafile,
+  absolutePath: string,
+) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const resolved = path.resolve(absolutePath);
+    return Array.findFirst(
+      Object.keys(metafile.inputs),
+      (key) => path.resolve(key) === resolved,
+    );
+  });
+
+/**
+ * Returns `true` when the module bundled from `sourceAbsolutePath` declares a
+ * direct import of `targetAbsolutePath` (according to the bundle's esbuild
+ * metafile). Returns `false` if either path is missing from the metafile.
+ */
+export const directlyImports = (
+  bundled: Bundled,
+  sourceAbsolutePath: string,
+  targetAbsolutePath: string,
+) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const sourceKey = yield* findMetafileInputKey(
+      bundled.metafile,
+      sourceAbsolutePath,
+    );
+    const targetKey = yield* findMetafileInputKey(
+      bundled.metafile,
+      targetAbsolutePath,
+    );
+
+    return pipe(
+      Option.all([sourceKey, targetKey]),
+      Option.flatMap(([sourceKey_, targetKey_]) =>
+        Option.fromNullable(bundled.metafile.inputs[sourceKey_]).pipe(
+          Option.map((sourceInput) => {
+            const targetResolved = path.resolve(targetKey_);
+            return sourceInput.imports.some(
+              (importedFile) =>
+                path.resolve(importedFile.path) === targetResolved,
+            );
+          }),
+        ),
+      ),
+      Option.getOrElse(() => false),
+    );
+  });

package/src/CodeBlockWriter.ts

@@ -0,0 +1,65 @@
+import type { Options as CodeBlockWriterOptions } from "code-block-writer";
+import CodeBlockWriter_ from "code-block-writer";
+import { Effect } from "effect";
+
+export class CodeBlockWriter {
+  private readonly writer: CodeBlockWriter_;
+
+  constructor(opts?: Partial<CodeBlockWriterOptions>) {
+    this.writer = new CodeBlockWriter_(opts);
+  }
+
+  indent<E = never, R = never>(
+    effect: Effect.Effect<void, E, R>,
+  ): Effect.Effect<void, E, R> {
+    return Effect.gen(this, function* () {
+      const indentationLevel = this.writer.getIndentationLevel();
+      this.writer.setIndentationLevel(indentationLevel + 1);
+      yield* effect;
+      this.writer.setIndentationLevel(indentationLevel);
+    });
+  }
+
+  writeLine<E = never, R = never>(line: string): Effect.Effect<void, E, R> {
+    return Effect.sync(() => {
+      this.writer.writeLine(line);
+    });
+  }
+
+  write<E = never, R = never>(text: string): Effect.Effect<void, E, R> {
+    return Effect.sync(() => {
+      this.writer.write(text);
+    });
+  }
+
+  quote<E = never, R = never>(text: string): Effect.Effect<void, E, R> {
+    return Effect.sync(() => {
+      this.writer.quote(text);
+    });
+  }
+
+  conditionalWriteLine<E = never, R = never>(
+    condition: boolean,
+    text: string,
+  ): Effect.Effect<void, E, R> {
+    return Effect.sync(() => {
+      this.writer.conditionalWriteLine(condition, text);
+    });
+  }
+
+  newLine<E = never, R = never>(): Effect.Effect<void, E, R> {
+    return Effect.sync(() => {
+      this.writer.newLine();
+    });
+  }
+
+  blankLine<E = never, R = never>(): Effect.Effect<void, E, R> {
+    return Effect.sync(() => {
+      this.writer.blankLine();
+    });
+  }
+
+  toString<E = never, R = never>(): Effect.Effect<string, E, R> {
+    return Effect.sync(() => this.writer.toString());
+  }
+}

package/src/CodegenError.ts

@@ -0,0 +1,376 @@
+import { Ansi, AnsiDoc } from "@effect/printer-ansi";
+import { Effect, Match, Option, pipe, Schema } from "effect";
+import { BuildError, isBuildError, renderBuildError } from "./BuildError";
+import { formatPathDoc } from "./log";
+
+// --- Variants ---
+
+export class MissingImplFileError extends Schema.TaggedError<MissingImplFileError>()(
+  "MissingImplFileError",
+  {
+    specPath: Schema.String,
+    expectedImplPath: Schema.String,
+  },
+) {}
+
+export class MissingSpecFileError extends Schema.TaggedError<MissingSpecFileError>()(
+  "MissingSpecFileError",
+  {
+    implPath: Schema.String,
+    expectedSpecPath: Schema.String,
+  },
+) {}
+
+export class SpecMissingDefaultGroupSpecError extends Schema.TaggedError<SpecMissingDefaultGroupSpecError>()(
+  "SpecMissingDefaultGroupSpecError",
+  {
+    specPath: Schema.String,
+  },
+) {}
+
+export class SpecRuntimeMismatchError extends Schema.TaggedError<SpecRuntimeMismatchError>()(
+  "SpecRuntimeMismatchError",
+  {
+    specPath: Schema.String,
+    expectedRuntime: Schema.Literal("Convex", "Node"),
+    actualRuntime: Schema.Literal("Convex", "Node"),
+  },
+) {}
+
+export class ImplMissingSpecImportError extends Schema.TaggedError<ImplMissingSpecImportError>()(
+  "ImplMissingSpecImportError",
+  {
+    implPath: Schema.String,
+    expectedSpecPath: Schema.String,
+  },
+) {}
+
+export class ImplMissingDefaultLayerError extends Schema.TaggedError<ImplMissingDefaultLayerError>()(
+  "ImplMissingDefaultLayerError",
+  {
+    implPath: Schema.String,
+  },
+) {}
+
+export class ImplNotFinalizedError extends Schema.TaggedError<ImplNotFinalizedError>()(
+  "ImplNotFinalizedError",
+  {
+    implPath: Schema.String,
+  },
+) {}
+
+export class ImplMissingFunctionsError extends Schema.TaggedError<ImplMissingFunctionsError>()(
+  "ImplMissingFunctionsError",
+  {
+    implPath: Schema.String,
+    groupPath: Schema.String,
+    missingFunctionNames: Schema.Array(Schema.String),
+  },
+) {}
+
+export class SchemaInvalidDefaultExportError extends Schema.TaggedError<SchemaInvalidDefaultExportError>()(
+  "SchemaInvalidDefaultExportError",
+  {
+    schemaPath: Schema.String,
+  },
+) {}
+
+export class ParentChildNameCollisionError extends Schema.TaggedError<ParentChildNameCollisionError>()(
+  "ParentChildNameCollisionError",
+  {
+    parentSpecPath: Schema.String,
+    childSpecPath: Schema.String,
+    collisionName: Schema.String,
+    collisionKind: Schema.Literal("function", "group"),
+  },
+) {}
+
+export class MissingSchemaFileError extends Schema.TaggedError<MissingSchemaFileError>()(
+  "MissingSchemaFileError",
+  {
+    schemaPath: Schema.String,
+  },
+) {}
+
+export const CodegenError = Schema.Union(
+  BuildError,
+  MissingImplFileError,
+  MissingSpecFileError,
+  SpecMissingDefaultGroupSpecError,
+  SpecRuntimeMismatchError,
+  ImplMissingSpecImportError,
+  ImplMissingDefaultLayerError,
+  ImplNotFinalizedError,
+  ImplMissingFunctionsError,
+  SchemaInvalidDefaultExportError,
+  MissingSchemaFileError,
+  ParentChildNameCollisionError,
+);
+export type CodegenError = typeof CodegenError.Type;
+
+export const isCodegenError = (error: unknown): error is CodegenError => {
+  if (isBuildError(error)) return true;
+  return Schema.is(CodegenError)(error);
+};
+
+// --- Per-variant rendering ---
+
+const cross = pipe(AnsiDoc.char("✘"), AnsiDoc.annotate(Ansi.red));
+
+const stemFromSpecPath = (specPath: string): string => {
+  const lastSep = Math.max(
+    specPath.lastIndexOf("/"),
+    specPath.lastIndexOf("\\"),
+  );
+  const basename = lastSep < 0 ? specPath : specPath.slice(lastSep + 1);
+  return basename.endsWith(".spec.ts")
+    ? basename.slice(0, -".spec.ts".length)
+    : basename;
+};
+
+const singleLine = (
+  ...parts: ReadonlyArray<AnsiDoc.AnsiDoc>
+): AnsiDoc.AnsiDoc => pipe(cross, AnsiDoc.catWithSpace(AnsiDoc.hcat(parts)));
+
+const renderMissingImplFileError = (
+  error: MissingImplFileError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Spec "),
+    formatPathDoc(error.specPath),
+    AnsiDoc.text(" has no sibling impl; create "),
+    formatPathDoc(error.expectedImplPath),
+    AnsiDoc.text(" and default-export a GroupImpl layer from it."),
+  );
+
+const renderMissingSpecFileError = (
+  error: MissingSpecFileError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Impl "),
+    formatPathDoc(error.implPath),
+    AnsiDoc.text(" has no sibling spec; create "),
+    formatPathDoc(error.expectedSpecPath),
+    AnsiDoc.text(
+      " and default-export a GroupSpec from it, or remove the impl.",
+    ),
+  );
+
+const renderSpecMissingDefaultGroupSpecError = (
+  error: SpecMissingDefaultGroupSpecError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Spec "),
+    formatPathDoc(error.specPath),
+    AnsiDoc.text(
+      " must default-export a GroupSpec; build it with GroupSpec.make() or GroupSpec.makeNode().",
+    ),
+  );
+
+const renderSpecRuntimeMismatchError = (
+  error: SpecRuntimeMismatchError,
+): AnsiDoc.AnsiDoc => {
+  const constructor =
+    error.expectedRuntime === "Node"
+      ? "GroupSpec.makeNode()"
+      : "GroupSpec.make()";
+  const moveHint =
+    error.expectedRuntime === "Node"
+      ? " or move the file into confect/node/."
+      : " or move the file out of confect/node/.";
+  return singleLine(
+    AnsiDoc.text("Spec "),
+    formatPathDoc(error.specPath),
+    AnsiDoc.text(
+      ` declares a ${error.actualRuntime} GroupSpec but its location requires ${error.expectedRuntime}; use ${constructor}${moveHint}`,
+    ),
+  );
+};
+
+const renderImplMissingSpecImportError = (
+  error: ImplMissingSpecImportError,
+): AnsiDoc.AnsiDoc => {
+  const stem = stemFromSpecPath(error.expectedSpecPath);
+  return singleLine(
+    AnsiDoc.text("Impl "),
+    formatPathDoc(error.implPath),
+    AnsiDoc.text(
+      ` does not import its sibling spec; add \`import ${stem} from "./${stem}.spec"\` and pass it to FunctionImpl.make / GroupImpl.make.`,
+    ),
+  );
+};
+
+const renderImplMissingDefaultLayerError = (
+  error: ImplMissingDefaultLayerError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Impl "),
+    formatPathDoc(error.implPath),
+    AnsiDoc.text(
+      " must default-export a GroupImpl layer; wrap your handlers with `GroupImpl.make(api, groupSpec).pipe(Layer.provide(...))` and `export default` it.",
+    ),
+  );
+
+const renderImplNotFinalizedError = (
+  error: ImplNotFinalizedError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Impl "),
+    formatPathDoc(error.implPath),
+    AnsiDoc.text(
+      " is not finalized; append `GroupImpl.finalize` to the end of the pipeline (e.g. `GroupImpl.make(api, group).pipe(Layer.provide(...), GroupImpl.finalize)`).",
+    ),
+  );
+
+const renderImplMissingFunctionsError = (
+  error: ImplMissingFunctionsError,
+): AnsiDoc.AnsiDoc => {
+  const names = error.missingFunctionNames.join(", ");
+  return singleLine(
+    AnsiDoc.text("Impl "),
+    formatPathDoc(error.implPath),
+    AnsiDoc.text(
+      ` does not implement every function declared by group \`${error.groupPath}\`; missing: ${names}. Add a \`FunctionImpl.make\` for each missing function and provide it to the group layer.`,
+    ),
+  );
+};
+
+const renderSchemaInvalidDefaultExportError = (
+  error: SchemaInvalidDefaultExportError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Schema "),
+    formatPathDoc(error.schemaPath),
+    AnsiDoc.text(
+      " must default-export a DatabaseSchema; build it with DatabaseSchema.make({ ... }).",
+    ),
+  );
+
+const renderMissingSchemaFileError = (
+  error: MissingSchemaFileError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Schema "),
+    formatPathDoc(error.schemaPath),
+    AnsiDoc.text(
+      " is required but is missing; create it and default-export a DatabaseSchema (DatabaseSchema.make({ ... })).",
+    ),
+  );
+
+const renderParentChildNameCollisionError = (
+  error: ParentChildNameCollisionError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Spec "),
+    formatPathDoc(error.parentSpecPath),
+    AnsiDoc.text(
+      ` declares a ${error.collisionKind} \`${error.collisionName}\` whose name collides with the sibling subdirectory spec `,
+    ),
+    formatPathDoc(error.childSpecPath),
+    AnsiDoc.text(
+      `. Rename one of them so the assembled spec has a unique key at this path.`,
+    ),
+  );
+
+/**
+ * Render any {@link CodegenError} into a styled, ready-to-print string.
+ * Single-error variants render to a one-line `✘`-prefixed message;
+ * `BundleFailedError` (the only multi-error variant) renders to a header
+ * plus an esbuild diagnostic block.
+ */
+export const renderCodegenError = (error: CodegenError): string => {
+  if (isBuildError(error)) return renderBuildError(error);
+  return Match.value(error).pipe(
+    Match.tag("MissingImplFileError", (e) =>
+      pipe(renderMissingImplFileError(e), AnsiDoc.render({ style: "pretty" })),
+    ),
+    Match.tag("MissingSpecFileError", (e) =>
+      pipe(renderMissingSpecFileError(e), AnsiDoc.render({ style: "pretty" })),
+    ),
+    Match.tag("SpecMissingDefaultGroupSpecError", (e) =>
+      pipe(
+        renderSpecMissingDefaultGroupSpecError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("SpecRuntimeMismatchError", (e) =>
+      pipe(
+        renderSpecRuntimeMismatchError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("ImplMissingSpecImportError", (e) =>
+      pipe(
+        renderImplMissingSpecImportError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("ImplMissingDefaultLayerError", (e) =>
+      pipe(
+        renderImplMissingDefaultLayerError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("ImplNotFinalizedError", (e) =>
+      pipe(renderImplNotFinalizedError(e), AnsiDoc.render({ style: "pretty" })),
+    ),
+    Match.tag("ImplMissingFunctionsError", (e) =>
+      pipe(
+        renderImplMissingFunctionsError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("SchemaInvalidDefaultExportError", (e) =>
+      pipe(
+        renderSchemaInvalidDefaultExportError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("MissingSchemaFileError", (e) =>
+      pipe(
+        renderMissingSchemaFileError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("ParentChildNameCollisionError", (e) =>
+      pipe(
+        renderParentChildNameCollisionError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.exhaustive,
+  );
+};
+
+export const logCodegenError = (error: CodegenError) =>
+  Effect.sync(() => console.error(renderCodegenError(error)));
+
+// --- Effect combinators ---
+
+/**
+ * Log any {@link CodegenError} thrown by `effect` and propagate the failure
+ * unchanged so the caller's error channel is preserved (used by the
+ * `codegen` command, which needs the failure to surface as a non-zero exit
+ * code).
+ */
+export const tapAndLog = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.tapError((error) =>
+      isCodegenError(error) ? logCodegenError(error) : Effect.void,
+    ),
+  );
+
+/**
+ * Catch any {@link CodegenError} thrown by `effect`, log it, and resolve to
+ * `Option.none()` (used by the `dev` command's sync loop, which continues
+ * after a failed sync rather than exiting). Success resolves to
+ * `Option.some(value)`.
+ */
+export const catchAndLog = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<Option.Option<A>, Exclude<E, CodegenError>, R> =>
+  Effect.catchIf(Effect.map(effect, Option.some<A>), isCodegenError, (error) =>
+    logCodegenError(error).pipe(Effect.as(Option.none<A>())),
+  ) as Effect.Effect<Option.Option<A>, Exclude<E, CodegenError>, R>;