@iyulab/m3l 0.1.4 → 0.5.0

package/dist/reader.d.ts

@@ -1,21 +0,0 @@
-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 and **\/*.m3l 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

@@ -1,84 +0,0 @@
-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 and **\/*.m3l 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

@@ -1,10 +0,0 @@
-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.4";
-/**
- * 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

@@ -1,192 +0,0 @@
-/** 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.4';
-/**
- * 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 allAttrRegistry = [];
-    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);
-        if (file.attributeRegistry)
-            allAttrRegistry.push(...file.attributeRegistry);
-    }
-    // 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);
-    }
-    // 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) {
-        const ns = files.find(f => f.namespace)?.namespace;
-        if (ns)
-            projectInfo.name = ns;
-    }
-    return {
-        parserVersion: PARSER_VERSION,
-        astVersion: AST_VERSION,
-        project: projectInfo,
-        sources,
-        models: allModels,
-        enums: allEnums,
-        interfaces: allInterfaces,
-        views: allViews,
-        attributeRegistry: allAttrRegistry,
-        errors,
-        warnings,
-    };
-}
-function checkDuplicate(name, kind, item, map, allMap, errors) {
-    const existing = allMap.get(name);
-    if (existing) {
-        errors.push({
-            code: 'M3L-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: 'M3L-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);
-    }
-    // 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 (filteredInherited.length > 0) {
-        model.fields = [...filteredInherited, ...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: 'M3L-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

@@ -1,180 +0,0 @@
-/** Source location for error reporting */
-export interface SourceLocation {
-    file: string;
-    line: number;
-    col: number;
-}
-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;
-    line: number;
-    indent: number;
-    data?: Record<string, unknown>;
-}
-export type FieldKind = 'stored' | 'computed' | 'lookup' | 'rollup';
-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 {
-    /** Content inside brackets, e.g., "MaxLength(100)" for `[MaxLength(100)]` */
-    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;
-    description?: string;
-    type?: string;
-    value?: unknown;
-}
-export interface FieldNode {
-    name: string;
-    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?: CustomAttribute[];
-    lookup?: {
-        path: string;
-    };
-    rollup?: {
-        target: string;
-        fk: string;
-        aggregate: string;
-        field?: string;
-        where?: string;
-    };
-    computed?: {
-        expression: string;
-        platform?: 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;
-    attributes: FieldAttribute[];
-    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;
-    inherits: string[];
-    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[];
-    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) */
-    parserVersion: string;
-    /** AST schema version — incremented on breaking AST structure changes */
-    astVersion: string;
-    project: ProjectInfo;
-    sources: string[];
-    models: ModelNode[];
-    enums: EnumNode[];
-    interfaces: ModelNode[];
-    views: ModelNode[];
-    /** Attribute registry entries parsed from ::attribute definitions */
-    attributeRegistry: AttributeRegistryEntry[];
-    errors: Diagnostic[];
-    warnings: Diagnostic[];
-}
-export interface ValidateOptions {
-    strict?: boolean;
-}
-export interface ValidateResult {
-    errors: Diagnostic[];
-    warnings: Diagnostic[];
-}

package/dist/types.js

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

package/dist/validator.d.ts

@@ -1,5 +0,0 @@
-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

@@ -1,196 +0,0 @@
-/**
- * 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);
-    }
-    // M3L-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);
-            }
-        }
-    }
-    // M3L-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);
-            }
-        }
-    }
-    // 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: 'M3L-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`,
-                });
-            }
-        }
-    }
-    // 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: 'M3L-E006',
-                    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) {
-                // M3L-W001: Field line length > 80 chars
-                // We check the source loc raw length — approximate using field attributes count
-                checkFieldLineLength(field, model, warnings);
-                // 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: 'M3L-W004',
-                            severity: 'warning',
-                            file: field.loc.file,
-                            line: field.loc.line,
-                            col: 1,
-                            message: `Lookup chain "${field.lookup.path}" exceeds 3 hops (${hops} hops)`,
-                        });
-                    }
-                }
-            }
-            // M3L-W002: Object nesting > 3 levels
-            checkNestingDepth(model.fields, 1, model, warnings);
-        }
-        // 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) {
-                    // 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 M3L-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: 'M3L-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: 'M3L-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: 'M3L-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: 'M3L-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);
-        }
-    }
-}