refactor: update CSV comment syntax for declarations

Update the syntax for type declarations and reverse reference
declarations in CSV files to be more explicit.

- Change type declarations from `# TypeName := schema` to
  `# type TypeName = schema`
- Change reverse reference declarations from `# fieldName :=
  ~table(key)`
  to `# inject fieldName = ~table(key)`

src/csv-loader/fixtures/user_rev.csv

@@ -1,4 +1,4 @@
-# orders := ~order_rev(user)
+# inject orders = ~order_rev(user)
 id,name
 string,string
 u01,Alice

src/csv-loader/module-gen.test.ts

@@ -104,7 +104,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("_self_refLookup = new Map(_raw.map");
     expect(result.js).toContain(
-      "parent: _self_refLookup.get(String(row.parent))",
+      "row.parent = _self_refLookup.get(String(row.parent));",
     );
   });
 
@@ -119,7 +119,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).toContain("import _circular_b from './circular_b.csv'");
     expect(result.js).toContain("export default function getData()");
     expect(result.js).toContain("_circular_bLookup");
-    expect(result.js).toContain("related:");
+    expect(result.js).toContain("row.related =");
   });
 
   it("should emit accessor for self-referencing table with nested reference in tuple", () => {
@@ -137,7 +137,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("export default function getData()");
-    expect(result.js).toContain("parent_info:");
+    expect(result.js).toContain("row.parent_info =");
     expect(result.js).toContain(
       "_self_refLookup.get(String(row.parent_info[0]))",
     );
@@ -159,7 +159,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("export default function getData()");
-    expect(result.js).toContain("ref_or_val:");
+    expect(result.js).toContain("row.ref_or_val =");
     expect(result.js).toContain(
       "_self_refLookup.get(String(row.ref_or_val)) ?? row.ref_or_val",
     );
@@ -180,7 +180,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("export default function getData()");
-    expect(result.js).toContain("children:");
+    expect(result.js).toContain("row.children =");
   });
 
   it("should generate correct type definition for self-referencing table using local singular type", () => {
@@ -247,7 +247,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -255,7 +255,7 @@ describe("csvToModule - reverse reference output", () => {
 
     expect(result.js).toContain("import _orders from './orders.csv'");
     expect(result.js).toContain("_ordersBy_customer");
-    expect(result.js).toContain("orders:");
+    expect(result.js).toContain("row.orders =");
     expect(result.js).toContain("_ordersBy_customer.get(String(row.id))");
   });
 
@@ -263,7 +263,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)?",
+      "# inject orders = ~orders(customer)?",
       "1,Alice",
     ].join("\n");
 
@@ -278,7 +278,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -291,7 +291,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# children := ~self_ref(parent)",
+      "# inject children = ~self_ref(parent)",
       "1,Root",
       "2,Child",
     ].join("\n");
@@ -304,14 +304,14 @@ describe("csvToModule - reverse reference output", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refBy_parent");
     expect(result.js).toContain("for (const r of _raw)");
-    expect(result.js).toContain("children:");
+    expect(result.js).toContain("row.children =");
   });
 
   it("should generate correct type definition for reverse references", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -329,7 +329,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)?",
+      "# inject orders = ~orders(customer)?",
       "1,Alice",
     ].join("\n");
 
@@ -346,7 +346,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name,manager",
       "string,string,@users",
-      "# reports := ~users(manager)",
+      "# inject reports = ~users(manager)",
       "1,Alice,2",
       "2,Bob,",
     ].join("\n");
@@ -365,7 +365,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name,creator",
       "string,string,@users",
-      "# reviews := ~users(reviewer)",
+      "# inject reviews = ~users(reviewer)",
       "1,Doc,1",
     ].join("\n");
 

src/csv-loader/module-gen.ts

@@ -186,7 +186,7 @@ export function csvToModule(
   const reverseLookupVar = (tableName: string, foreignKey: string) =>
     reverseLookupVarMap.get(`${tableName}:${foreignKey}`)!;
 
-  const rowResolvers: string[] = [];
+  const rowResolvers: { name: string; code: string }[] = [];
   for (const config of result.propertyConfigs) {
     if (config.isReverseReference) {
       // Reverse reference resolution
@@ -196,13 +196,15 @@ export function csvToModule(
       if (decl) {
         const revLookup = reverseLookupVar(decl.tableName, decl.foreignKey);
         if (decl.isOptional) {
-          rowResolvers.push(
-            `    ${config.name}: (${revLookup}.get(String(row.${defaultPrimaryKey})) || null),`,
-          );
+          rowResolvers.push({
+            name: config.name,
+            code: `(${revLookup}.get(String(row.${defaultPrimaryKey})) || null)`,
+          });
         } else {
-          rowResolvers.push(
-            `    ${config.name}: (${revLookup}.get(String(row.${defaultPrimaryKey})) || []),`,
-          );
+          rowResolvers.push({
+            name: config.name,
+            code: `(${revLookup}.get(String(row.${defaultPrimaryKey})) || [])`,
+          });
         }
       }
     } else if (hasNestedReferences(config.schema)) {
@@ -213,7 +215,7 @@ export function csvToModule(
         defaultPrimaryKey,
         reverseLookupVar,
       );
-      rowResolvers.push(`    ${config.name}: ${resolveCode},`);
+      rowResolvers.push({ name: config.name, code: resolveCode });
     }
   }
 
@@ -233,9 +235,10 @@ export function csvToModule(
     ...reverseLookupInits.map((l) => `  ${l}`),
     ...(rowResolvers.length > 0
       ? [
-          "  _resolved = _raw.map(row => (",
-          ...rowResolvers.map((r) => `    row${r.slice(1)}`),
-          "    row));",
+          "  _resolved = _raw.map(row => {",
+          ...rowResolvers.map((r) => `    row.${r.name} = ${r.code};`),
+          "    return row;",
+          "  });",
         ]
       : []),
     "  return _resolved;",

src/csv-loader/tests/parseCsv-reverseRefs.test.ts

@@ -20,7 +20,7 @@ describe("parseCsv - reverse reference resolution", () => {
       const csv = [
         "id,name",
         "string,string",
-        "# orders := ~rev_orders(customer)",
+        "# inject orders = ~rev_orders(customer)",
         "1,Alice",
         "2,Bob",
       ].join("\n");
@@ -57,7 +57,7 @@ describe("parseCsv - reverse reference resolution", () => {
       const csv = [
         "id,name",
         "string,string",
-        "# orders := ~rev_orders(customer)",
+        "# inject orders = ~rev_orders(customer)",
         "1,Alice",
         "99,Nobody",
       ].join("\n");
@@ -79,7 +79,7 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)?",
+      "# inject orders = ~orders(customer)?",
       "99,Nobody",
     ].join("\n");
 
@@ -96,7 +96,7 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -124,7 +124,7 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -140,8 +140,8 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
-      "# parts := ~parts(user)",
+      "# inject orders = ~orders(customer)",
+      "# inject parts = ~parts(user)",
       "1,Alice",
     ].join("\n");
 
@@ -162,7 +162,7 @@ describe("parseCsv - reverse reference resolution", () => {
       "id,name",
       "string,string",
       "# This is just a comment",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -190,7 +190,7 @@ describe("parseCsv - reverse reference resolution", () => {
       const csv = [
         "# id: id of user",
         "# orders: list of related orders",
-        "# orders := ~order(user)",
+        "# inject orders = ~order(user)",
         "id,name",
         "string,string",
         "u01,Alice",
@@ -225,7 +225,7 @@ describe("parseCsv - reverse reference with resolveReferences: false", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -255,7 +255,7 @@ describe("parseCsv - reverse reference with resolveReferences: false", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# nonexistent := ~nonexistent(some_key)",
+      "# inject nonexistent = ~nonexistent(some_key)",
       "1,Alice",
     ].join("\n");
 

src/csv-loader/tests/parseCsv-typeDeclarations.test.ts

@@ -6,7 +6,7 @@ import { fixturesDir } from "../test-utils";
 describe("parseCsv - type declarations", () => {
   it("should parse type declaration from comment line", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -30,7 +30,7 @@ describe("parseCsv - type declarations", () => {
 
   it("should use declared type as column schema", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -44,7 +44,7 @@ describe("parseCsv - type declarations", () => {
 
   it("should include declared types in type definition", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -64,8 +64,8 @@ describe("parseCsv - type declarations", () => {
 
   it("should parse multiple type declarations", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw'",
-      "# Status := 'active' | 'inactive'",
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "# type Status = 'active' | 'inactive'",
       "id,trigger,status",
       "string,Trigger,Status",
       "attack,onPlay,active",
@@ -80,8 +80,8 @@ describe("parseCsv - type declarations", () => {
 
   it("should include multiple type declarations in type definition", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw'",
-      "# Status := 'active' | 'inactive'",
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "# type Status = 'active' | 'inactive'",
       "id,trigger,status",
       "string,Trigger,Status",
       "attack,onPlay,active",
@@ -100,7 +100,7 @@ describe("parseCsv - type declarations", () => {
   it("should ignore comment lines that are not type declarations", () => {
     const csv = [
       "# This is just a comment",
-      "# Trigger := 'onPlay' | 'onDraw'",
+      "# type Trigger = 'onPlay' | 'onDraw'",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -114,7 +114,7 @@ describe("parseCsv - type declarations", () => {
 
   it("should handle type declaration with array schema", () => {
     const csv = [
-      "# Tags := string[]",
+      "# type Tags = string[]",
       "id,tags",
       "string,Tags",
       "1,[dev; admin; user]",
@@ -129,7 +129,7 @@ describe("parseCsv - type declarations", () => {
 
   it("should include type declaration before table type in output", () => {
     const csv = [
-      "# Status := 'active' | 'inactive'",
+      "# type Status = 'active' | 'inactive'",
       "id,status",
       "string,Status",
       "1,active",
@@ -150,7 +150,7 @@ describe("parseCsv - type declarations", () => {
 
   it("should work with type declarations alongside reverse references", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw'",
+      "# type Trigger = 'onPlay' | 'onDraw'",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -164,8 +164,8 @@ describe("parseCsv - type declarations", () => {
 
   it("should resolve type references inside tuple type declarations", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw' | 'onDiscard'",
-      "# Effect := [Trigger; @effect; int]",
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Effect = [Trigger; @effect; int]",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -182,8 +182,8 @@ describe("parseCsv - type declarations", () => {
 
   it("should include resolved type references in generated type definition", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw' | 'onDiscard'",
-      "# Effect := [Trigger; @effect; int]",
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Effect = [Trigger; @effect; int]",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",
@@ -206,7 +206,7 @@ describe("parseCsv - type declarations", () => {
 describe("parseCsv - type declarations with resolveReferences: false", () => {
   it("should populate typeDeclarations even when resolveReferences is false", () => {
     const csv = [
-      "# Trigger := 'onPlay' | 'onDraw'",
+      "# type Trigger = 'onPlay' | 'onDraw'",
       "id,trigger",
       "string,Trigger",
       "attack,onPlay",

src/csv-loader/type-declarations.ts

@@ -1,7 +1,4 @@
-import type {
-  Schema,
-  ReverseReferenceSchema,
-} from "../types.js";
+import type { Schema, ReverseReferenceSchema } from "../types.js";
 import { parseSchema } from "../parser.js";
 
 export interface ReverseReferenceDeclaration {
@@ -19,7 +16,7 @@ export interface TypeDeclaration {
 
 /**
  * Parse a type declaration from a comment line.
- * Format: # TypeName := schema
+ * Format: # type TypeName = schema
  * Returns null if the line is not a type declaration.
  */
 export function parseTypeDeclaration(
@@ -32,8 +29,8 @@ export function parseTypeDeclaration(
 
   const content = trimmed.slice(commentChar.length).trim();
 
-  // Match pattern: TypeName := schema
-  const match = content.match(/^([A-Z][a-zA-Z0-9]*)\s*:=\s*(.+)$/);
+  // Match pattern: type TypeName = schema
+  const match = content.match(/^type\s+([A-Z][a-zA-Z0-9]*)\s*=\s*(.+)$/);
   if (!match) return null;
 
   const [, typeName, schemaString] = match;
@@ -214,7 +211,7 @@ export function resolveTypeDeclarationSchema(
 
 /**
  * Parse a reverse reference declaration from a comment line.
- * Format: # fieldName := ~tableName(foreignKey)
+ * Format: # inject fieldName = ~tableName(foreignKey)
  * Returns null if the line is not a reverse reference declaration.
  */
 export function parseReverseReferenceDeclaration(
@@ -227,8 +224,8 @@ export function parseReverseReferenceDeclaration(
 
   const content = trimmed.slice(commentChar.length).trim();
 
-  // Match pattern: fieldName := ~tableName(foreignKey)
-  const match = content.match(/^(\w+)\s*:=\s*~(\w+)\((\w+)\)(\?)?$/);
+  // Match pattern: inject fieldName = ~tableName(foreignKey)
+  const match = content.match(/^inject\s+(\w+)\s*=\s*~(\w+)\((\w+)\)(\?)?$/);
   if (!match) return null;
 
   const [, fieldName, tableName, foreignKey, optionalMark] = match;