@iyulab/m3l 0.1.1 → 0.1.2

package/README.md

@@ -64,7 +64,7 @@ npx m3l validate ./models --strict --format json
 - bio(Biography): text?
 - birth_date: date?
 
-# Rollup
+### Rollup
 - book_count: integer @rollup(BookAuthor.author_id, count)
 
 > Stores information about book authors.
@@ -82,10 +82,10 @@ npx m3l validate ./models --strict --format json
   - borrowed: "Borrowed"
 - publisher_id: identifier @fk(Publisher.id)
 
-# Lookup
+### Lookup
 - publisher_name: string @lookup(publisher_id.name)
 
-# Computed
+### Computed
 - is_available: boolean @computed("status = 'available' AND quantity > 0")
 
 ## OverdueLoans ::view @materialized
@@ -110,9 +110,11 @@ npx m3l validate ./models --strict --format json
 | `- field: type` | Field definition |
 | `- field: type?` | Nullable field |
 | `- field: type[]` | Array field |
+| `- field: type?[]` | Array of nullable items |
 | `- field: type = val` | Field with default value |
 | `@attr` / `@attr(args)` | Attribute (constraint, index, etc.) |
-| `# Lookup` / `# Rollup` / `# Computed` | Kind section for derived fields |
+| `` `[FrameworkAttr]` `` | Custom framework attribute |
+| `### Lookup` / `### Rollup` / `### Computed` | Kind section for derived fields |
 | `### Section` | Named section (Indexes, Relations, Metadata, etc.) |
 | `> text` | Model/element description |
 | `"text"` | Inline description on field |
@@ -123,18 +125,54 @@ The parser produces an `M3LAST` object:
 
 ```typescript
 interface M3LAST {
+  parserVersion: string;   // Parser package version (semver)
+  astVersion: string;      // AST schema version
   project: { name?: string; version?: string };
-  sources: string[];         // parsed file paths
-  models: ModelNode[];       // models and interfaces
-  enums: EnumNode[];         // enum definitions
-  interfaces: ModelNode[];   // interface definitions
-  views: ModelNode[];        // derived views
-  errors: Diagnostic[];      // parse/resolve errors
-  warnings: Diagnostic[];    // validation warnings
+  sources: string[];
+  models: ModelNode[];
+  enums: EnumNode[];
+  interfaces: ModelNode[];
+  views: ModelNode[];
+  errors: Diagnostic[];
+  warnings: Diagnostic[];
 }
 ```
 
-Each `ModelNode` contains fields, sections (indexes, relations, metadata), inheritance info, and source locations for error reporting.
+### Key AST types
+
+```typescript
+interface FieldNode {
+  name: string;
+  label?: string;
+  type?: string;
+  params?: (string | number)[];
+  generic_params?: string[];     // map<K,V> → ["K", "V"]
+  nullable: boolean;
+  array: boolean;
+  arrayItemNullable: boolean;    // string?[] → true
+  kind: 'stored' | 'computed' | 'lookup' | 'rollup';
+  default_value?: string;
+  description?: string;
+  attributes: FieldAttribute[];
+  framework_attrs?: CustomAttribute[];
+  lookup?: { path: string };
+  rollup?: { target: string; fk: string; aggregate: string; field?: string; where?: string };
+  computed?: { expression: string };
+  enum_values?: EnumValue[];
+  fields?: FieldNode[];          // sub-fields for object type
+  loc: SourceLocation;
+}
+
+interface ModelNode {
+  name: string;
+  type: 'model' | 'enum' | 'interface' | 'view';
+  inherits: string[];
+  attributes: FieldAttribute[];  // model-level attributes (@public, etc.)
+  fields: FieldNode[];
+  sections: { indexes; relations; behaviors; metadata; [key: string]: unknown };
+  // ...
+}
+```
 
 ## Validation
 
@@ -143,20 +181,17 @@ The validator checks for semantic errors and style warnings:
 **Errors:**
 | Code | Description |
 |------|-------------|
-| E001 | Rollup FK field missing `@reference` |
-| E002 | Lookup FK field missing `@reference` |
-| E004 | View references non-existent model |
-| E005 | Duplicate model/enum name |
-| E006 | Duplicate field name within model |
-| E007 | Unresolved parent in inheritance |
+| M3L-E001 | Rollup FK field missing `@reference` |
+| M3L-E002 | Lookup FK field missing `@reference` |
+| M3L-E004 | View references non-existent model |
+| M3L-E006 | Duplicate field name within model |
 
 **Warnings (--strict):**
 | Code | Description |
 |------|-------------|
-| W001 | Model has no fields |
-| W002 | Model has no description |
-| W003 | Field missing label |
-| W004 | Enum has no values |
+| M3L-W001 | Field line exceeds 80 characters |
+| M3L-W002 | Object nesting exceeds 3 levels |
+| M3L-W004 | Lookup chain exceeds 3 hops |
 
 ## Multi-file Projects
 
@@ -197,6 +232,18 @@ const ast = resolve([parsed]);
 const diagnostics = validate(ast, { strict: true });
 ```
 
+## Compatibility
+
+This TypeScript parser and the [C# parser](../csharp/) produce equivalent AST structures. Both share the same conformance test suite.
+
+| | TypeScript | C# |
+|---|---|---|
+| Package | `@iyulab/m3l` | `Iyulab.M3L` |
+| Runtime | Node.js 20+ | .NET 8.0+ |
+| AST Version | 1.0 | 1.0 |
+
+Version is managed centrally via the root `VERSION` file.
+
 ## License
 
 MIT

package/dist/lexer.js

@@ -35,15 +35,20 @@ export function lex(content, file) {
             tokens.push({ type: 'horizontal_rule', raw, line: lineNum, indent: 0 });
             continue;
         }
-        // H3 — Section header
+        // H3 — Section header (including kind sections: ### Lookup, ### Rollup, ### Computed)
         const h3Match = raw.match(RE_H3);
         if (h3Match) {
+            const h3Name = h3Match[1].trim();
+            const data = { name: h3Name };
+            if (KIND_SECTIONS.has(h3Name)) {
+                data.kind_section = true;
+            }
             tokens.push({
                 type: 'section',
                 raw,
                 line: lineNum,
                 indent: 0,
-                data: { name: h3Match[1].trim() },
+                data,
             });
             continue;
         }
@@ -54,29 +59,17 @@ export function lex(content, file) {
             tokens.push(tokenizeH2(h2Content, raw, lineNum));
             continue;
         }
-        // H1 — Namespace or kind-section context
+        // H1 — Namespace / Document title only
         const h1Match = raw.match(RE_H1);
         if (h1Match) {
             const h1Content = h1Match[1].trim();
-            // Check if this is a kind section (# Lookup, # Rollup, # Computed)
-            if (KIND_SECTIONS.has(h1Content)) {
-                tokens.push({
-                    type: 'section',
-                    raw,
-                    line: lineNum,
-                    indent: 0,
-                    data: { name: h1Content, kind_section: true },
-                });
-            }
-            else {
-                tokens.push({
-                    type: 'namespace',
-                    raw,
-                    line: lineNum,
-                    indent: 0,
-                    data: parseNamespace(h1Content),
-                });
-            }
+            tokens.push({
+                type: 'namespace',
+                raw,
+                line: lineNum,
+                indent: 0,
+                data: parseNamespace(h1Content),
+            });
             continue;
         }
         // Blockquote
@@ -331,9 +324,24 @@ export function parseTypeAndAttrs(rest, data) {
             skipWS();
         }
     }
-    // Parse attributes: @name or @name(balanced_args)
+    // Parse attributes: @name or @name(balanced_args), with optional cascade symbols (! !!)
     const attrs = [];
-    while (pos < len && rest[pos] === '@') {
+    while (pos < len && (rest[pos] === '@' || rest[pos] === '!' || rest[pos] === '?')) {
+        // Cascade symbols: !, !!, ? — attach to the previous attribute
+        if (rest[pos] === '!' || rest[pos] === '?') {
+            let symbol = rest[pos];
+            pos++;
+            if (symbol === '!' && pos < len && rest[pos] === '!') {
+                symbol = '!!';
+                pos++;
+            }
+            // Attach cascade to last attribute
+            if (attrs.length > 0) {
+                attrs[attrs.length - 1].cascade = symbol;
+            }
+            skipWS();
+            continue;
+        }
         pos++; // skip @
         const nameStart = pos;
         while (pos < len && /\w/.test(rest[pos]))

package/dist/parser.js

@@ -75,11 +75,6 @@ function processToken(token, state) {
 }
 function handleNamespace(token, state) {
     const data = token.data;
-    // Check if this is a kind section (# Lookup, # Rollup, etc.)
-    if (data.kind_section) {
-        handleSection(token, state);
-        return;
-    }
     if (!state.currentElement) {
         state.namespace = data.name;
     }
@@ -554,20 +549,61 @@ function buildFieldNode(data, token, state) {
         const expr = computedAttr.args[0].replace(/^["']|["']$/g, '');
         field.computed = { expression: expr };
     }
-    // Parse computed_raw: @computed_raw("expression", ...)
+    // Parse computed_raw: @computed_raw("expression", platform: "name")
     if (computedRawAttr && computedRawAttr.args?.[0]) {
-        const expr = computedRawAttr.args[0].replace(/^["']|["']$/g, '');
+        const rawArgs = computedRawAttr.args[0];
+        const parts = splitComputedRawArgs(rawArgs);
+        const expr = parts.expression.replace(/^["']|["']$/g, '');
         field.computed = { expression: expr };
+        if (parts.platform) {
+            field.computed.platform = parts.platform;
+        }
     }
     return field;
 }
+/**
+ * Split @computed_raw args: "expr", platform: "name"
+ * Returns the expression (first positional arg) and optional named params.
+ */
+function splitComputedRawArgs(raw) {
+    // Find the first quoted string as the expression
+    const quoteChar = raw[0];
+    if (quoteChar === '"' || quoteChar === "'") {
+        // Find matching closing quote (not escaped)
+        let i = 1;
+        while (i < raw.length) {
+            if (raw[i] === '\\') {
+                i += 2;
+                continue;
+            }
+            if (raw[i] === quoteChar)
+                break;
+            i++;
+        }
+        const expression = raw.slice(0, i + 1); // includes quotes
+        const remainder = raw.slice(i + 1).trim();
+        // Parse named params from remainder: , platform: "sqlserver"
+        let platform;
+        const platformMatch = remainder.match(/platform\s*:\s*["']([^"']+)["']/);
+        if (platformMatch) {
+            platform = platformMatch[1];
+        }
+        return { expression, platform };
+    }
+    // No quotes — treat entire string as expression
+    return { expression: raw };
+}
 function parseAttributes(rawAttrs) {
     if (!rawAttrs)
         return [];
-    return rawAttrs.map(a => ({
-        name: a.name,
-        args: a.args ? [a.args] : undefined,
-    }));
+    return rawAttrs.map(a => {
+        const attr = { name: a.name };
+        if (a.args)
+            attr.args = [a.args];
+        if (a.cascade)
+            attr.cascade = a.cascade;
+        return attr;
+    });
 }
 function parseTypeParams(params) {
     if (!params)
@@ -697,8 +733,12 @@ function parseMetadataValue(value) {
     if (typeof value !== 'string')
         return value;
     const str = value;
-    // Remove surrounding quotes
+    // If explicitly quoted, preserve as string (don't coerce "1.0" to number)
+    const wasQuoted = (str.startsWith('"') && str.endsWith('"')) ||
+        (str.startsWith("'") && str.endsWith("'"));
     const unquoted = str.replace(/^["']|["']$/g, '');
+    if (wasQuoted)
+        return unquoted;
     // Try number
     const n = Number(unquoted);
     if (!isNaN(n) && unquoted !== '')

package/dist/resolver.d.ts

@@ -2,7 +2,7 @@ import type { ParsedFile, M3LAST, ProjectInfo } from './types.js';
 /** AST schema version — bump major on breaking structure changes */
 export declare const AST_VERSION = "1.0";
 /** Parser package version — kept in sync with package.json */
-export declare const PARSER_VERSION = "0.1.1";
+export declare const PARSER_VERSION = "0.1.2";
 /**
  * Resolve and merge multiple parsed file ASTs into a single M3LAST.
  * Handles: inheritance resolution, duplicate detection, reference validation.

package/dist/resolver.js

@@ -1,7 +1,7 @@
 /** AST schema version — bump major on breaking structure changes */
 export const AST_VERSION = '1.0';
 /** Parser package version — kept in sync with package.json */
-export const PARSER_VERSION = '0.1.1';
+export const PARSER_VERSION = '0.1.2';
 /**
  * Resolve and merge multiple parsed file ASTs into a single M3LAST.
  * Handles: inheritance resolution, duplicate detection, reference validation.
@@ -131,11 +131,10 @@ function resolveInheritance(model, modelMap, interfaceMap, allNamedMap, errors)
     // Handle @override: child fields with @override replace inherited fields
     const overrideNames = new Set();
     for (const ownField of model.fields) {
-        const overrideIdx = ownField.attributes.findIndex(a => a.name === 'override');
-        if (overrideIdx >= 0) {
+        const hasOverride = ownField.attributes.some(a => a.name === 'override');
+        if (hasOverride) {
             overrideNames.add(ownField.name);
-            // Remove @override attribute from the child field
-            ownField.attributes.splice(overrideIdx, 1);
+            // Preserve @override in attributes so AST consumers can detect it
         }
     }
     // Remove inherited fields that are overridden

package/dist/types.d.ts

@@ -16,6 +16,7 @@ export type FieldKind = 'stored' | 'computed' | 'lookup' | 'rollup';
 export interface FieldAttribute {
     name: string;
     args?: (string | number | boolean)[];
+    cascade?: string;
 }
 /** Structured representation of a backtick-wrapped framework attribute like `[MaxLength(100)]` */
 export interface CustomAttribute {
@@ -56,6 +57,7 @@ export interface FieldNode {
     };
     computed?: {
         expression: string;
+        platform?: string;
     };
     enum_values?: EnumValue[];
     fields?: FieldNode[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/m3l",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "M3L parser and CLI tool — parse .m3l.md files into JSON AST",
   "type": "module",
   "main": "dist/index.js",