@iyulab/m3l 0.1.0 → 0.1.1

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
@@ -264,7 +264,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 +277,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();
     }

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.
  */
@@ -87,6 +87,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 +95,7 @@ function handleModelStart(token, state) {
         source: state.file,
         line: token.line,
         inherits: data.inherits || [],
+        attributes: modelAttrs,
         fields: [],
         sections: {
             indexes: [],
@@ -137,6 +139,7 @@ function handleViewStart(token, state) {
         source: state.file,
         line: token.line,
         inherits: [],
+        attributes: [],
         materialized: data.materialized || false,
         fields: [],
         sections: {
@@ -248,15 +251,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 +345,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 +422,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 +515,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 +523,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,6 +554,11 @@ function buildFieldNode(data, token, state) {
         const expr = computedAttr.args[0].replace(/^["']|["']$/g, '');
         field.computed = { expression: expr };
     }
+    // Parse computed_raw: @computed_raw("expression", ...)
+    if (computedRawAttr && computedRawAttr.args?.[0]) {
+        const expr = computedRawAttr.args[0].replace(/^["']|["']$/g, '');
+        field.computed = { expression: expr };
+    }
     return field;
 }
 function parseAttributes(rawAttrs) {
@@ -699,6 +752,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.1";
 /**
  * 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.1';
 /**
  * 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,21 @@ 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 overrideIdx = ownField.attributes.findIndex(a => a.name === 'override');
+        if (overrideIdx >= 0) {
+            overrideNames.add(ownField.name);
+            // Remove @override attribute from the child field
+            ownField.attributes.splice(overrideIdx, 1);
+        }
+    }
+    // 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 +151,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,14 @@ export interface Token {
 export type FieldKind = 'stored' | 'computed' | 'lookup' | 'rollup';
 export interface FieldAttribute {
     name: string;
-    args?: unknown[];
+    args?: (string | number | boolean)[];
+}
+/** 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 +35,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;
     };
@@ -60,6 +69,7 @@ export interface ModelNode {
     line: number;
     inherits: string[];
     description?: string;
+    attributes: FieldAttribute[];
     fields: FieldNode[];
     sections: {
         indexes: unknown[];
@@ -117,6 +127,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.1",
   "description": "M3L parser and CLI tool — parse .m3l.md files into JSON AST",
   "type": "module",
   "main": "dist/index.js",