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

@@ -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");
 
@@ -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");
@@ -311,7 +311,7 @@ describe("csvToModule - reverse reference output", () => {
     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/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;