@iyulab/m3l 0.1.0 → 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/index.d.ts

@@ -1,6 +1,6 @@
 export { lex } from './lexer.js';
 export { parseTokens, parseString as parseFileString } from './parser.js';
-export { resolve } from './resolver.js';
+export { resolve, AST_VERSION, PARSER_VERSION } from './resolver.js';
 export { validate } from './validator.js';
 export { readM3LFiles, readM3LString, readProjectConfig } from './reader.js';
 export type * from './types.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { lex } from './lexer.js';
 export { parseTokens, parseString as parseFileString } from './parser.js';
-export { resolve } from './resolver.js';
+export { resolve, AST_VERSION, PARSER_VERSION } from './resolver.js';
 export { validate } from './validator.js';
 export { readM3LFiles, readM3LString, readProjectConfig } from './reader.js';
 import { readM3LFiles, readProjectConfig } from './reader.js';

package/dist/lexer.d.ts

@@ -3,3 +3,4 @@ import type { Token } from './types.js';
  * Tokenize M3L markdown content into a sequence of tokens.
  */
 export declare function lex(content: string, file: string): Token[];
+export declare function parseTypeAndAttrs(rest: string, data: Record<string, unknown>): void;

package/dist/lexer.js

@@ -11,7 +11,7 @@ const RE_TYPE_INDICATOR = /^([\w][\w.]*(?:\([^)]*\))?)\s*::(\w+)(.*)$/;
 const RE_MODEL_DEF = /^([\w][\w.]*(?:\([^)]*\))?)\s*(?::\s*(.+?))?(\s+@.+)?$/;
 // Field line patterns
 const RE_FIELD_NAME = /^([\w]+)(?:\(([^)]*)\))?\s*(?::\s*(.+))?$/;
-const RE_TYPE_PART = /^([\w]+)(?:\(([^)]*)\))?(\?)?(\[\])?/;
+const RE_TYPE_PART = /^([\w]+)(?:<([^>]+)>)?(?:\(([^)]*)\))?(\?)?(\[\])?(\?)?/;
 const RE_FRAMEWORK_ATTR = /`\[([^\]]+)\]`/g;
 const RE_INLINE_COMMENT = /\s+#\s+(.+)$/;
 // Known kind-context H1 headers
@@ -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
@@ -264,7 +257,7 @@ function parseFieldLine(content) {
     parseTypeAndAttrs(rest, data);
     return data;
 }
-function parseTypeAndAttrs(rest, data) {
+export function parseTypeAndAttrs(rest, data) {
     let pos = 0;
     const len = rest.length;
     const skipWS = () => { while (pos < len && rest[pos] === ' ')
@@ -277,15 +270,29 @@ function parseTypeAndAttrs(rest, data) {
             return;
         }
     }
-    // Parse type: word(params)?[]?
+    // Parse type: word<generics>?(params)?[]??
     const typeMatch = rest.match(RE_TYPE_PART);
     if (typeMatch) {
         data.type_name = typeMatch[1];
+        // Group 2: generic params from <K,V>
         if (typeMatch[2]) {
-            data.type_params = typeMatch[2].split(',').map(s => s.trim());
+            data.type_generic_params = typeMatch[2].split(',').map(s => s.trim());
+        }
+        // Group 3: size/type params from (params)
+        if (typeMatch[3]) {
+            data.type_params = typeMatch[3].split(',').map(s => s.trim());
+        }
+        // Group 5: array
+        data.array = typeMatch[5] === '[]';
+        // Group 4: ? before [] = element nullable; Group 6: ? after [] = container nullable
+        if (data.array) {
+            data.nullable = typeMatch[6] === '?';
+            data.arrayItemNullable = typeMatch[4] === '?';
+        }
+        else {
+            data.nullable = typeMatch[4] === '?' || typeMatch[6] === '?';
+            data.arrayItemNullable = false;
         }
-        data.nullable = typeMatch[3] === '?';
-        data.array = typeMatch[4] === '[]';
         pos = typeMatch[0].length;
         skipWS();
     }
@@ -317,9 +324,24 @@ 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

@@ -1,4 +1,4 @@
-import { lex } from './lexer.js';
+import { lex, parseTypeAndAttrs } from './lexer.js';
 /**
  * Parse M3L content string into a ParsedFile AST.
  */
@@ -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;
     }
@@ -87,6 +82,7 @@ function handleNamespace(token, state) {
 function handleModelStart(token, state) {
     finalizeElement(state);
     const data = token.data;
+    const modelAttrs = parseAttributes(data.attributes);
     const model = {
         name: data.name,
         label: data.label,
@@ -94,6 +90,7 @@ function handleModelStart(token, state) {
         source: state.file,
         line: token.line,
         inherits: data.inherits || [],
+        attributes: modelAttrs,
         fields: [],
         sections: {
             indexes: [],
@@ -137,6 +134,7 @@ function handleViewStart(token, state) {
         source: state.file,
         line: token.line,
         inherits: [],
+        attributes: [],
         materialized: data.materialized || false,
         fields: [],
         sections: {
@@ -248,15 +246,25 @@ function handleDirective(data, model, token, state) {
         });
     }
     else {
-        // Generic directive
-        const sectionName = attr.name;
-        if (!model.sections[sectionName]) {
-            model.sections[sectionName] = [];
+        // Generic directive — normalize singular form
+        let sectionName = attr.name;
+        if (sectionName === 'behavior')
+            sectionName = 'behaviors';
+        if (sectionName === 'behaviors') {
+            model.sections.behaviors.push({
+                raw: data.raw_content,
+                args: attr.args,
+            });
+        }
+        else {
+            if (!model.sections[sectionName]) {
+                model.sections[sectionName] = [];
+            }
+            model.sections[sectionName].push({
+                raw: data.raw_content,
+                args: attr.args,
+            });
         }
-        model.sections[sectionName].push({
-            raw: data.raw_content,
-            args: attr.args,
-        });
     }
 }
 function handleSectionItem(data, model, token, state) {
@@ -332,10 +340,17 @@ function handleSectionItem(data, model, token, state) {
         });
         return;
     }
-    // Generic section — treat as fields
-    const field = buildFieldNode(data, token, state);
-    model.fields.push(field);
-    state.lastField = field;
+    // Generic section — store as section items, NOT as fields
+    if (!model.sections[section]) {
+        model.sections[section] = [];
+    }
+    model.sections[section].push({
+        name: data.name,
+        raw: token.raw.trim(),
+        value: data.type_name || data.description || data.raw_value,
+        loc,
+    });
+    state.lastField = null;
 }
 function handleNestedItem(token, state) {
     if (!state.currentElement)
@@ -402,6 +417,29 @@ function handleNestedItem(token, state) {
             });
             return;
         }
+        // Sub-field for object/nested type
+        if (key && value) {
+            // Walk up to find the nearest object-type ancestor for this indent level
+            const parentField = field;
+            if (parentField.type === 'object') {
+                if (!parentField.fields)
+                    parentField.fields = [];
+                // Re-parse value as type and attributes
+                const subData = { name: key };
+                parseTypeAndAttrs(value, subData);
+                // Only treat as sub-field if a type was extracted
+                if (subData.type_name) {
+                    const subField = buildFieldNode(subData, token, state);
+                    parentField.fields.push(subField);
+                    // If the sub-field is also an object, set it as lastField for deeper nesting
+                    if (subField.type === 'object') {
+                        state.lastField = subField;
+                    }
+                    // Otherwise keep lastField pointing to the parent object for siblings
+                    return;
+                }
+            }
+        }
         // Extended format field attributes
         if (key) {
             applyExtendedAttribute(field, key, value || '');
@@ -472,6 +510,7 @@ function buildFieldNode(data, token, state) {
     const lookupAttr = attrs.find(a => a.name === 'lookup');
     const rollupAttr = attrs.find(a => a.name === 'rollup');
     const computedAttr = attrs.find(a => a.name === 'computed');
+    const computedRawAttr = attrs.find(a => a.name === 'computed_raw');
     const fromAttr = attrs.find(a => a.name === 'from');
     if (lookupAttr)
         kind = 'lookup';
@@ -479,18 +518,22 @@ function buildFieldNode(data, token, state) {
         kind = 'rollup';
     else if (computedAttr)
         kind = 'computed';
+    else if (computedRawAttr)
+        kind = 'computed';
     const field = {
         name: data.name,
         label: data.label,
         type: data.type_name,
         params: parseTypeParams(data.type_params),
+        generic_params: data.type_generic_params,
         nullable: data.nullable || false,
         array: data.array || false,
+        arrayItemNullable: data.arrayItemNullable || false,
         kind,
         default_value: data.default_value,
         description: data.description,
         attributes: attrs,
-        framework_attrs: data.framework_attrs,
+        framework_attrs: parseCustomAttributes(data.framework_attrs),
         loc: { file: state.file, line: token.line, col: 1 },
     };
     // Parse lookup
@@ -506,15 +549,61 @@ function buildFieldNode(data, token, state) {
         const expr = computedAttr.args[0].replace(/^["']|["']$/g, '');
         field.computed = { expression: expr };
     }
+    // Parse computed_raw: @computed_raw("expression", platform: "name")
+    if (computedRawAttr && computedRawAttr.args?.[0]) {
+        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)
@@ -644,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 !== '')
@@ -699,6 +792,15 @@ function applyExtendedAttribute(field, key, value) {
             break;
     }
 }
+function parseCustomAttributes(rawAttrs) {
+    if (!rawAttrs || rawAttrs.length === 0)
+        return undefined;
+    return rawAttrs.map(raw => {
+        // raw is "[MaxLength(100)]" — strip brackets to get content
+        const content = raw.replace(/^\[|\]$/g, '');
+        return { content, raw };
+    });
+}
 function isEnumNode(el) {
     return el.type === 'enum' && 'values' in el;
 }

package/dist/resolver.d.ts

@@ -1,4 +1,8 @@
 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.2";
 /**
  * Resolve and merge multiple parsed file ASTs into a single M3LAST.
  * Handles: inheritance resolution, duplicate detection, reference validation.

package/dist/resolver.js

@@ -1,3 +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.2';
 /**
  * Resolve and merge multiple parsed file ASTs into a single M3LAST.
  * Handles: inheritance resolution, duplicate detection, reference validation.
@@ -58,6 +62,8 @@ export function resolve(files, project) {
             projectInfo.name = ns;
     }
     return {
+        parserVersion: PARSER_VERSION,
+        astVersion: AST_VERSION,
         project: projectInfo,
         sources,
         models: allModels,
@@ -72,7 +78,7 @@ function checkDuplicate(name, kind, item, map, allMap, errors) {
     const existing = allMap.get(name);
     if (existing) {
         errors.push({
-            code: 'E005',
+            code: 'M3L-E005',
             severity: 'error',
             file: item.source,
             line: item.line,
@@ -95,7 +101,7 @@ function resolveInheritance(model, modelMap, interfaceMap, allNamedMap, errors)
         if (!parent) {
             if (!allNamedMap.has(name)) {
                 errors.push({
-                    code: 'E007',
+                    code: 'M3L-E007',
                     severity: 'error',
                     file: fromModel.source,
                     line: fromModel.line,
@@ -122,9 +128,20 @@ function resolveInheritance(model, modelMap, interfaceMap, allNamedMap, errors)
     for (const parentName of model.inherits) {
         collectFields(parentName, model);
     }
+    // Handle @override: child fields with @override replace inherited fields
+    const overrideNames = new Set();
+    for (const ownField of model.fields) {
+        const hasOverride = ownField.attributes.some(a => a.name === 'override');
+        if (hasOverride) {
+            overrideNames.add(ownField.name);
+            // Preserve @override in attributes so AST consumers can detect it
+        }
+    }
+    // Remove inherited fields that are overridden
+    const filteredInherited = inheritedFields.filter(f => !overrideNames.has(f.name));
     // Prepend inherited fields before model's own fields
-    if (inheritedFields.length > 0) {
-        model.fields = [...inheritedFields, ...model.fields];
+    if (filteredInherited.length > 0) {
+        model.fields = [...filteredInherited, ...model.fields];
     }
 }
 function checkDuplicateFields(model, errors) {
@@ -133,7 +150,7 @@ function checkDuplicateFields(model, errors) {
         const existing = seen.get(field.name);
         if (existing) {
             errors.push({
-                code: 'E005',
+                code: 'M3L-E005',
                 severity: 'error',
                 file: field.loc.file,
                 line: field.loc.line,

package/dist/types.d.ts

@@ -15,7 +15,15 @@ export interface Token {
 export type FieldKind = 'stored' | 'computed' | 'lookup' | 'rollup';
 export interface FieldAttribute {
     name: string;
-    args?: unknown[];
+    args?: (string | number | boolean)[];
+    cascade?: string;
+}
+/** Structured representation of a backtick-wrapped framework attribute like `[MaxLength(100)]` */
+export interface CustomAttribute {
+    /** Content inside brackets, e.g., "MaxLength(100)" for `[MaxLength(100)]` */
+    content: string;
+    /** Original text including brackets, e.g., "[MaxLength(100)]" */
+    raw: string;
 }
 export interface EnumValue {
     name: string;
@@ -28,13 +36,15 @@ export interface FieldNode {
     label?: string;
     type?: string;
     params?: (string | number)[];
+    generic_params?: string[];
     nullable: boolean;
     array: boolean;
+    arrayItemNullable: boolean;
     kind: FieldKind;
     default_value?: string;
     description?: string;
     attributes: FieldAttribute[];
-    framework_attrs?: string[];
+    framework_attrs?: CustomAttribute[];
     lookup?: {
         path: string;
     };
@@ -47,6 +57,7 @@ export interface FieldNode {
     };
     computed?: {
         expression: string;
+        platform?: string;
     };
     enum_values?: EnumValue[];
     fields?: FieldNode[];
@@ -60,6 +71,7 @@ export interface ModelNode {
     line: number;
     inherits: string[];
     description?: string;
+    attributes: FieldAttribute[];
     fields: FieldNode[];
     sections: {
         indexes: unknown[];
@@ -117,6 +129,10 @@ export interface ParsedFile {
     views: ModelNode[];
 }
 export interface M3LAST {
+    /** Parser package version (semver) */
+    parserVersion: string;
+    /** AST schema version — incremented on breaking AST structure changes */
+    astVersion: string;
     project: ProjectInfo;
     sources: string[];
     models: ModelNode[];

package/dist/validator.js

@@ -9,7 +9,7 @@ export function validate(ast, options = {}) {
     for (const m of allModels) {
         modelMap.set(m.name, m);
     }
-    // E001: @rollup FK missing @reference
+    // M3L-E001: @rollup FK missing @reference
     for (const model of allModels) {
         for (const field of model.fields) {
             if (field.kind === 'rollup' && field.rollup) {
@@ -17,7 +17,7 @@ export function validate(ast, options = {}) {
             }
         }
     }
-    // E002: @lookup path FK missing @reference
+    // M3L-E002: @lookup path FK missing @reference
     for (const model of allModels) {
         for (const field of model.fields) {
             if (field.kind === 'lookup' && field.lookup) {
@@ -25,12 +25,12 @@ export function validate(ast, options = {}) {
             }
         }
     }
-    // E004: View @from references model not found
+    // M3L-E004: View @from references model not found
     for (const view of ast.views) {
         if (view.source_def?.from) {
             if (!modelMap.has(view.source_def.from)) {
                 errors.push({
-                    code: 'E004',
+                    code: 'M3L-E004',
                     severity: 'error',
                     file: view.source,
                     line: view.line,
@@ -40,13 +40,13 @@ export function validate(ast, options = {}) {
             }
         }
     }
-    // E005: Duplicate field names (already checked in resolver, but re-check for safety)
+    // M3L-E006: Duplicate field names (already checked in resolver, but re-check for safety)
     for (const model of allModels) {
         const seen = new Set();
         for (const field of model.fields) {
             if (seen.has(field.name)) {
                 errors.push({
-                    code: 'E005',
+                    code: 'M3L-E006',
                     severity: 'error',
                     file: field.loc.file,
                     line: field.loc.line,
@@ -61,16 +61,16 @@ export function validate(ast, options = {}) {
     if (options.strict) {
         for (const model of allModels) {
             for (const field of model.fields) {
-                // W001: Field line length > 80 chars
+                // M3L-W001: Field line length > 80 chars
                 // We check the source loc raw length — approximate using field attributes count
                 checkFieldLineLength(field, model, warnings);
-                // W003: Framework attrs without backtick (already processed in lexer, skip)
-                // W004: Lookup chain > 3 hops
+                // M3L-W003: Framework attrs without backtick (already processed in lexer, skip)
+                // M3L-W004: Lookup chain > 3 hops
                 if (field.kind === 'lookup' && field.lookup) {
                     const hops = field.lookup.path.split('.').length;
                     if (hops > 3) {
                         warnings.push({
-                            code: 'W004',
+                            code: 'M3L-W004',
                             severity: 'warning',
                             file: field.loc.file,
                             line: field.loc.line,
@@ -80,10 +80,10 @@ export function validate(ast, options = {}) {
                     }
                 }
             }
-            // W002: Object nesting > 3 levels
+            // M3L-W002: Object nesting > 3 levels
             checkNestingDepth(model.fields, 1, model, warnings);
         }
-        // W006: Inline enum missing values: key
+        // M3L-W006: Inline enum missing values: key
         for (const model of allModels) {
             for (const field of model.fields) {
                 if (field.type === 'enum' && field.enum_values && field.enum_values.length > 0) {
@@ -102,7 +102,7 @@ function validateRollupReference(field, model, modelMap, errors) {
     const rollup = field.rollup;
     const targetModel = modelMap.get(rollup.target);
     if (!targetModel) {
-        // Target model doesn't exist — this is E007 (already caught in resolver)
+        // Target model doesn't exist — this is M3L-E007 (already caught in resolver)
         return;
     }
     // Check that the FK field in the target model has @reference or @fk
@@ -114,7 +114,7 @@ function validateRollupReference(field, model, modelMap, errors) {
     const hasReference = fkField.attributes.some(a => a.name === 'reference' || a.name === 'fk');
     if (!hasReference) {
         errors.push({
-            code: 'E001',
+            code: 'M3L-E001',
             severity: 'error',
             file: field.loc.file,
             line: field.loc.line,
@@ -136,7 +136,7 @@ function validateLookupReference(field, model, modelMap, errors) {
     const hasReference = fkField.attributes.some(a => a.name === 'reference' || a.name === 'fk');
     if (!hasReference) {
         errors.push({
-            code: 'E002',
+            code: 'M3L-E002',
             severity: 'error',
             file: field.loc.file,
             line: field.loc.line,
@@ -168,7 +168,7 @@ function checkFieldLineLength(field, model, warnings) {
         len += 3 + field.description.length;
     if (len > 80) {
         warnings.push({
-            code: 'W001',
+            code: 'M3L-W001',
             severity: 'warning',
             file: field.loc.file,
             line: field.loc.line,
@@ -182,7 +182,7 @@ function checkNestingDepth(fields, depth, model, warnings) {
         if (field.fields && field.fields.length > 0) {
             if (depth >= 3) {
                 warnings.push({
-                    code: 'W002',
+                    code: 'M3L-W002',
                     severity: 'warning',
                     file: field.loc.file,
                     line: field.loc.line,

package/package.json

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