@iyulab/m3l 0.1.4 → 0.5.0

package/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse a single M3L file and return the AST as JSON.
+ *
+ * @param content - M3L markdown text
+ * @param filename - Source filename for error reporting
+ * @returns JSON string with `{ success: boolean, data?: AST, error?: string }`
+ */
+export function parse(content: string, filename: string): string;
+
+/**
+ * Parse multiple M3L files and return the merged AST as JSON.
+ *
+ * @param filesJson - JSON array of `{ content: string, filename: string }` objects
+ * @returns JSON string with `{ success: boolean, data?: AST, error?: string }`
+ */
+export function parseMulti(filesJson: string): string;
+
+/**
+ * Validate M3L content and return diagnostics as JSON.
+ *
+ * @param content - M3L markdown text
+ * @param optionsJson - JSON options `{ strict?: boolean, filename?: string }`
+ * @returns JSON string with `{ success: boolean, data?: ValidateResult, error?: string }`
+ */
+export function validate(content: string, optionsJson: string): string;

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * @iyulab/m3l — M3L parser (Rust native via NAPI)
+ *
+ * Thin wrapper that re-exports the native NAPI addon.
+ * All parsing is performed by the Rust m3l-core library.
+ */
+
+const { parse, parseMulti, validate } = require('@iyulab/m3l-napi');
+
+module.exports.parse = parse;
+module.exports.parseMulti = parseMulti;
+module.exports.validate = validate;

package/package.json

@@ -1,34 +1,29 @@
 {
   "name": "@iyulab/m3l",
-  "version": "0.1.4",
-  "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"
-  },
+  "version": "0.5.0",
+  "description": "M3L parser — Markdown-based schema definition language (.m3l.md → JSON AST)",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
   "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"
+    "@iyulab/m3l-napi": "0.5.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">= 18"
   },
-  "files": [
-    "dist"
-  ],
-  "license": "MIT"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iyulab/m3l"
+  },
+  "keywords": [
+    "m3l",
+    "markdown",
+    "schema",
+    "parser",
+    "ast"
+  ]
 }

package/README.md

@@ -1,305 +0,0 @@
-# @iyulab/m3l
-
-[![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.
-
-## 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 |
-| `## @name ::attribute` | Attribute registry entry |
-| `- field: type` | Field definition |
-| `- field: type?` | Nullable field |
-| `- field: type[]` | Array field |
-| `- field: type?[]` | Array of nullable items |
-| `- field: type = val` | Field with default value |
-| `@attr` / `@attr(args)` | Attribute (constraint, index, etc.) |
-| `` `[FrameworkAttr]` `` | Custom framework attribute |
-| `### 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 {
-  parserVersion: string;   // Parser package version (semver)
-  astVersion: string;      // AST schema version
-  project: { name?: string; version?: string };
-  sources: string[];
-  models: ModelNode[];
-  enums: EnumNode[];
-  interfaces: ModelNode[];
-  views: ModelNode[];
-  attributeRegistry: AttributeRegistryEntry[];
-  errors: Diagnostic[];
-  warnings: Diagnostic[];
-}
-```
-
-### Key AST types
-
-```typescript
-interface FieldNode {
-  name: string;
-  label?: string;
-  type?: string;
-  params?: (string | number)[];
-  generic_params?: string[];     // map<K,V> -> ["K", "V"]
-  nullable: boolean;
-  array: boolean;
-  arrayItemNullable: boolean;    // string?[] -> true
-  kind: 'stored' | 'computed' | 'lookup' | 'rollup';
-  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 };
-  enum_values?: EnumValue[];
-  fields?: FieldNode[];          // sub-fields for object type
-  loc: SourceLocation;
-}
-
-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;
-  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:
-
-**Errors:**
-| Code | Description |
-|------|-------------|
-| 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 |
-|------|-------------|
-| M3L-W001 | Field line exceeds 80 characters |
-| M3L-W002 | Object nesting exceeds 3 levels |
-| M3L-W004 | Lookup chain exceeds 3 hops |
-
-## 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 }`.
-
-### `STANDARD_ATTRIBUTES: Set<string>`
-
-The set of 27 M3L standard attribute names (e.g. `primary`, `unique`, `reference`, `computed`, ...).
-
-### 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 });
-```
-
-## Compatibility
-
-This TypeScript parser and the [C# parser](../csharp/) produce equivalent AST structures. Both share the same conformance test suite.
-
-| | TypeScript | C# |
-|---|---|---|
-| Package | `@iyulab/m3l` | `M3LParser` |
-| Runtime | Node.js 20+ | .NET 8.0+ |
-| AST Version | 1.0 | 1.0 |
-
-Version is managed centrally via the root `VERSION` file.
-
-## License
-
-MIT

package/dist/cli.d.ts

@@ -1,14 +0,0 @@
-#!/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

@@ -1,150 +0,0 @@
-#!/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

@@ -1,23 +0,0 @@
-export { lex } from './lexer.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';
-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

@@ -1,46 +0,0 @@
-export { lex } from './lexer.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';
-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 or .m3l 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

@@ -1,6 +0,0 @@
-import type { Token } from './types.js';
-/**
- * Tokenize M3L markdown content into a sequence of tokens.
- */
-export declare function lex(content: string, file: string): Token[];
-export declare function parseTypeAndAttrs(rest: string, data: Record<string, unknown>): void;