@iyulab/m3l 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# @iyulab/m3l
+
+M3L (Meta Model Markup Language) parser and CLI — parse `.m3l.md` 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.
+
+## Install
+
+```bash
+npm install @iyulab/m3l
+```
+
+## Quick Start
+
+### As a Library
+
+```typescript
+import { parse, parseString, validateFiles } from '@iyulab/m3l';
+
+// Parse a file or directory
+const ast = await parse('./models');
+
+// Parse a string
+const ast2 = parseString(`
+## User
+- name: string(100) @not_null
+- email: string(320)? @unique
+
+## UserRole ::enum
+- admin: "Administrator"
+- user: "Regular User"
+`);
+
+console.log(ast2.models);  // [{ name: 'User', fields: [...], ... }]
+console.log(ast2.enums);   // [{ name: 'UserRole', values: [...], ... }]
+
+// Validate with diagnostics
+const { ast: validated, errors, warnings } = await validateFiles('./models');
+```
+
+### As a CLI
+
+```bash
+# Parse and output JSON AST
+npx m3l parse ./models
+
+# Parse a single file
+npx m3l parse ./models/user.m3l.md -o ast.json
+
+# Validate
+npx m3l validate ./models
+
+# Validate with strict style checks and JSON output
+npx m3l validate ./models --strict --format json
+```
+
+## M3L Syntax
+
+```markdown
+# Library System
+
+## Author
+- name(Author Name): string(100) @not_null @idx
+- bio(Biography): text?
+- birth_date: date?
+
+# Rollup
+- book_count: integer @rollup(BookAuthor.author_id, count)
+
+> Stores information about book authors.
+
+## BookStatus ::enum "Status of a book"
+- available: "Available"
+- borrowed: "Borrowed"
+- reserved: "Reserved"
+
+## Book : BaseModel
+- title: string(200) @not_null @idx
+- isbn: string(20) @unique
+- status: enum = "available"
+  - available: "Available"
+  - borrowed: "Borrowed"
+- publisher_id: identifier @fk(Publisher.id)
+
+# Lookup
+- publisher_name: string @lookup(publisher_id.name)
+
+# Computed
+- is_available: boolean @computed("status = 'available' AND quantity > 0")
+
+## OverdueLoans ::view @materialized
+> Currently overdue book loans.
+### Source
+- from: Loan
+- where: "due_date < now() AND status = 'ongoing'"
+- order_by: due_date asc
+- borrower_name: string @lookup(member_id.name)
+```
+
+**Key syntax elements:**
+
+| Syntax | Meaning |
+|--------|---------|
+| `# Title` | Document title or namespace (`# Namespace: domain.example`) |
+| `## Name` | Model definition |
+| `## Name : Parent` | Model with inheritance |
+| `## Name ::enum` | Enum definition |
+| `## Name ::interface` | Interface definition |
+| `## Name ::view` | Derived view |
+| `- field: type` | Field definition |
+| `- field: type?` | Nullable field |
+| `- field: type[]` | Array field |
+| `- field: type = val` | Field with default value |
+| `@attr` / `@attr(args)` | Attribute (constraint, index, etc.) |
+| `# Lookup` / `# Rollup` / `# Computed` | Kind section for derived fields |
+| `### Section` | Named section (Indexes, Relations, Metadata, etc.) |
+| `> text` | Model/element description |
+| `"text"` | Inline description on field |
+
+## AST Output
+
+The parser produces an `M3LAST` object:
+
+```typescript
+interface M3LAST {
+  project: { name?: string; version?: string };
+  sources: string[];         // parsed file paths
+  models: ModelNode[];       // models and interfaces
+  enums: EnumNode[];         // enum definitions
+  interfaces: ModelNode[];   // interface definitions
+  views: ModelNode[];        // derived views
+  errors: Diagnostic[];      // parse/resolve errors
+  warnings: Diagnostic[];    // validation warnings
+}
+```
+
+Each `ModelNode` contains fields, sections (indexes, relations, metadata), inheritance info, and source locations for error reporting.
+
+## Validation
+
+The validator checks for semantic errors and style warnings:
+
+**Errors:**
+| Code | Description |
+|------|-------------|
+| E001 | Rollup FK field missing `@reference` |
+| E002 | Lookup FK field missing `@reference` |
+| E004 | View references non-existent model |
+| E005 | Duplicate model/enum name |
+| E006 | Duplicate field name within model |
+| E007 | Unresolved parent in inheritance |
+
+**Warnings (--strict):**
+| Code | Description |
+|------|-------------|
+| W001 | Model has no fields |
+| W002 | Model has no description |
+| W003 | Field missing label |
+| W004 | Enum has no values |
+
+## Multi-file Projects
+
+Place `.m3l.md` or `.m3l` files in a directory and parse the directory path. The resolver automatically merges all files, resolves inheritance, and detects cross-file references.
+
+Optionally, create an `m3l.config.yaml`:
+
+```yaml
+name: my-project
+version: 1.0.0
+sources:
+  - "models/**/*.m3l.md"
+  - "shared/*.m3l"
+```
+
+## API Reference
+
+### `parse(inputPath: string): Promise<M3LAST>`
+
+Parse M3L files from a file or directory into a merged AST.
+
+### `parseString(content: string, filename?: string): M3LAST`
+
+Parse an M3L content string into an AST.
+
+### `validateFiles(inputPath: string, options?): Promise<{ ast, errors, warnings }>`
+
+Parse and validate M3L files. Options: `{ strict?: boolean }`.
+
+### Lower-level API
+
+```typescript
+import { lex, parseTokens, resolve, validate } from '@iyulab/m3l';
+
+const tokens = lex(content, 'file.m3l.md');
+const parsed = parseTokens(tokens, 'file.m3l.md');
+const ast = resolve([parsed]);
+const diagnostics = validate(ast, { strict: true });
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import type { ValidateOptions } from './types.js';
+/**
+ * Run parse command — also used for testing.
+ */
+export declare function runParse(inputPath: string, outputFile?: string): Promise<string>;
+/**
+ * Run validate command — also used for testing.
+ */
+export declare function runValidate(inputPath: string, options?: ValidateOptions, format?: string): Promise<string>;
+/**
+ * Run CLI with args — for testing.
+ */
+export declare function runCLI(args: string[]): Promise<string>;

package/dist/cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { writeFileSync } from 'fs';
+import { resolve as resolvePath } from 'path';
+import { readM3LFiles, readProjectConfig } from './reader.js';
+import { parseString as parseFileContent } from './parser.js';
+import { resolve } from './resolver.js';
+import { validate } from './validator.js';
+const program = new Command()
+    .name('m3l')
+    .description('M3L parser and validator — parse .m3l.md files into JSON AST')
+    .version('0.1.0');
+program
+    .command('parse [path]')
+    .description('Parse M3L files and output JSON AST')
+    .option('-o, --output <file>', 'Write output to file instead of stdout')
+    .action(async (inputPath, options) => {
+    try {
+        const output = await runParse(inputPath || '.', options?.output);
+        if (!options?.output) {
+            process.stdout.write(output + '\n');
+        }
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(1);
+    }
+});
+program
+    .command('validate [path]')
+    .description('Validate M3L files')
+    .option('--strict', 'Enable strict style guidelines')
+    .option('--format <format>', 'Output format: human (default) or json', 'human')
+    .action(async (inputPath, options) => {
+    try {
+        const output = await runValidate(inputPath || '.', { strict: options?.strict }, options?.format || 'human');
+        process.stdout.write(output + '\n');
+        // Exit with error code if there are errors
+        if (output.includes('"errors":') || output.match(/\d+ error/)) {
+            const errorCount = extractErrorCount(output, options?.format || 'human');
+            if (errorCount > 0)
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(1);
+    }
+});
+// Entry point for direct execution
+const args = process.argv.slice(2);
+if (args.length > 0) {
+    program.parse();
+}
+/**
+ * Run parse command — also used for testing.
+ */
+export async function runParse(inputPath, outputFile) {
+    const ast = await buildAST(inputPath);
+    const json = JSON.stringify(ast, null, 2);
+    if (outputFile) {
+        writeFileSync(resolvePath(outputFile), json, 'utf-8');
+        return `Written to ${outputFile}`;
+    }
+    return json;
+}
+/**
+ * Run validate command — also used for testing.
+ */
+export async function runValidate(inputPath, options = {}, format = 'human') {
+    const ast = await buildAST(inputPath);
+    const result = validate(ast, options);
+    if (format === 'json') {
+        return JSON.stringify({
+            diagnostics: [...result.errors, ...result.warnings],
+            summary: {
+                errors: result.errors.length,
+                warnings: result.warnings.length,
+                files: ast.sources.length,
+            },
+        }, null, 2);
+    }
+    // Human-readable format
+    return formatHumanDiagnostics(result.errors, result.warnings, ast.sources.length);
+}
+/**
+ * Run CLI with args — for testing.
+ */
+export async function runCLI(args) {
+    const cmd = args[0];
+    const rest = args.slice(1);
+    if (cmd === 'parse') {
+        const inputPath = rest.find(a => !a.startsWith('-')) || '.';
+        const outputIdx = rest.indexOf('-o');
+        const outputFile = outputIdx >= 0 ? rest[outputIdx + 1] : undefined;
+        const outputIdx2 = rest.indexOf('--output');
+        const outputFile2 = outputIdx2 >= 0 ? rest[outputIdx2 + 1] : undefined;
+        return runParse(inputPath, outputFile || outputFile2);
+    }
+    if (cmd === 'validate') {
+        const inputPath = rest.find(a => !a.startsWith('-')) || '.';
+        const strict = rest.includes('--strict');
+        const formatIdx = rest.indexOf('--format');
+        const format = formatIdx >= 0 ? rest[formatIdx + 1] : 'human';
+        return runValidate(inputPath, { strict }, format);
+    }
+    throw new Error(`Unknown command: ${cmd}`);
+}
+// --- Internal ---
+async function buildAST(inputPath) {
+    const resolved = resolvePath(inputPath);
+    const files = await readM3LFiles(resolved);
+    if (files.length === 0) {
+        throw new Error(`No .m3l.md files found at: ${inputPath}`);
+    }
+    const parsedFiles = files.map(f => parseFileContent(f.content, f.path));
+    // Try to read project config
+    let projectInfo;
+    try {
+        const config = await readProjectConfig(resolved);
+        if (config)
+            projectInfo = config;
+    }
+    catch {
+        // No config — that's fine
+    }
+    return resolve(parsedFiles, projectInfo || undefined);
+}
+function formatHumanDiagnostics(errors, warnings, fileCount) {
+    const lines = [];
+    for (const d of [...errors, ...warnings]) {
+        const severity = d.severity === 'error' ? 'error' : 'warning';
+        lines.push(`${d.file}:${d.line}:${d.col} ${severity}[${d.code}]: ${d.message}`);
+    }
+    lines.push(`${errors.length} error${errors.length !== 1 ? 's' : ''}, ${warnings.length} warning${warnings.length !== 1 ? 's' : ''} in ${fileCount} file${fileCount !== 1 ? 's' : ''}.`);
+    return lines.join('\n');
+}
+function extractErrorCount(output, format) {
+    if (format === 'json') {
+        try {
+            const parsed = JSON.parse(output);
+            return parsed.summary?.errors || 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    const match = output.match(/(\d+) error/);
+    return match ? parseInt(match[1], 10) : 0;
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { lex } from './lexer.js';
+export { parseTokens, parseString as parseFileString } from './parser.js';
+export { resolve } from './resolver.js';
+export { validate } from './validator.js';
+export { readM3LFiles, readM3LString, readProjectConfig } from './reader.js';
+export type * from './types.js';
+import type { M3LAST, ValidateOptions } from './types.js';
+/**
+ * High-level API: Parse M3L files from a path (file or directory) into a merged AST.
+ */
+export declare function parse(inputPath: string): Promise<M3LAST>;
+/**
+ * High-level API: Parse M3L content string into AST.
+ */
+export declare function parseString(content: string, filename?: string): M3LAST;
+/**
+ * High-level API: Validate M3L files from a path.
+ */
+export declare function validateFiles(inputPath: string, options?: ValidateOptions): Promise<{
+    ast: M3LAST;
+    errors: import('./types.js').Diagnostic[];
+    warnings: import('./types.js').Diagnostic[];
+}>;

package/dist/index.js

@@ -0,0 +1,46 @@
+export { lex } from './lexer.js';
+export { parseTokens, parseString as parseFileString } from './parser.js';
+export { resolve } from './resolver.js';
+export { validate } from './validator.js';
+export { readM3LFiles, readM3LString, readProjectConfig } from './reader.js';
+import { readM3LFiles, readProjectConfig } from './reader.js';
+import { parseString as parseFileContent } from './parser.js';
+import { resolve } from './resolver.js';
+import { validate as validateAST } from './validator.js';
+import { resolve as resolvePath } from 'path';
+/**
+ * High-level API: Parse M3L files from a path (file or directory) into a merged AST.
+ */
+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}`);
+    }
+    const parsedFiles = files.map(f => parseFileContent(f.content, f.path));
+    let projectInfo;
+    try {
+        const config = await readProjectConfig(resolved);
+        if (config)
+            projectInfo = config;
+    }
+    catch {
+        // No config
+    }
+    return resolve(parsedFiles, projectInfo || undefined);
+}
+/**
+ * High-level API: Parse M3L content string into AST.
+ */
+export function parseString(content, filename = 'inline.m3l.md') {
+    const parsed = parseFileContent(content, filename);
+    return resolve([parsed]);
+}
+/**
+ * High-level API: Validate M3L files from a path.
+ */
+export async function validateFiles(inputPath, options) {
+    const ast = await parse(inputPath);
+    const result = validateAST(ast, options);
+    return { ast, ...result };
+}

package/dist/lexer.d.ts

@@ -0,0 +1,5 @@
+import type { Token } from './types.js';
+/**
+ * Tokenize M3L markdown content into a sequence of tokens.
+ */
+export declare function lex(content: string, file: string): Token[];