@iyulab/m3l 0.1.0

package/dist/reader.d.ts

@@ -0,0 +1,21 @@
+export interface M3LFile {
+    path: string;
+    content: string;
+}
+/**
+ * Read M3L files from a path (file or directory).
+ * If path is a directory, scans for **\/*.m3l.md files.
+ * If an m3l.config.yaml exists in the directory, uses its sources patterns.
+ */
+export declare function readM3LFiles(inputPath: string): Promise<M3LFile[]>;
+/**
+ * Wrap a string content as an M3LFile.
+ */
+export declare function readM3LString(content: string, filename?: string): M3LFile;
+/**
+ * Read project config from m3l.config.yaml if it exists.
+ */
+export declare function readProjectConfig(dirPath: string): Promise<{
+    name?: string;
+    version?: string;
+} | null>;

package/dist/reader.js

@@ -0,0 +1,84 @@
+import { readFileSync, statSync, existsSync } from 'fs';
+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 an m3l.config.yaml exists in the directory, uses its sources patterns.
+ */
+export async function readM3LFiles(inputPath) {
+    const resolved = resolvePath(inputPath);
+    const stat = statSync(resolved);
+    if (stat.isFile()) {
+        return [readSingleFile(resolved)];
+    }
+    if (stat.isDirectory()) {
+        // Check for m3l.config.yaml
+        const configPath = join(resolved, 'm3l.config.yaml');
+        if (existsSync(configPath)) {
+            return readFromConfig(configPath, resolved);
+        }
+        // Default: scan for all .m3l.md files
+        return scanDirectory(resolved);
+    }
+    throw new Error(`Path is neither a file nor a directory: ${resolved}`);
+}
+/**
+ * Wrap a string content as an M3LFile.
+ */
+export function readM3LString(content, filename = 'inline.m3l.md') {
+    return { path: filename, content };
+}
+function readSingleFile(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    return { path: filePath, content };
+}
+async function scanDirectory(dirPath) {
+    const pattern = '**/*.{m3l.md,m3l}';
+    const files = await fg(pattern, {
+        cwd: dirPath,
+        absolute: true,
+        onlyFiles: true,
+    });
+    return files.sort().map(f => readSingleFile(f));
+}
+async function readFromConfig(configPath, baseDir) {
+    const yamlContent = readFileSync(configPath, 'utf-8');
+    // Dynamic import yaml to parse config
+    const { parse: parseYaml } = await import('yaml');
+    const config = parseYaml(yamlContent);
+    if (!config.sources || config.sources.length === 0) {
+        return scanDirectory(baseDir);
+    }
+    const allFiles = [];
+    const seen = new Set();
+    for (const pattern of config.sources) {
+        const files = await fg(pattern, {
+            cwd: baseDir,
+            absolute: true,
+            onlyFiles: true,
+        });
+        for (const f of files.sort()) {
+            if (!seen.has(f)) {
+                seen.add(f);
+                allFiles.push(readSingleFile(f));
+            }
+        }
+    }
+    return allFiles;
+}
+/**
+ * Read project config from m3l.config.yaml if it exists.
+ */
+export async function readProjectConfig(dirPath) {
+    const configPath = join(resolvePath(dirPath), 'm3l.config.yaml');
+    if (!existsSync(configPath))
+        return null;
+    const yamlContent = readFileSync(configPath, 'utf-8');
+    const { parse: parseYaml } = await import('yaml');
+    const config = parseYaml(yamlContent);
+    return {
+        name: config?.name,
+        version: config?.version,
+    };
+}

package/dist/resolver.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedFile, M3LAST, ProjectInfo } from './types.js';
+/**
+ * Resolve and merge multiple parsed file ASTs into a single M3LAST.
+ * Handles: inheritance resolution, duplicate detection, reference validation.
+ */
+export declare function resolve(files: ParsedFile[], project?: ProjectInfo): M3LAST;

package/dist/resolver.js

@@ -0,0 +1,148 @@
+/**
+ * Resolve and merge multiple parsed file ASTs into a single M3LAST.
+ * Handles: inheritance resolution, duplicate detection, reference validation.
+ */
+export function resolve(files, project) {
+    const errors = [];
+    const warnings = [];
+    // Collect all elements from all files
+    const allModels = [];
+    const allEnums = [];
+    const allInterfaces = [];
+    const allViews = [];
+    const sources = [];
+    for (const file of files) {
+        sources.push(file.source);
+        allModels.push(...file.models);
+        allEnums.push(...file.enums);
+        allInterfaces.push(...file.interfaces);
+        allViews.push(...file.views);
+    }
+    // Build name maps
+    const modelMap = new Map();
+    const enumMap = new Map();
+    const interfaceMap = new Map();
+    const allNamedMap = new Map();
+    // Check for duplicate model names
+    for (const model of allModels) {
+        checkDuplicate(model.name, 'model', model, modelMap, allNamedMap, errors);
+        modelMap.set(model.name, model);
+        allNamedMap.set(model.name, { type: 'model', loc: { file: model.source, line: model.line } });
+    }
+    for (const en of allEnums) {
+        checkDuplicate(en.name, 'enum', en, enumMap, allNamedMap, errors);
+        enumMap.set(en.name, en);
+        allNamedMap.set(en.name, { type: 'enum', loc: { file: en.source, line: en.line } });
+    }
+    for (const iface of allInterfaces) {
+        checkDuplicate(iface.name, 'interface', iface, interfaceMap, allNamedMap, errors);
+        interfaceMap.set(iface.name, iface);
+        allNamedMap.set(iface.name, { type: 'interface', loc: { file: iface.source, line: iface.line } });
+    }
+    for (const view of allViews) {
+        allNamedMap.set(view.name, { type: 'view', loc: { file: view.source, line: view.line } });
+    }
+    // Resolve inheritance
+    for (const model of allModels) {
+        resolveInheritance(model, modelMap, interfaceMap, allNamedMap, errors);
+    }
+    // Check duplicate field names within each model
+    for (const model of [...allModels, ...allViews]) {
+        checkDuplicateFields(model, errors);
+    }
+    // Detect namespace from first file if available
+    const projectInfo = project || {};
+    if (!projectInfo.name) {
+        const ns = files.find(f => f.namespace)?.namespace;
+        if (ns)
+            projectInfo.name = ns;
+    }
+    return {
+        project: projectInfo,
+        sources,
+        models: allModels,
+        enums: allEnums,
+        interfaces: allInterfaces,
+        views: allViews,
+        errors,
+        warnings,
+    };
+}
+function checkDuplicate(name, kind, item, map, allMap, errors) {
+    const existing = allMap.get(name);
+    if (existing) {
+        errors.push({
+            code: 'E005',
+            severity: 'error',
+            file: item.source,
+            line: item.line,
+            col: 1,
+            message: `Duplicate ${kind} name "${name}" (first defined in ${existing.loc.file}:${existing.loc.line})`,
+        });
+    }
+}
+function resolveInheritance(model, modelMap, interfaceMap, allNamedMap, errors) {
+    if (model.inherits.length === 0)
+        return;
+    const inheritedFields = [];
+    const resolved = new Set();
+    const visiting = new Set();
+    function collectFields(name, fromModel) {
+        if (resolved.has(name) || visiting.has(name))
+            return;
+        visiting.add(name);
+        const parent = modelMap.get(name) || interfaceMap.get(name);
+        if (!parent) {
+            if (!allNamedMap.has(name)) {
+                errors.push({
+                    code: 'E007',
+                    severity: 'error',
+                    file: fromModel.source,
+                    line: fromModel.line,
+                    col: 1,
+                    message: `Unresolved inheritance reference "${name}" in model "${fromModel.name}"`,
+                });
+            }
+            visiting.delete(name);
+            return;
+        }
+        // Recursively resolve parent's parents first
+        for (const grandparent of parent.inherits) {
+            collectFields(grandparent, fromModel);
+        }
+        // Add parent's own fields
+        for (const field of parent.fields) {
+            if (!inheritedFields.some(f => f.name === field.name)) {
+                inheritedFields.push({ ...field });
+            }
+        }
+        visiting.delete(name);
+        resolved.add(name);
+    }
+    for (const parentName of model.inherits) {
+        collectFields(parentName, model);
+    }
+    // Prepend inherited fields before model's own fields
+    if (inheritedFields.length > 0) {
+        model.fields = [...inheritedFields, ...model.fields];
+    }
+}
+function checkDuplicateFields(model, errors) {
+    const seen = new Map();
+    for (const field of model.fields) {
+        const existing = seen.get(field.name);
+        if (existing) {
+            errors.push({
+                code: 'E005',
+                severity: 'error',
+                file: field.loc.file,
+                line: field.loc.line,
+                col: 1,
+                message: `Duplicate field name "${field.name}" in ${model.type} "${model.name}" (first at line ${existing.loc.line})`,
+            });
+        }
+        else {
+            seen.set(field.name, field);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+/** Source location for error reporting */
+export interface SourceLocation {
+    file: string;
+    line: number;
+    col: number;
+}
+export type TokenType = 'namespace' | 'model' | 'enum' | 'interface' | 'view' | 'section' | 'field' | 'nested_item' | 'blockquote' | 'horizontal_rule' | 'blank' | 'text';
+export interface Token {
+    type: TokenType;
+    raw: string;
+    line: number;
+    indent: number;
+    data?: Record<string, unknown>;
+}
+export type FieldKind = 'stored' | 'computed' | 'lookup' | 'rollup';
+export interface FieldAttribute {
+    name: string;
+    args?: unknown[];
+}
+export interface EnumValue {
+    name: string;
+    description?: string;
+    type?: string;
+    value?: unknown;
+}
+export interface FieldNode {
+    name: string;
+    label?: string;
+    type?: string;
+    params?: (string | number)[];
+    nullable: boolean;
+    array: boolean;
+    kind: FieldKind;
+    default_value?: string;
+    description?: string;
+    attributes: FieldAttribute[];
+    framework_attrs?: string[];
+    lookup?: {
+        path: string;
+    };
+    rollup?: {
+        target: string;
+        fk: string;
+        aggregate: string;
+        field?: string;
+        where?: string;
+    };
+    computed?: {
+        expression: string;
+    };
+    enum_values?: EnumValue[];
+    fields?: FieldNode[];
+    loc: SourceLocation;
+}
+export interface ModelNode {
+    name: string;
+    label?: string;
+    type: 'model' | 'enum' | 'interface' | 'view';
+    source: string;
+    line: number;
+    inherits: string[];
+    description?: string;
+    fields: FieldNode[];
+    sections: {
+        indexes: unknown[];
+        relations: unknown[];
+        behaviors: unknown[];
+        metadata: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    materialized?: boolean;
+    source_def?: ViewSourceDef;
+    refresh?: {
+        strategy: string;
+        interval?: string;
+    };
+    loc: SourceLocation;
+}
+export interface ViewSourceDef {
+    from: string;
+    joins?: {
+        model: string;
+        on: string;
+    }[];
+    where?: string;
+    order_by?: string;
+    group_by?: string[];
+}
+export interface EnumNode {
+    name: string;
+    label?: string;
+    type: 'enum';
+    source: string;
+    line: number;
+    description?: string;
+    values: EnumValue[];
+    loc: SourceLocation;
+}
+export interface ProjectInfo {
+    name?: string;
+    version?: string;
+}
+export interface Diagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    file: string;
+    line: number;
+    col: number;
+    message: string;
+}
+export interface ParsedFile {
+    source: string;
+    namespace?: string;
+    models: ModelNode[];
+    enums: EnumNode[];
+    interfaces: ModelNode[];
+    views: ModelNode[];
+}
+export interface M3LAST {
+    project: ProjectInfo;
+    sources: string[];
+    models: ModelNode[];
+    enums: EnumNode[];
+    interfaces: ModelNode[];
+    views: ModelNode[];
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+}
+export interface ValidateOptions {
+    strict?: boolean;
+}
+export interface ValidateResult {
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,5 @@
+import type { M3LAST, ValidateOptions, ValidateResult } from './types.js';
+/**
+ * Validate a resolved M3L AST for semantic errors and style warnings.
+ */
+export declare function validate(ast: M3LAST, options?: ValidateOptions): ValidateResult;

package/dist/validator.js

@@ -0,0 +1,196 @@
+/**
+ * Validate a resolved M3L AST for semantic errors and style warnings.
+ */
+export function validate(ast, options = {}) {
+    const errors = [...ast.errors];
+    const warnings = [...ast.warnings];
+    const allModels = [...ast.models, ...ast.views];
+    const modelMap = new Map();
+    for (const m of allModels) {
+        modelMap.set(m.name, m);
+    }
+    // E001: @rollup FK missing @reference
+    for (const model of allModels) {
+        for (const field of model.fields) {
+            if (field.kind === 'rollup' && field.rollup) {
+                validateRollupReference(field, model, modelMap, errors);
+            }
+        }
+    }
+    // E002: @lookup path FK missing @reference
+    for (const model of allModels) {
+        for (const field of model.fields) {
+            if (field.kind === 'lookup' && field.lookup) {
+                validateLookupReference(field, model, modelMap, errors);
+            }
+        }
+    }
+    // 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',
+                    severity: 'error',
+                    file: view.source,
+                    line: view.line,
+                    col: 1,
+                    message: `View "${view.name}" references model "${view.source_def.from}" which is not defined`,
+                });
+            }
+        }
+    }
+    // E005: 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',
+                    severity: 'error',
+                    file: field.loc.file,
+                    line: field.loc.line,
+                    col: 1,
+                    message: `Duplicate field name "${field.name}" in ${model.type} "${model.name}"`,
+                });
+            }
+            seen.add(field.name);
+        }
+    }
+    // Strict mode warnings
+    if (options.strict) {
+        for (const model of allModels) {
+            for (const field of model.fields) {
+                // 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
+                if (field.kind === 'lookup' && field.lookup) {
+                    const hops = field.lookup.path.split('.').length;
+                    if (hops > 3) {
+                        warnings.push({
+                            code: 'W004',
+                            severity: 'warning',
+                            file: field.loc.file,
+                            line: field.loc.line,
+                            col: 1,
+                            message: `Lookup chain "${field.lookup.path}" exceeds 3 hops (${hops} hops)`,
+                        });
+                    }
+                }
+            }
+            // W002: Object nesting > 3 levels
+            checkNestingDepth(model.fields, 1, model, warnings);
+        }
+        // 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) {
+                    // The lexer/parser would have marked whether values: key was used
+                    // For now, we check based on presence — if enum_values exist without
+                    // the values: wrapper, the parser still collects them.
+                    // This warning is informational for style.
+                    // We'll rely on a flag set during parsing in the future.
+                }
+            }
+        }
+    }
+    return { errors, warnings };
+}
+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)
+        return;
+    }
+    // Check that the FK field in the target model has @reference or @fk
+    const fkField = targetModel.fields.find(f => f.name === rollup.fk);
+    if (!fkField) {
+        // FK field doesn't exist in target
+        return;
+    }
+    const hasReference = fkField.attributes.some(a => a.name === 'reference' || a.name === 'fk');
+    if (!hasReference) {
+        errors.push({
+            code: 'E001',
+            severity: 'error',
+            file: field.loc.file,
+            line: field.loc.line,
+            col: 1,
+            message: `@rollup on "${field.name}" targets "${rollup.target}.${rollup.fk}" which has no @reference or @fk attribute`,
+        });
+    }
+}
+function validateLookupReference(field, model, modelMap, errors) {
+    const lookupPath = field.lookup.path;
+    const segments = lookupPath.split('.');
+    if (segments.length < 2)
+        return;
+    const fkFieldName = segments[0];
+    // Find the FK field in the current model
+    const fkField = model.fields.find(f => f.name === fkFieldName);
+    if (!fkField)
+        return; // Missing field — different issue
+    const hasReference = fkField.attributes.some(a => a.name === 'reference' || a.name === 'fk');
+    if (!hasReference) {
+        errors.push({
+            code: 'E002',
+            severity: 'error',
+            file: field.loc.file,
+            line: field.loc.line,
+            col: 1,
+            message: `@lookup on "${field.name}" references FK "${fkFieldName}" which has no @reference or @fk attribute`,
+        });
+    }
+}
+function checkFieldLineLength(field, model, warnings) {
+    // Reconstruct approximate line length
+    let len = 2 + field.name.length; // "- name"
+    if (field.label)
+        len += field.label.length + 2; // "(label)"
+    if (field.type) {
+        len += 2 + field.type.length; // ": type"
+        if (field.params)
+            len += field.params.join(',').length + 2;
+    }
+    if (field.nullable)
+        len += 1;
+    if (field.default_value)
+        len += 3 + field.default_value.length;
+    for (const attr of field.attributes) {
+        len += 2 + attr.name.length; // " @name"
+        if (attr.args)
+            len += attr.args.join(',').length + 2;
+    }
+    if (field.description)
+        len += 3 + field.description.length;
+    if (len > 80) {
+        warnings.push({
+            code: 'W001',
+            severity: 'warning',
+            file: field.loc.file,
+            line: field.loc.line,
+            col: 1,
+            message: `Field "${field.name}" line length (~${len} chars) exceeds 80 character guideline`,
+        });
+    }
+}
+function checkNestingDepth(fields, depth, model, warnings) {
+    for (const field of fields) {
+        if (field.fields && field.fields.length > 0) {
+            if (depth >= 3) {
+                warnings.push({
+                    code: 'W002',
+                    severity: 'warning',
+                    file: field.loc.file,
+                    line: field.loc.line,
+                    col: 1,
+                    message: `Object nesting depth exceeds 3 levels at field "${field.name}" in "${model.name}"`,
+                });
+            }
+            checkNestingDepth(field.fields, depth + 1, model, warnings);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@iyulab/m3l",
+  "version": "0.1.0",
+  "description": "M3L parser and CLI tool — parse .m3l.md files into JSON AST",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "m3l": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "yaml": "^2.7.0",
+    "fast-glob": "^3.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}