@iyulab/m3l 0.1.3 → 0.1.4

package/README.md

@@ -1,6 +1,10 @@
 # @iyulab/m3l
 
-M3L (Meta Model Markup Language) parser and CLI — parse `.m3l.md` files into a structured JSON AST.
+[![npm](https://img.shields.io/npm/v/@iyulab/m3l)](https://www.npmjs.com/package/@iyulab/m3l)
+[![TypeScript CI](https://github.com/iyulab/m3l/actions/workflows/parser-publish.yml/badge.svg)](https://github.com/iyulab/m3l/actions/workflows/parser-publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+
+M3L (Meta Model Markup Language) parser and CLI — parse `.m3l.md` / `.m3l` files into a structured JSON AST.
 
 M3L is a Markdown-based data modeling language. You write data models in readable Markdown, and this parser converts them into a machine-processable AST with full validation.
 
@@ -107,6 +111,7 @@ npx m3l validate ./models --strict --format json
 | `## Name ::enum` | Enum definition |
 | `## Name ::interface` | Interface definition |
 | `## Name ::view` | Derived view |
+| `## @name ::attribute` | Attribute registry entry |
 | `- field: type` | Field definition |
 | `- field: type?` | Nullable field |
 | `- field: type[]` | Array field |
@@ -133,6 +138,7 @@ interface M3LAST {
   enums: EnumNode[];
   interfaces: ModelNode[];
   views: ModelNode[];
+  attributeRegistry: AttributeRegistryEntry[];
   errors: Diagnostic[];
   warnings: Diagnostic[];
 }
@@ -146,10 +152,10 @@ interface FieldNode {
   label?: string;
   type?: string;
   params?: (string | number)[];
-  generic_params?: string[];     // map<K,V> → ["K", "V"]
+  generic_params?: string[];     // map<K,V> -> ["K", "V"]
   nullable: boolean;
   array: boolean;
-  arrayItemNullable: boolean;    // string?[] → true
+  arrayItemNullable: boolean;    // string?[] -> true
   kind: 'stored' | 'computed' | 'lookup' | 'rollup';
   default_value?: string;
   description?: string;
@@ -163,17 +169,61 @@ interface FieldNode {
   loc: SourceLocation;
 }
 
-interface ModelNode {
+interface FieldAttribute {
+  name: string;
+  args?: (string | number | boolean)[];
+  cascade?: string;
+  isStandard?: boolean;          // true for M3L standard attributes
+  isRegistered?: boolean;        // true for attributes in the registry
+}
+
+interface CustomAttribute {
+  content: string;               // e.g. "MaxLength(100)"
+  raw: string;                   // e.g. "[MaxLength(100)]"
+  parsed?: {                     // structured parse result
+    name: string;
+    arguments: (string | number | boolean)[];
+  };
+}
+
+interface AttributeRegistryEntry {
   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 };
-  // ...
+  description?: string;
+  target: ('field' | 'model')[];
+  type: string;
+  range?: [number, number];
+  required: boolean;
+  defaultValue?: string | number | boolean;
 }
 ```
 
+## Attribute Registry
+
+Define custom attributes with validation metadata using `::attribute`:
+
+```markdown
+## @pii ::attribute
+> Personal identifiable information marker
+- target: [field]
+- type: boolean
+- default: false
+
+## @audit_level ::attribute
+> Audit compliance level
+- target: [field, model]
+- type: integer
+- range: [1, 5]
+- default: 1
+```
+
+Attributes are classified into 3 tiers:
+
+| Tier | `isStandard` | `isRegistered` | Example |
+|------|-------------|----------------|---------|
+| Standard | `true` | — | `@primary`, `@unique`, `@reference` |
+| Registered | — | `true` | `@pii`, `@audit_level` (defined via `::attribute`) |
+| Unregistered | — | — | `@some_unknown_attr` |
+
 ## Validation
 
 The validator checks for semantic errors and style warnings:
@@ -184,7 +234,9 @@ The validator checks for semantic errors and style warnings:
 | M3L-E001 | Rollup FK field missing `@reference` |
 | M3L-E002 | Lookup FK field missing `@reference` |
 | M3L-E004 | View references non-existent model |
+| M3L-E005 | Duplicate model/enum name |
 | M3L-E006 | Duplicate field name within model |
+| M3L-E007 | Unresolved parent in inheritance |
 
 **Warnings (--strict):**
 | Code | Description |
@@ -221,6 +273,10 @@ Parse an M3L content string into an AST.
 
 Parse and validate M3L files. Options: `{ strict?: boolean }`.
 
+### `STANDARD_ATTRIBUTES: Set<string>`
+
+The set of 27 M3L standard attribute names (e.g. `primary`, `unique`, `reference`, `computed`, ...).
+
 ### Lower-level API
 
 ```typescript

package/dist/lexer.js

@@ -3,7 +3,7 @@ const RE_H1 = /^# (.+)$/;
 const RE_H2 = /^## (.+)$/;
 const RE_H3 = /^### (.+)$/;
 const RE_HR = /^-{3,}$/;
-const RE_BLOCKQUOTE = /^> (.+)$/;
+const RE_BLOCKQUOTE = /^\s*> (.+)$/;
 const RE_LIST_ITEM = /^(\s*)- (.+)$/;
 const RE_BLANK = /^\s*$/;
 // H2 sub-patterns
@@ -143,6 +143,14 @@ function tokenizeH2(content, raw, line) {
         const rest = typeMatch[3]?.trim() || '';
         const { name, label } = parseNameLabel(namepart);
         const data = { name, label };
+        // Parse inheritance: ::enum : Base1, Base2
+        const inheritMatch = rest.match(/^:\s*(.+?)(?:\s+@|\s*"|\s*$)/);
+        if (inheritMatch) {
+            data.inherits = inheritMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+        }
+        else {
+            data.inherits = [];
+        }
         if (typeIndicator === 'view') {
             data.materialized = rest.includes('@materialized');
         }

package/dist/parser.js

@@ -139,6 +139,7 @@ function handleEnumStart(token, state) {
         type: 'enum',
         source: state.file,
         line: token.line,
+        inherits: data.inherits || [],
         description: data.description,
         values: [],
         loc: { file: state.file, line: token.line, col: 1 },
@@ -265,11 +266,12 @@ function handleDirective(data, model, token, state) {
     if (!attrs || attrs.length === 0)
         return;
     const attr = attrs[0];
-    if (attr.name === 'index') {
+    if (attr.name === 'index' || attr.name === 'unique') {
         model.sections.indexes.push({
             type: 'directive',
             raw: data.raw_content,
             args: attr.args,
+            unique: attr.name === 'unique',
             loc: { file: state.file, line: token.line, col: 1 },
         });
     }
@@ -358,6 +360,7 @@ function handleSectionItem(data, model, token, state) {
             raw: token.raw.trim().replace(/^- /, ''),
             loc,
         });
+        state.lastField = { name: token.raw.trim().replace(/^- /, '') };
         return;
     }
     // Metadata section
@@ -420,6 +423,16 @@ function handleNestedItem(token, state) {
         }
         return;
     }
+    // Nested items under relation in Relations section
+    if (state.currentSection === 'Relations' && state.lastField) {
+        const lastRelation = model.sections.relations[model.sections.relations.length - 1];
+        if (lastRelation && typeof lastRelation === 'object') {
+            if (key) {
+                lastRelation[key] = parseNestedValue(value || '');
+            }
+        }
+        return;
+    }
     // Nested items under a field
     if (state.lastField) {
         const field = state.lastField;
@@ -500,6 +513,16 @@ function handleBlockquote(token, state) {
     if (!state.currentElement)
         return;
     const text = token.data.text;
+    // Field-level blockquote: apply to lastField if available (not for enums)
+    if (state.lastField && !isEnumNode(state.currentElement)) {
+        if (state.lastField.description) {
+            state.lastField.description += '\n' + text;
+        }
+        else {
+            state.lastField.description = text;
+        }
+        return;
+    }
     if (state.currentElement.description) {
         state.currentElement.description += '\n' + text;
     }
@@ -667,6 +690,10 @@ function buildFieldNode(data, token, state) {
             field.computed.platform = parts.platform;
         }
     }
+    // Inline comment as field description
+    if (!field.description && data.comment) {
+        field.description = data.comment;
+    }
     return field;
 }
 /**

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.3";
+export declare const PARSER_VERSION = "0.1.4";
 /**
  * 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.3';
+export const PARSER_VERSION = '0.1.4';
 /**
  * Resolve and merge multiple parsed file ASTs into a single M3LAST.
  * Handles: inheritance resolution, duplicate detection, reference validation.

package/dist/types.d.ts

@@ -113,6 +113,7 @@ export interface EnumNode {
     type: 'enum';
     source: string;
     line: number;
+    inherits: string[];
     description?: string;
     values: EnumValue[];
     loc: SourceLocation;

package/package.json

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