@confect/cli 9.0.0-next.5 → 9.0.0-next.7

package/package.json

@@ -1,42 +1,14 @@
 {
   "name": "@confect/cli",
-  "version": "9.0.0-next.5",
   "description": "Developer tooling for codegen and sync",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/rjdellecese/confect.git"
-  },
-  "bugs": {
-    "url": "https://github.com/rjdellecese/confect/issues"
-  },
-  "homepage": "https://confect.dev",
-  "sideEffects": false,
-  "type": "module",
+  "version": "9.0.0-next.7",
+  "author": "RJ Dellecese",
   "bin": {
     "confect": "./dist/index.mjs"
   },
-  "files": [
-    "CHANGELOG.md",
-    "LICENSE",
-    "README.md",
-    "dist",
-    "package.json",
-    "src"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+  "bugs": {
+    "url": "https://github.com/rjdellecese/confect/issues"
   },
-  "keywords": [
-    "effect",
-    "convex",
-    "cli"
-  ],
-  "author": "RJ Dellecese",
-  "license": "ISC",
   "dependencies": {
     "@effect/cli": "^0.75.1",
     "@effect/platform": "0.96.1",
@@ -64,26 +36,53 @@
     "vite-tsconfig-paths": "6.1.1",
     "vitest": "3.2.4"
   },
-  "peerDependencies": {
-    "effect": "^3.21.2",
-    "@confect/core": "^9.0.0-next.5",
-    "@confect/server": "^9.0.0-next.5"
-  },
   "engines": {
-    "node": ">=22",
-    "pnpm": ">=10"
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "dist",
+    "package.json",
+    "src"
+  ],
+  "homepage": "https://confect.dev",
+  "keywords": [
+    "cli",
+    "convex",
+    "effect"
+  ],
+  "license": "ISC",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
+  "peerDependencies": {
+    "effect": "^3.21.2",
+    "@confect/core": "^9.0.0-next.7",
+    "@confect/server": "^9.0.0-next.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rjdellecese/confect.git"
+  },
+  "sideEffects": false,
+  "type": "module",
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsdown --config-loader unrun",
+    "clean": "rm -rf dist coverage node_modules",
     "dev": "tsdown --watch --config-loader unrun",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit --project tsconfig.json",
     "fix": "prettier --write . && eslint --fix . --max-warnings=0",
     "format": "prettier --check .",
     "lint": "eslint . --max-warnings=0",
-    "clean": "rm -rf dist coverage node_modules"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
   }
 }

package/src/CodegenError.ts

@@ -68,13 +68,6 @@ export class ImplMissingFunctionsError extends Schema.TaggedError<ImplMissingFun
   },
 ) {}
 
-export class SchemaInvalidDefaultExportError extends Schema.TaggedError<SchemaInvalidDefaultExportError>()(
-  "SchemaInvalidDefaultExportError",
-  {
-    schemaPath: Schema.String,
-  },
-) {}
-
 export class ParentChildNameCollisionError extends Schema.TaggedError<ParentChildNameCollisionError>()(
   "ParentChildNameCollisionError",
   {
@@ -85,8 +78,39 @@ export class ParentChildNameCollisionError extends Schema.TaggedError<ParentChil
   },
 ) {}
 
-export class MissingSchemaFileError extends Schema.TaggedError<MissingSchemaFileError>()(
-  "MissingSchemaFileError",
+export class InvalidTableDefaultExportError extends Schema.TaggedError<InvalidTableDefaultExportError>()(
+  "InvalidTableDefaultExportError",
+  {
+    tablePath: Schema.String,
+  },
+) {}
+
+export class InvalidTableFilenameError extends Schema.TaggedError<InvalidTableFilenameError>()(
+  "InvalidTableFilenameError",
+  {
+    tablePath: Schema.String,
+    reason: Schema.String,
+  },
+) {}
+
+export class DuplicateTableNameError extends Schema.TaggedError<DuplicateTableNameError>()(
+  "DuplicateTableNameError",
+  {
+    // Every table name that more than one file resolves to, each paired with
+    // the colliding file paths. All collisions are captured in a single pass
+    // so the user can fix them together rather than re-running codegen once
+    // per conflict.
+    collisions: Schema.Array(
+      Schema.Struct({
+        tableName: Schema.String,
+        tablePaths: Schema.Array(Schema.String),
+      }),
+    ),
+  },
+) {}
+
+export class LegacySchemaFileError extends Schema.TaggedError<LegacySchemaFileError>()(
+  "LegacySchemaFileError",
   {
     schemaPath: Schema.String,
   },
@@ -102,9 +126,11 @@ export const CodegenError = Schema.Union(
   ImplMissingDefaultLayerError,
   ImplNotFinalizedError,
   ImplMissingFunctionsError,
-  SchemaInvalidDefaultExportError,
-  MissingSchemaFileError,
   ParentChildNameCollisionError,
+  InvalidTableDefaultExportError,
+  InvalidTableFilenameError,
+  DuplicateTableNameError,
+  LegacySchemaFileError,
 );
 export type CodegenError = typeof CodegenError.Type;
 
@@ -207,7 +233,7 @@ const renderImplMissingDefaultLayerError = (
     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.",
+      " must default-export a GroupImpl layer; wrap your handlers with `GroupImpl.make(databaseSchema, groupSpec).pipe(Layer.provide(...))` and `export default` it.",
     ),
   );
 
@@ -218,7 +244,7 @@ const renderImplNotFinalizedError = (
     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)`).",
+      " is not finalized; append `GroupImpl.finalize` to the end of the pipeline (e.g. `GroupImpl.make(databaseSchema, group).pipe(Layer.provide(...), GroupImpl.finalize)`).",
     ),
   );
 
@@ -235,25 +261,52 @@ const renderImplMissingFunctionsError = (
   );
 };
 
-const renderSchemaInvalidDefaultExportError = (
-  error: SchemaInvalidDefaultExportError,
+const renderInvalidTableDefaultExportError = (
+  error: InvalidTableDefaultExportError,
 ): AnsiDoc.AnsiDoc =>
   singleLine(
-    AnsiDoc.text("Schema "),
-    formatPathDoc(error.schemaPath),
+    AnsiDoc.text("Table "),
+    formatPathDoc(error.tablePath),
     AnsiDoc.text(
-      " must default-export a DatabaseSchema; build it with DatabaseSchema.make({ ... }).",
+      " must default-export a Table (e.g. `export default Table.make({ ... })`); convert any named export to a default export.",
     ),
   );
 
-const renderMissingSchemaFileError = (
-  error: MissingSchemaFileError,
+const renderInvalidTableFilenameError = (
+  error: InvalidTableFilenameError,
 ): AnsiDoc.AnsiDoc =>
   singleLine(
-    AnsiDoc.text("Schema "),
+    AnsiDoc.text("Table "),
+    formatPathDoc(error.tablePath),
+    AnsiDoc.text(
+      ` has an invalid filename: ${error.reason} Convex table names must start with a letter and contain only letters, numbers, and underscores; leading underscores are reserved for system tables.`,
+    ),
+  );
+
+const renderDuplicateTableNameError = (
+  error: DuplicateTableNameError,
+): AnsiDoc.AnsiDoc => {
+  const conflicts = error.collisions
+    .map(
+      ({ tableName, tablePaths }) =>
+        `\`${tableName}\` (${tablePaths.join(", ")})`,
+    )
+    .join("; ");
+  return singleLine(
+    AnsiDoc.text(
+      `Multiple files under \`confect/tables/\` resolve to the same table name. Table names are derived from filenames, so each must be unique across the directory (including subdirectories); rename or remove all but one. Conflicts: ${conflicts}.`,
+    ),
+  );
+};
+
+const renderLegacySchemaFileError = (
+  error: LegacySchemaFileError,
+): AnsiDoc.AnsiDoc =>
+  singleLine(
+    AnsiDoc.text("Found a legacy "),
     formatPathDoc(error.schemaPath),
     AnsiDoc.text(
-      " is required but is missing; create it and default-export a DatabaseSchema (DatabaseSchema.make({ ... })).",
+      ". Delete it: tables in `confect/tables/*.ts` are now the single source of truth, and the runtime schema is generated as `confect/_generated/schema.ts`.",
     ),
   );
 
@@ -320,24 +373,33 @@ export const renderCodegenError = (error: CodegenError): string => {
         AnsiDoc.render({ style: "pretty" }),
       ),
     ),
-    Match.tag("SchemaInvalidDefaultExportError", (e) =>
+    Match.tag("ParentChildNameCollisionError", (e) =>
       pipe(
-        renderSchemaInvalidDefaultExportError(e),
+        renderParentChildNameCollisionError(e),
         AnsiDoc.render({ style: "pretty" }),
       ),
     ),
-    Match.tag("MissingSchemaFileError", (e) =>
+    Match.tag("InvalidTableDefaultExportError", (e) =>
       pipe(
-        renderMissingSchemaFileError(e),
+        renderInvalidTableDefaultExportError(e),
         AnsiDoc.render({ style: "pretty" }),
       ),
     ),
-    Match.tag("ParentChildNameCollisionError", (e) =>
+    Match.tag("InvalidTableFilenameError", (e) =>
       pipe(
-        renderParentChildNameCollisionError(e),
+        renderInvalidTableFilenameError(e),
         AnsiDoc.render({ style: "pretty" }),
       ),
     ),
+    Match.tag("DuplicateTableNameError", (e) =>
+      pipe(
+        renderDuplicateTableNameError(e),
+        AnsiDoc.render({ style: "pretty" }),
+      ),
+    ),
+    Match.tag("LegacySchemaFileError", (e) =>
+      pipe(renderLegacySchemaFileError(e), AnsiDoc.render({ style: "pretty" })),
+    ),
     Match.exhaustive,
   );
 };

package/src/LeafModule.ts

@@ -310,7 +310,7 @@ export const validateImpl = (leaf: LeafModule) =>
     if (missing.length > 0) {
       return yield* new ImplMissingFunctionsError({
         implPath: implRelativePath,
-        groupPath: finalizedGroupImpl.groupPath,
+        groupPath: leaf.groupPathDot,
         missingFunctionNames: missing,
       });
     }

package/src/SpecAssemblyNode.ts

@@ -82,39 +82,3 @@ export const collectImportBindings = (
     Array.map(([, binding]) => binding),
     Array.sortBy(Order.mapInput(Order.string, (binding) => binding.localName)),
   );
-
-export interface SpecLeafPath {
-  readonly binding: SpecImportBinding;
-  readonly dotPath: string;
-}
-
-const leafPathsForNode = (
-  node: SpecAssemblyNode,
-  ancestorSegments: ReadonlyArray<string>,
-): ReadonlyArray<SpecLeafPath> => {
-  const segments = [...ancestorSegments, node.segment];
-  const childPaths = Array.flatMap(node.children, (child) =>
-    leafPathsForNode(child, segments),
-  );
-  return Option.match(node.importBinding, {
-    onNone: () => childPaths,
-    onSome: (binding) =>
-      Array.prepend(childPaths, { binding, dotPath: segments.join(".") }),
-  });
-};
-
-/**
- * Walk the assembly tree and produce one entry per leaf spec, pairing its
- * import binding with the full dot-path codegen will register via
- * `Spec.addPath`. Ordering matches `collectImportBindings` (sorted by the
- * binding's local name) so the generated file is stable across runs.
- */
-export const collectLeafPaths = (
-  nodes: ReadonlyArray<SpecAssemblyNode>,
-): ReadonlyArray<SpecLeafPath> =>
-  pipe(
-    Array.flatMap(nodes, (node) => leafPathsForNode(node, [])),
-    Array.sortBy(
-      Order.mapInput(Order.string, (entry) => entry.binding.localName),
-    ),
-  );

package/src/TableModule.ts

@@ -0,0 +1,153 @@
+import { Identifier } from "@confect/core";
+import * as Table from "@confect/server/Table";
+import { FileSystem, Path } from "@effect/platform";
+import { Array, Effect, Order, pipe } from "effect";
+import { fromBundlerError } from "./BuildError";
+import * as Bundler from "./Bundler";
+import {
+  DuplicateTableNameError,
+  InvalidTableDefaultExportError,
+  InvalidTableFilenameError,
+} from "./CodegenError";
+import { ConfectDirectory } from "./ConfectDirectory";
+
+export const TABLES_DIRNAME = "tables";
+
+/**
+ * Discovered metadata for a single user-authored table module under
+ * `confect/tables/`.
+ *
+ * - `relativePath` — path from `confect/` to the file (e.g. `tables/notes.ts`).
+ * - `tableName` — the file basename (e.g. `notes`). This is also the import
+ *   binding used in generated files, and the table name surfaced to Convex.
+ */
+export interface TableModule {
+  readonly relativePath: string;
+  readonly tableName: string;
+}
+
+const tableNameFromRelativePath = (relativePath: string) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const { name } = path.parse(relativePath);
+    return name;
+  });
+
+const listTableFiles = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const confectDirectory = yield* ConfectDirectory.get;
+  const tablesDirectory = path.join(confectDirectory, TABLES_DIRNAME);
+
+  if (!(yield* fs.exists(tablesDirectory))) {
+    return [] as ReadonlyArray<string>;
+  }
+
+  const allPaths = yield* fs.readDirectory(tablesDirectory, {
+    recursive: true,
+  });
+
+  return pipe(
+    allPaths,
+    Array.filter((p) => p.endsWith(".ts") && !p.endsWith(".test.ts")),
+    Array.map((p) => path.join(TABLES_DIRNAME, p)),
+  );
+});
+
+const byTableName = Order.mapInput(
+  Order.string,
+  (tableModule: TableModule) => tableModule.tableName,
+);
+
+/**
+ * Discover every `confect/tables/**\/*.ts` module by listing the directory.
+ * Validates that each filename is a legal table identifier — the table name is
+ * derived from the file basename, so the filename must be a valid JavaScript
+ * identifier with no leading underscore (Convex reserves `_<name>` for system
+ * tables).
+ *
+ * This step does *not* bundle the table modules. It runs early in the codegen
+ * pipeline so the `_generated/id.ts` constructor can be emitted *before* any
+ * user-authored table is bundled (those modules import from `_generated/id.ts`
+ * for cross-table refs).
+ *
+ * A missing `confect/tables/` directory is allowed and produces an empty list.
+ *
+ * Fails with {@link InvalidTableFilenameError} if any filename is not a valid
+ * table identifier, or {@link DuplicateTableNameError} if two files resolve to
+ * the same table name (the directory is scanned recursively but names are
+ * derived from the basename alone, so `tables/a/notes.ts` and
+ * `tables/b/notes.ts` would collide).
+ */
+export const discover = Effect.gen(function* () {
+  const relativePaths = yield* listTableFiles;
+
+  const tableModules = yield* Effect.forEach(
+    relativePaths,
+    (relativePath) =>
+      Effect.gen(function* () {
+        const tableName = yield* tableNameFromRelativePath(relativePath);
+        yield* Effect.try({
+          try: () => Identifier.validateConfectTableIdentifier(tableName),
+          catch: (e) =>
+            new InvalidTableFilenameError({
+              tablePath: relativePath,
+              reason: e instanceof Error ? e.message : String(e),
+            }),
+        });
+        return { relativePath, tableName } satisfies TableModule;
+      }),
+    { concurrency: "unbounded" },
+  );
+
+  const sorted = pipe(tableModules, Array.sortBy(byTableName));
+
+  const collisions = Object.entries(
+    Array.groupBy(sorted, (tableModule) => tableModule.tableName),
+  )
+    .filter(([, group]) => group.length > 1)
+    .map(([tableName, group]) => ({
+      tableName,
+      tablePaths: Array.map(group, (tableModule) => tableModule.relativePath),
+    }));
+
+  if (collisions.length > 0) {
+    return yield* new DuplicateTableNameError({ collisions });
+  }
+
+  return sorted;
+});
+
+/**
+ * Bundle every discovered table module and verify that its default export is
+ * an {@link Table.UnnamedTable} (the result of `Table.make(...)` before a
+ * name has been bound). Fails with {@link InvalidTableDefaultExportError} if
+ * any module's default export is missing or has the wrong shape.
+ *
+ * Must run *after* `_generated/id.ts` has been emitted, because user-authored
+ * table modules typically `import { Id } from "../_generated/id"` for
+ * cross-table references.
+ */
+export const validate = (tableModules: ReadonlyArray<TableModule>) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const confectDirectory = yield* ConfectDirectory.get;
+
+    yield* Effect.forEach(
+      tableModules,
+      ({ relativePath }) =>
+        Effect.gen(function* () {
+          const absolutePath = path.resolve(confectDirectory, relativePath);
+          const { module } = yield* Bundler.bundle(absolutePath).pipe(
+            Effect.mapError((error) => fromBundlerError(relativePath, error)),
+          );
+
+          if (!Table.isUnnamedTable(module.default)) {
+            return yield* new InvalidTableDefaultExportError({
+              tablePath: relativePath,
+            });
+          }
+        }),
+      { concurrency: "unbounded" },
+    );
+  });