@iyulab/m3l 0.1.2 → 0.1.3

package/README.md

@@ -238,7 +238,7 @@ This TypeScript parser and the [C# parser](../csharp/) produce equivalent AST st
 
 | | TypeScript | C# |
 |---|---|---|
-| Package | `@iyulab/m3l` | `Iyulab.M3L` |
+| Package | `@iyulab/m3l` | `M3LParser` |
 | Runtime | Node.js 20+ | .NET 8.0+ |
 | AST Version | 1.0 | 1.0 |
 

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,5 +1,5 @@
 export { lex } from './lexer.js';
-export { parseTokens, parseString as parseFileString } from './parser.js';
+export { parseTokens, parseString as parseFileString, STANDARD_ATTRIBUTES } from './parser.js';
 export { resolve, AST_VERSION, PARSER_VERSION } from './resolver.js';
 export { validate } from './validator.js';
 export { readM3LFiles, readM3LString, readProjectConfig } from './reader.js';
@@ -15,7 +15,7 @@ export async function parse(inputPath) {
     const resolved = resolvePath(inputPath);
     const files = await readM3LFiles(resolved);
     if (files.length === 0) {
-        throw new Error(`No .m3l.md files found at: ${inputPath}`);
+        throw new Error(`No .m3l.md or .m3l files found at: ${inputPath}`);
     }
     const parsedFiles = files.map(f => parseFileContent(f.content, f.path));
     let projectInfo;

package/dist/lexer.js

@@ -7,7 +7,7 @@ const RE_BLOCKQUOTE = /^> (.+)$/;
 const RE_LIST_ITEM = /^(\s*)- (.+)$/;
 const RE_BLANK = /^\s*$/;
 // H2 sub-patterns
-const RE_TYPE_INDICATOR = /^([\w][\w.]*(?:\([^)]*\))?)\s*::(\w+)(.*)$/;
+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*(.+))?$/;
@@ -135,7 +135,7 @@ export function lex(content, file) {
     return tokens;
 }
 function tokenizeH2(content, raw, line) {
-    // Check for type indicator: ## Name ::enum, ::interface, ::view
+    // Check for type indicator: ## Name ::enum, ::interface, ::view, ::attribute
     const typeMatch = content.match(RE_TYPE_INDICATOR);
     if (typeMatch) {
         const namepart = typeMatch[1];
@@ -151,7 +151,8 @@ function tokenizeH2(content, raw, line) {
         if (descMatch) {
             data.description = descMatch[1];
         }
-        return { type: typeIndicator, raw, line, indent: 0, data };
+        const tokenType = typeIndicator === 'attribute' ? 'attribute_def' : typeIndicator;
+        return { type: tokenType, raw, line, indent: 0, data };
     }
     // Regular model: ## Name : Parent1, Parent2
     const modelMatch = content.match(RE_MODEL_DEF);

package/dist/parser.d.ts

@@ -1,4 +1,9 @@
 import type { Token, ParsedFile } from './types.js';
+/**
+ * Standard M3L attribute catalog.
+ * These are the officially defined attributes in the M3L specification.
+ */
+export declare const STANDARD_ATTRIBUTES: Set<string>;
 /**
  * Parse M3L content string into a ParsedFile AST.
  */

package/dist/parser.js

@@ -1,4 +1,22 @@
 import { lex, parseTypeAndAttrs } from './lexer.js';
+/**
+ * Standard M3L attribute catalog.
+ * These are the officially defined attributes in the M3L specification.
+ */
+export const STANDARD_ATTRIBUTES = new Set([
+    // Field constraints
+    'primary', 'unique', 'required', 'index', 'generated', 'immutable',
+    // References / relations
+    'reference', 'fk', 'relation', 'on_update', 'on_delete',
+    // Search / display
+    'searchable', 'description', 'visibility',
+    // Validation
+    'min', 'max', 'validate', 'not_null',
+    // Derived fields
+    'computed', 'computed_raw', 'lookup', 'rollup', 'from', 'persisted',
+    // Model-level
+    'public', 'private', 'materialized', 'meta', 'behavior', 'override', 'default_attribute',
+]);
 /**
  * Parse M3L content string into a ParsedFile AST.
  */
@@ -21,6 +39,8 @@ export function parseTokens(tokens, file) {
         enums: [],
         interfaces: [],
         views: [],
+        attributeRegistry: [],
+        currentAttrDef: null,
         sourceDirectivesDone: false,
     };
     for (const token of tokens) {
@@ -35,6 +55,7 @@ export function parseTokens(tokens, file) {
         enums: state.enums,
         interfaces: state.interfaces,
         views: state.views,
+        attributeRegistry: state.attributeRegistry,
     };
 }
 function processToken(token, state) {
@@ -52,6 +73,9 @@ function processToken(token, state) {
         case 'view':
             handleViewStart(token, state);
             break;
+        case 'attribute_def':
+            handleAttributeDefStart(token, state);
+            break;
         case 'section':
             handleSection(token, state);
             break;
@@ -181,6 +205,18 @@ function handleSection(token, state) {
     }
 }
 function handleField(token, state) {
+    // Handle attribute definition fields (- target: [field, model])
+    if (state.currentAttrDef) {
+        const data = token.data;
+        const name = data.name;
+        const raw = token.raw.trim().replace(/^-\s*/, '');
+        const colonIdx = raw.indexOf(':');
+        if (colonIdx >= 0) {
+            const value = raw.substring(colonIdx + 1).trim();
+            state.currentAttrDef.fields.set(name, value);
+        }
+        return;
+    }
     if (!state.currentElement)
         return;
     const data = token.data;
@@ -455,6 +491,12 @@ function handleNestedItem(token, state) {
     }
 }
 function handleBlockquote(token, state) {
+    // Handle attribute definition description
+    if (state.currentAttrDef) {
+        const text = token.data.text;
+        state.currentAttrDef.description = text;
+        return;
+    }
     if (!state.currentElement)
         return;
     const text = token.data.text;
@@ -478,6 +520,8 @@ function handleText(token, state) {
     }
 }
 function finalizeElement(state) {
+    // Finalize pending attribute definition
+    finalizeAttrDef(state);
     if (!state.currentElement)
         return;
     if (isEnumNode(state.currentElement)) {
@@ -502,6 +546,70 @@ function finalizeElement(state) {
     state.currentKind = 'stored';
     state.lastField = null;
 }
+function handleAttributeDefStart(token, state) {
+    finalizeElement(state);
+    const data = token.data || {};
+    const name = (data.name || '').replace(/^@/, '');
+    state.currentAttrDef = {
+        name,
+        description: data.description,
+        fields: new Map(),
+    };
+    state.currentElement = null;
+}
+function finalizeAttrDef(state) {
+    if (!state.currentAttrDef)
+        return;
+    const def = state.currentAttrDef;
+    const fields = def.fields;
+    const targetRaw = fields.get('target');
+    const target = [];
+    if (targetRaw) {
+        const cleaned = targetRaw.replace(/^\[|\]$/g, '').split(',').map(s => s.trim());
+        for (const t of cleaned) {
+            if (t === 'field' || t === 'model')
+                target.push(t);
+        }
+    }
+    const rangeRaw = fields.get('range');
+    let range;
+    if (rangeRaw) {
+        const nums = rangeRaw.replace(/^\[|\]$/g, '').split(',').map(s => Number(s.trim()));
+        if (nums.length === 2 && !isNaN(nums[0]) && !isNaN(nums[1])) {
+            range = [nums[0], nums[1]];
+        }
+    }
+    const requiredRaw = fields.get('required');
+    const required = requiredRaw === 'true' || requiredRaw === true;
+    const defaultRaw = fields.get('default');
+    let defaultValue;
+    if (defaultRaw !== undefined) {
+        if (defaultRaw === 'true')
+            defaultValue = true;
+        else if (defaultRaw === 'false')
+            defaultValue = false;
+        else if (typeof defaultRaw === 'string' && !isNaN(Number(defaultRaw)))
+            defaultValue = Number(defaultRaw);
+        else if (typeof defaultRaw === 'string')
+            defaultValue = defaultRaw;
+        else if (typeof defaultRaw === 'number' || typeof defaultRaw === 'boolean')
+            defaultValue = defaultRaw;
+    }
+    const entry = {
+        name: def.name,
+        target: target.length > 0 ? target : ['field'],
+        type: fields.get('type') || 'boolean',
+        required,
+    };
+    if (def.description)
+        entry.description = def.description;
+    if (range)
+        entry.range = range;
+    if (defaultValue !== undefined)
+        entry.defaultValue = defaultValue;
+    state.attributeRegistry.push(entry);
+    state.currentAttrDef = null;
+}
 // --- Helpers ---
 function buildFieldNode(data, token, state) {
     const attrs = parseAttributes(data.attributes);
@@ -602,6 +710,8 @@ function parseAttributes(rawAttrs) {
             attr.args = [a.args];
         if (a.cascade)
             attr.cascade = a.cascade;
+        if (STANDARD_ATTRIBUTES.has(a.name))
+            attr.isStandard = true;
         return attr;
     });
 }
@@ -798,9 +908,57 @@ function parseCustomAttributes(rawAttrs) {
     return rawAttrs.map(raw => {
         // raw is "[MaxLength(100)]" — strip brackets to get content
         const content = raw.replace(/^\[|\]$/g, '');
-        return { content, raw };
+        const attr = { content, raw };
+        // Try to parse "Name(arg1, arg2)" or "Name" pattern
+        const match = content.match(/^([A-Za-z_][\w.]*)(?:\((.+)\))?$/);
+        if (match) {
+            const name = match[1];
+            const argsStr = match[2];
+            const args = [];
+            if (argsStr) {
+                for (const part of splitBalanced(argsStr)) {
+                    const trimmed = part.trim();
+                    args.push(parseArgValue(trimmed));
+                }
+            }
+            attr.parsed = { name, arguments: args };
+        }
+        return attr;
     });
 }
+/** Split a string by commas, respecting balanced parentheses */
+function splitBalanced(s) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '(')
+            depth++;
+        else if (s[i] === ')')
+            depth--;
+        else if (s[i] === ',' && depth === 0) {
+            parts.push(s.substring(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(s.substring(start));
+    return parts;
+}
+/** Parse a single argument value: numbers, booleans, or strings */
+function parseArgValue(s) {
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    const n = Number(s);
+    if (!isNaN(n) && s.length > 0)
+        return n;
+    // Strip surrounding quotes if present
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
 function isEnumNode(el) {
     return el.type === 'enum' && 'values' in el;
 }

package/dist/reader.d.ts

@@ -4,7 +4,7 @@ export interface M3LFile {
 }
 /**
  * Read M3L files from a path (file or directory).
- * If path is a directory, scans for **\/*.m3l.md files.
+ * If path is a directory, scans for **\/*.m3l.md and **\/*.m3l files.
  * If an m3l.config.yaml exists in the directory, uses its sources patterns.
  */
 export declare function readM3LFiles(inputPath: string): Promise<M3LFile[]>;

package/dist/reader.js

@@ -3,7 +3,7 @@ import { join, resolve as resolvePath } from 'path';
 import fg from 'fast-glob';
 /**
  * Read M3L files from a path (file or directory).
- * If path is a directory, scans for **\/*.m3l.md files.
+ * If path is a directory, scans for **\/*.m3l.md and **\/*.m3l files.
  * If an m3l.config.yaml exists in the directory, uses its sources patterns.
  */
 export async function readM3LFiles(inputPath) {

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.2";
+export declare const PARSER_VERSION = "0.1.3";
 /**
  * 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.2';
+export const PARSER_VERSION = '0.1.3';
 /**
  * Resolve and merge multiple parsed file ASTs into a single M3LAST.
  * Handles: inheritance resolution, duplicate detection, reference validation.
@@ -14,6 +14,7 @@ export function resolve(files, project) {
     const allEnums = [];
     const allInterfaces = [];
     const allViews = [];
+    const allAttrRegistry = [];
     const sources = [];
     for (const file of files) {
         sources.push(file.source);
@@ -21,6 +22,8 @@ export function resolve(files, project) {
         allEnums.push(...file.enums);
         allInterfaces.push(...file.interfaces);
         allViews.push(...file.views);
+        if (file.attributeRegistry)
+            allAttrRegistry.push(...file.attributeRegistry);
     }
     // Build name maps
     const modelMap = new Map();
@@ -54,6 +57,29 @@ export function resolve(files, project) {
     for (const model of [...allModels, ...allViews]) {
         checkDuplicateFields(model, errors);
     }
+    // Tag isRegistered on attributes matching the registry
+    if (allAttrRegistry.length > 0) {
+        const registeredNames = new Set(allAttrRegistry.map(r => r.name));
+        const tagAttrs = (attrs) => {
+            for (const a of attrs) {
+                if (registeredNames.has(a.name)) {
+                    a.isRegistered = true;
+                }
+            }
+        };
+        const tagModel = (m) => {
+            tagAttrs(m.attributes);
+            for (const f of m.fields) {
+                tagAttrs(f.attributes);
+            }
+        };
+        for (const m of allModels)
+            tagModel(m);
+        for (const v of allViews)
+            tagModel(v);
+        for (const i of allInterfaces)
+            tagModel(i);
+    }
     // Detect namespace from first file if available
     const projectInfo = project || {};
     if (!projectInfo.name) {
@@ -70,6 +96,7 @@ export function resolve(files, project) {
         enums: allEnums,
         interfaces: allInterfaces,
         views: allViews,
+        attributeRegistry: allAttrRegistry,
         errors,
         warnings,
     };

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export interface SourceLocation {
     line: number;
     col: number;
 }
-export type TokenType = 'namespace' | 'model' | 'enum' | 'interface' | 'view' | 'section' | 'field' | 'nested_item' | 'blockquote' | 'horizontal_rule' | 'blank' | 'text';
+export type TokenType = 'namespace' | 'model' | 'enum' | 'interface' | 'view' | 'attribute_def' | 'section' | 'field' | 'nested_item' | 'blockquote' | 'horizontal_rule' | 'blank' | 'text';
 export interface Token {
     type: TokenType;
     raw: string;
@@ -17,6 +17,10 @@ export interface FieldAttribute {
     name: string;
     args?: (string | number | boolean)[];
     cascade?: string;
+    /** Whether this is a standard M3L attribute (from the official catalog) */
+    isStandard?: boolean;
+    /** Whether this attribute is registered in an Attribute Registry (::attribute definition) */
+    isRegistered?: boolean;
 }
 /** Structured representation of a backtick-wrapped framework attribute like `[MaxLength(100)]` */
 export interface CustomAttribute {
@@ -24,6 +28,11 @@ export interface CustomAttribute {
     content: string;
     /** Original text including brackets, e.g., "[MaxLength(100)]" */
     raw: string;
+    /** Parsed structure — name and arguments extracted from the content */
+    parsed?: {
+        name: string;
+        arguments: (string | number | boolean)[];
+    };
 }
 export interface EnumValue {
     name: string;
@@ -127,6 +136,23 @@ export interface ParsedFile {
     enums: EnumNode[];
     interfaces: ModelNode[];
     views: ModelNode[];
+    attributeRegistry: AttributeRegistryEntry[];
+}
+export interface AttributeRegistryEntry {
+    /** Attribute name (without @) */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Valid targets: 'field', 'model' */
+    target: ('field' | 'model')[];
+    /** Value type: 'boolean', 'integer', 'string', etc. */
+    type: string;
+    /** Valid range for numeric types */
+    range?: [number, number];
+    /** Whether the attribute is required */
+    required: boolean;
+    /** Default value */
+    defaultValue?: string | number | boolean;
 }
 export interface M3LAST {
     /** Parser package version (semver) */
@@ -139,6 +165,8 @@ export interface M3LAST {
     enums: EnumNode[];
     interfaces: ModelNode[];
     views: ModelNode[];
+    /** Attribute registry entries parsed from ::attribute definitions */
+    attributeRegistry: AttributeRegistryEntry[];
     errors: Diagnostic[];
     warnings: Diagnostic[];
 }

package/package.json

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