refactor: enforce mandatory brackets for composite values

Implements Phase 1 and 2 of the syntax rework plan:
- Brackets `[]` are now mandatory for all tuple and array values.
- Removed the `[Type][]` array syntax; arrays now only use `Type[]`.
- `[single]` is now strictly a 1-tuple rather than an array.
- Updated documentation and test fixtures to reflect these breaking
  changes.

AGENTS.md

@@ -28,6 +28,7 @@ Build produces separate bundles per entry point (see `tsup.config.ts`). The csv-
 
 - Schema syntax uses **semicolons** (`;`) as separators, not commas
 - Unknown identifiers throw a `ParseError` — only recognized keywords (`string`, `number`, `int`, `float`, `boolean`) and string literals (`"on"`, `'off'`) are valid types
+- Tuple and array **values** must be wrapped in brackets `[]` (e.g. `[a; b]`); `[single]` is a 1-tuple, not an array — use `Type[]` for arrays
 - `@tablename` / `@tablename[]` are reference schemas resolved at CSV load time
 - `csvToModule()` emits accessor functions (`getData()`) for tables with references, and static JSON for tables without; bundler loaders all use `csvToModule`
 - `parseCsv({ resolveReferences: false })` stores reference IDs instead of resolved objects — used by `csvToModule` to emit import-based lazy resolution

README.md

@@ -35,14 +35,9 @@ numberSchema.validator(name);    // false
 ```typescript
 const tupleSchema = defineSchema('[string; number; boolean]');
 
-// With brackets
 const value1 = tupleSchema.parse('[hello; 42; true]');
 // ["hello", 42, true]
 
-// Without brackets (outermost brackets are optional)
-const value2 = tupleSchema.parse('hello; 42; true');
-// ["hello", 42, true]
-
 tupleSchema.validator(value1);    // true
 tupleSchema.validator(['a', 'b', true]);  // false (second element should be number)
 ```
@@ -50,16 +45,11 @@ tupleSchema.validator(['a', 'b', true]);  // false (second element should be num
 ### Arrays
 
 ```typescript
-// Array syntax: Type[] or [Type][]
+// Array syntax: Type[]
 const stringArray = defineSchema('string[]');
-const numberArray = defineSchema('[number][]');
+const numberArray = defineSchema('number[]');
 
-// With brackets
+const names = stringArray.parse('[alice; bob; charlie]');
-const names1 = stringArray.parse('[alice; bob; charlie]');
-// ["alice", "bob", "charlie"]
-
-// Without brackets (outermost brackets are optional)
-const names2 = stringArray.parse('alice; bob; charlie');
 // ["alice", "bob", "charlie"]
 
 const numbers = numberArray.parse('[1; 2; 3; 4; 5]');
@@ -71,12 +61,7 @@ const numbers = numberArray.parse('[1; 2; 3; 4; 5]');
 ```typescript
 const schema = defineSchema('[string; number][]');
 
-// With outer brackets
+const data = schema.parse('[[a; 1]; [b; 2]; [c; 3]]');
-const data1 = schema.parse('[[a; 1]; [b; 2]; [c; 3]]');
-// [["a", 1], ["b", 2], ["c", 3]]
-
-// Without outer brackets
-const data2 = schema.parse('[a; 1]; [b; 2]; [c; 3]');
 // [["a", 1], ["b", 2], ["c", 3]]
 ```
 
@@ -155,9 +140,9 @@ The following TypeScript types are exported:
 | Float | `float` | `3.14` |
 | Number | `number` | `42` or `3.14` |
 | Boolean | `boolean` | `true` or `false` |
-| Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` or `hello; 42; true` |
+| Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` |
-| Array | `Type[]` or `[Type][]` | `[1; 2; 3]` or `1; 2; 3` |
+| Array | `Type[]` | `[1; 2; 3]` |
-| Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` or `[a; 1]; [b; 2]` |
+| Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` |
 | Union | `Type1 \| Type2` | `hello` or `42` (matches first valid member) |
 | String Literal | `'on' \| 'off'` or `"red"` | `on` or `off` |
 | Reference | `@tablename` or `@tablename[]` | (resolved at CSV load time) |
@@ -166,7 +151,8 @@ The following TypeScript types are exported:
 ## Notes
 
 - Semicolons `;` are used as separators instead of commas `,`
-- Outermost brackets `[]` are optional for tuple and array values
+- Tuple and array values **must** be wrapped in brackets `[]` (e.g. `[a; b]`)
+- `[single]` is a 1-tuple, not an array — use `Type[]` for arrays
 - Special characters can be escaped with backslash: `\;`, `\[`, `\]`, `\\`
 - Empty arrays/tuples are not allowed
 - For CSV loading with reference resolution, see [csv-loader.md](./csv-loader.md)

csv-loader.md

@@ -146,7 +146,7 @@ Uses [typed-csv](https://github.com/your-repo/typed-csv) syntax:
 | String | `string` | `hello` |
 | Number | `number` | `42` |
 | Boolean | `boolean` | `true` |
-| Array | `string[]` or `[string][]` | `[a; b; c]` |
+| Array | `string[]` | `[a; b; c]` |
 | Tuple | `[string; number]` | `[hello; 42]` |
 
 ## License

docs/syntax-rework-plan.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Syntax Clarity & Parser Robustness
 
-Status: **Draft — not yet applied**
+Status: **In progress — Phases 1 & 2 applied** (Phases 3–6 not yet done)
 
 ## Goals
 
@@ -14,34 +14,29 @@ All changes are **breaking** to the DSL → bump to `2.0.0`, update README + `cs
 
 ---
 
-## Phase 1 — Mandatory brackets for composite values
+## Phase 1 — Mandatory brackets for composite values ✅ Applied
 
 **Files:** `src/value-parser.ts`, `src/index.test.ts`, `src/csv-loader/reference-resolver.ts`
 
-- Remove the `allowOmitBrackets` parameter from `parseValue`, `parseTupleValue`, `parseArrayValue`.
+- Removed the `allowOmitBrackets` parameter from `parseValue`, `parseTupleValue`, `parseArrayValue`.
-- Delete the `elementIsTupleOrArray` disambiguation block and all `savedPos` restore logic in `parseArrayValue`.
+- Deleted the `elementIsTupleOrArray` disambiguation block and all `savedPos` restore logic in `parseArrayValue`.
-- In `parseValue` (top-level), drop the `allowOmitBrackets = schema.type === "tuple" || "array"` special case — brackets are always required.
+- Dropped the `allowOmitBrackets = schema.type === "tuple" || "array"` special case in top-level `parseValue` — brackets are always required.
-- Values now must be fully bracketed: `[a; 1]; [b; 2]` (no more `[a; 1]; [b; 2]` without outer brackets).
+- Array references (`@table[]` values) now also require brackets, for consistency.
+- Values must now be fully bracketed: `[a; 1]; [b; 2]` (no more `[a; 1]; [b; 2]` without outer brackets).
 
-**Tests to update** (currently assert bracket-optional behavior):
+**Decision:** Full mandatory brackets (no carve-out).
-- `index.test.ts`: "should parse tuple without brackets" [L177], "should parse array without brackets" [L215], "should parse array of tuples without outer brackets" [L249].
-- `reference-resolver.ts` / `index.test.ts` reference tests: "should parse array reference IDs without brackets" [L685].
-
-**Decision point:** Full mandatory brackets, or a *top-level-only* carve-out (brackets optional only when the value is the whole cell and the element is non-composite)? Recommend **full mandatory** for a clean grammar; note the carve-out as a fallback if ergonomics matter more.
 
 ---
 
-## Phase 2 — Single array form `Type[]`
+## Phase 2 — Single array form `Type[]` ✅ Applied
 
 **Files:** `src/parser.ts`, `src/index.test.ts`
 
-- Remove the `[Type][]` array syntax from `parseSchemaInternal`. Keep only `Type[]`.
+- Removed the `[Type][]` array syntax from `parseSchemaInternal`. Kept only `Type[]`.
-- This makes `[string]` a **1-tuple** (currently it collapses to an array). Update the tuple branch: `[t]` → `{ type: "tuple", elements: [t] }`; the special case `elements.length === 1 && !elements[0].name` becomes a real tuple.
+- `[string]` is now a **1-tuple** (previously it collapsed to an array). The tuple branch always returns `{ type: "tuple", elements }`.
-- Update `schemaToTypeString` in `src/type-utils.ts` — the `array` case currently special-cases tuple elements; with `[Type][]` gone, arrays are always `elementType[]` (keep the `(union)[]` paren wrapping).
+- Updated `schemaToTypeString` in `src/type-utils.ts` — the `array` case no longer special-cases tuple elements; arrays are always `elementType[]` (kept the `(union)[]` paren wrapping).
 
-**Tests to update:**
+**Tests updated:** `index.test.ts` bracket-optional tests, `encounter.csv` / `enemy_intents.csv` fixtures, and `parseCsv-typeDeclarations.test.ts` array-of-tuple values.
-- `index.test.ts`: "should parse array of tuples" [L239] uses `[string; number][]` → becomes `[string; number][]` (unchanged) but "array of tuples without outer brackets" [L249] changes per Phase 1.
-- Any test using `[number][]`, `[string][]` schema strings (e.g. README examples, `csv-loader.md`).
 
 ---
 

src/csv-loader/fixtures/encounter.csv

@@ -3,5 +3,5 @@
 
 id,type,name,description,enemies,dialogue
 string,EncounterType,string,string,EnemyList,string
-cactus_pair,minion,仙人掌怪,概念：防+强化。【尖刺X】：对攻击者造成X点伤害。,[仙人掌怪;12;[]];[仙人掌怪;12;[]],
+cactus_pair,minion,仙人掌怪,概念：防+强化。【尖刺X】：对攻击者造成X点伤害。,[[仙人掌怪;12;[]];[仙人掌怪;12;[]]],
-snake_pair,minion,蛇,概念：攻+强化。给玩家塞入蛇毒牌（1费：打出时移除此牌。弃掉时受到3点伤害）。,[蛇;10;[[poison;2];[quick;1]]],
+snake_pair,minion,蛇,概念：攻+强化。给玩家塞入蛇毒牌（1费：打出时移除此牌。弃掉时受到3点伤害）。,[[蛇;10;[[poison;2];[quick;1]]]],

src/csv-loader/fixtures/enemy_intents.csv

@@ -4,4 +4,4 @@
 
 id,enemy,initialIntent,nextIntents,brokenIntent,effects
 string,string,boolean,string[],string[],IntentEffects
-仙人掌怪-boost,仙人掌怪,true,仙人掌怪-boost;仙人掌怪-defend,,[user;spike;1];[user;defend;4]
+仙人掌怪-boost,仙人掌怪,true,[仙人掌怪-boost;仙人掌怪-defend],,[[user;spike;1];[user;defend;4]]

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

@@ -209,7 +209,7 @@ describe("parseCsv - type declarations", () => {
       "# type IntentEffects = IntentEffect[]",
       "id,effects",
       "string,IntentEffects",
-      "boost,[user;spike;1];[user;defend;4]",
+      "boost,[[user;spike;1];[user;defend;4]]",
     ].join("\n");
 
     const result = parseCsv(csv, { emitTypes: false });
@@ -233,7 +233,7 @@ describe("parseCsv - type declarations", () => {
       "# type IntentEffects = IntentEffect[]",
       "id,effects",
       "string,IntentEffects",
-      "boost,[user;spike;1];[user;defend;4]",
+      "boost,[[user;spike;1];[user;defend;4]]",
     ].join("\n");
 
     const result = parseCsv(csv, {
@@ -260,7 +260,7 @@ describe("parseCsv - type declarations", () => {
       '# type Type = "apple" | "orange"',
       "id,items",
       "string,[Type; int][]",
-      "001,[apple;2];[orange;3]",
+      "001,[[apple;2];[orange;3]]",
     ].join("\n");
 
     const result = parseCsv(csv, { emitTypes: false });
@@ -292,7 +292,7 @@ describe("parseCsv - type declarations", () => {
       "# type Entry = [@user]",
       "id,entry",
       "string,Entry",
-      "1,1",
+      "1,[1]",
     ].join("\n");
 
     const result = parseCsv(csv, {

src/index.test.ts

@@ -174,10 +174,11 @@ describe("Tuples", () => {
     expect(schema.validator(["hello", "42"])).toBe(false);
   });
 
-  it("should parse tuple without brackets", () => {
+  it("should require brackets for tuple values", () => {
     const schema = defineSchema("[string; number]");
-    const value = schema.parse("hello; 42");
+    const value = schema.parse("[hello; 42]");
     expect(value).toEqual(["hello", 42]);
+    expect(() => schema.parse("hello; 42")).toThrow(ParseError);
   });
 
   it("should parse named tuple", () => {
@@ -212,10 +213,11 @@ describe("Arrays", () => {
     expect(schema.validator(["hello", 42])).toBe(false);
   });
 
-  it("should parse array without brackets", () => {
+  it("should require brackets for array values", () => {
     const schema = defineSchema("string[]");
-    const value = schema.parse("hello; world; test");
+    const value = schema.parse("[hello; world; test]");
     expect(value).toEqual(["hello", "world", "test"]);
+    expect(() => schema.parse("hello; world; test")).toThrow(ParseError);
   });
 
   it("should parse array of numbers", () => {
@@ -246,14 +248,15 @@ describe("Arrays", () => {
     ]);
   });
 
-  it("should parse array of tuples without outer brackets", () => {
+  it("should require outer brackets for array of tuples", () => {
     const schema = defineSchema("[string; number][]");
-    const value = schema.parse("[a; 1]; [b; 2]; [c; 3]");
+    const value = schema.parse("[[a; 1]; [b; 2]; [c; 3]]");
     expect(value).toEqual([
       ["a", 1],
       ["b", 2],
       ["c", 3],
     ]);
+    expect(() => schema.parse("[a; 1]; [b; 2]; [c; 3]")).toThrow(ParseError);
   });
 
   it("should parse array of unions", () => {
@@ -283,7 +286,7 @@ describe("Escaping", () => {
 
   it("should handle escaped semicolon in tuple", () => {
     const schema = defineSchema("[string; string]");
-    const value = schema.parse("hello\\;world; test");
+    const value = schema.parse("[hello\\;world; test]");
     expect(value).toEqual(["hello;world", "test"]);
   });
 });
@@ -682,14 +685,15 @@ describe("Reference value parsing (parseValue)", () => {
     expect(result).toEqual(["1", "2", "3"]);
   });
 
-  it("should parse array reference IDs without brackets", () => {
+  it("should require brackets for array reference IDs", () => {
     const schema: import("./types").ReferenceSchema = {
       type: "reference",
       tableName: "users",
       isArray: true,
     };
-    const result = parseValue(schema, "1; 2; 3");
+    const result = parseValue(schema, "[1; 2; 3]");
     expect(result).toEqual(["1", "2", "3"]);
+    expect(() => parseValue(schema, "1; 2; 3")).toThrow(ParseError);
   });
 
   it("should parse empty array reference", () => {

src/parser.ts

@@ -250,20 +250,7 @@ class Parser {
         throw new ParseError("Expected ]", this.pos);
       }
 
-      if (this.consumeStr("[")) {
+      // [t] is always a 1-tuple (the [Type][] array form was removed)
-        this.skipWhitespace();
-        if (!this.consumeStr("]")) {
-          throw new ParseError("Expected ]", this.pos);
-        }
-        if (elements.length === 1 && !elements[0].name) {
-          return { type: "array", element: elements[0].schema };
-        }
-        return { type: "array", element: { type: "tuple", elements } };
-      }
-
-      if (elements.length === 1 && !elements[0].name) {
-        return { type: "array", element: elements[0].schema };
-      }
       return { type: "tuple", elements };
     }
 

src/type-utils.ts

@@ -39,13 +39,6 @@ export function schemaToTypeString(
       return schema.isOptional ? `${baseType} | null` : baseType;
     }
     case "array":
-      if (schema.element.type === "tuple") {
-        const tupleElements = schema.element.elements.map((el) => {
-          const typeStr = schemaToTypeString(el.schema, resourceNames);
-          return el.name ? `${el.name}: ${typeStr}` : typeStr;
-        });
-        return `[${tupleElements.join(", ")}][]`;
-      }
       const elementType = schemaToTypeString(schema.element, resourceNames);
       if (schema.element.type === "union") {
         return `(${elementType})[]`;

src/value-parser.ts

@@ -41,7 +41,7 @@ class ValueParser {
     return false;
   }
 
-  parseValue(schema: Schema, allowOmitBrackets: boolean = false): unknown {
+  parseValue(schema: Schema): unknown {
     this.skipWhitespace();
 
     switch (schema.type) {
@@ -60,9 +60,9 @@ class ValueParser {
       case "union":
         return this.parseUnionValue(schema);
       case "tuple":
-        return this.parseTupleValue(schema, allowOmitBrackets);
+        return this.parseTupleValue(schema);
       case "array":
-        return this.parseArrayValue(schema, allowOmitBrackets);
+        return this.parseArrayValue(schema);
       case "reference":
         // Reference values are parsed as strings (IDs) initially, resolved later
         return this.parseReferenceValue(schema);
@@ -250,7 +250,7 @@ class ValueParser {
     for (let i = 0; i < schema.members.length; i++) {
       this.pos = savedPos;
       try {
-        return this.parseValue(schema.members[i], false);
+        return this.parseValue(schema.members[i]);
       } catch (e) {
         errors.push(e as Error);
         // Continue to next member
@@ -266,16 +266,8 @@ class ValueParser {
     );
   }
 
-  private parseTupleValue(
+  private parseTupleValue(schema: TupleSchema): unknown[] {
-    schema: TupleSchema,
+    if (!this.consumeStr("[")) {
-    allowOmitBrackets: boolean,
-  ): unknown[] {
-    let hasOpenBracket = false;
-
-    if (this.peek() === "[") {
-      this.consume();
-      hasOpenBracket = true;
-    } else if (!allowOmitBrackets) {
       throw new ParseError(
         "Expected [",
         this.pos,
@@ -286,7 +278,7 @@ class ValueParser {
 
     this.skipWhitespace();
 
-    if (this.peek() === "]" && hasOpenBracket) {
+    if (this.peek() === "]") {
       this.consume();
       return [];
     }
@@ -308,7 +300,7 @@ class ValueParser {
         }
       }
 
-      result.push(this.parseValue(elementSchema.schema, false));
+      result.push(this.parseValue(elementSchema.schema));
       this.skipWhitespace();
 
       if (i < schema.elements.length - 1) {
@@ -325,7 +317,6 @@ class ValueParser {
 
     this.skipWhitespace();
 
-    if (hasOpenBracket) {
     if (!this.consumeStr("]")) {
       throw new ParseError(
         "Expected ]",
@@ -334,48 +325,16 @@ class ValueParser {
         this.input,
       );
     }
-    }
 
     return result;
   }
 
-  private parseArrayValue(
+  private parseArrayValue(schema: ArraySchema): unknown[] {
-    schema: ArraySchema,
-    allowOmitBrackets: boolean,
-  ): unknown[] {
-    let hasOpenBracket = false;
-    const elementIsTupleOrArray =
-      schema.element.type === "tuple" || schema.element.type === "array";
-
     if (this.pos >= this.input.length || !this.input.trim()) {
       return [];
     }
 
-    if (this.peek() === "[") {
+    if (!this.consumeStr("[")) {
-      if (!elementIsTupleOrArray) {
-        this.consume();
-        hasOpenBracket = true;
-      } else {
-        // Element is tuple or array - need to disambiguate
-        // Save position to check if this is an empty array
-        const savedPos = this.pos;
-        this.consume();
-        this.skipWhitespace();
-        if (this.peek() === "]") {
-          // Empty array []
-          this.consume();
-          return [];
-        } else if (this.peek() === "[") {
-          // Nested brackets [[ - this is the array opener
-          hasOpenBracket = true;
-        } else {
-          // [ belongs to the first element, restore position
-          this.pos = savedPos;
-        }
-      }
-    }
-
-    if (!hasOpenBracket && !allowOmitBrackets && !elementIsTupleOrArray) {
       throw new ParseError(
         "Expected [",
         this.pos,
@@ -386,7 +345,7 @@ class ValueParser {
 
     this.skipWhitespace();
 
-    if (this.peek() === "]" && hasOpenBracket) {
+    if (this.peek() === "]") {
       this.consume();
       return [];
     }
@@ -395,7 +354,7 @@ class ValueParser {
     while (true) {
       this.skipWhitespace();
 
-      result.push(this.parseValue(schema.element, elementIsTupleOrArray));
+      result.push(this.parseValue(schema.element));
       this.skipWhitespace();
 
       if (!this.consumeStr(";")) {
@@ -405,7 +364,6 @@ class ValueParser {
 
     this.skipWhitespace();
 
-    if (hasOpenBracket) {
     if (!this.consumeStr("]")) {
       throw new ParseError(
         "Expected ]",
@@ -414,7 +372,6 @@ class ValueParser {
         this.input,
       );
     }
-    }
 
     return result;
   }
@@ -431,15 +388,18 @@ class ValueParser {
 
     if (schema.isArray) {
       // Parse array of IDs: [id1; id2; id3]
-      let hasOpenBracket = false;
+      if (!this.consumeStr("[")) {
-      if (this.peek() === "[") {
+        throw new ParseError(
-        this.consume();
+          "Expected [",
-        hasOpenBracket = true;
+          this.pos,
+          this.schemaString,
+          this.input,
+        );
       }
 
       this.skipWhitespace();
 
-      if (this.peek() === "]" && hasOpenBracket) {
+      if (this.peek() === "]") {
         this.consume();
         return [];
       }
@@ -464,7 +424,8 @@ class ValueParser {
         }
       }
 
-      if (hasOpenBracket) {
+      this.skipWhitespace();
+
       if (!this.consumeStr("]")) {
         throw new ParseError(
           "Expected ]",
@@ -473,7 +434,6 @@ class ValueParser {
           this.input,
         );
       }
-      }
 
       return ids;
     } else {
@@ -506,8 +466,7 @@ export function parseValue(
 ): unknown {
   const sStr = schemaString || schemaToTypeString(schema);
   const parser = new ValueParser(valueString.trim(), sStr);
-  const allowOmitBrackets = schema.type === "tuple" || schema.type === "array";
+  const value = parser.parseValue(schema);
-  const value = parser.parseValue(schema, allowOmitBrackets);
 
   if (parser.getPosition() < parser.getInputLength()) {
     throw new ParseError(