@maias/core 0.2.0

package/dist/parse.js

@@ -0,0 +1,65 @@
+import { LineCounter, parseDocument } from 'yaml';
+import { CODES } from './diagnostics.js';
+/**
+ * A parsed MAIAS document. Wraps the `yaml` Document (which preserves comments
+ * and source ranges for round-trip edits and line-referenced diagnostics)
+ * together with the plain-data view used by validation and graph utilities.
+ *
+ * JSON input is parsed through the same YAML parser (JSON is a YAML subset),
+ * so positions and edits work identically; `format` records the original
+ * serialisation so `toString()` can emit it back.
+ */
+export class ParsedDocument {
+    ydoc;
+    lineCounter;
+    format;
+    constructor(ydoc, lineCounter, format) {
+        this.ydoc = ydoc;
+        this.lineCounter = lineCounter;
+        this.format = format;
+    }
+    /** Plain-data view. Recomputed on each call — cheap, and edits stay visible. */
+    get data() {
+        return this.ydoc.toJS();
+    }
+    /** 1-based line/col for a JSON path, when resolvable. */
+    position(path) {
+        const node = this.ydoc.getIn(path, true);
+        const offset = node?.range?.[0];
+        if (offset === undefined) {
+            // Fall back to the parent so e.g. a missing required key still points somewhere useful.
+            if (path.length === 0)
+                return undefined;
+            return this.position(path.slice(0, -1));
+        }
+        const pos = this.lineCounter.linePos(offset);
+        return { line: pos.line, col: pos.col };
+    }
+    /** Serialise. YAML keeps comments and (for unedited nodes) original layout. */
+    toString() {
+        if (this.format === 'json') {
+            return JSON.stringify(this.ydoc.toJS(), null, 2) + '\n';
+        }
+        return this.ydoc.toString({ lineWidth: 0 });
+    }
+}
+/** Parse MAIAS source text (YAML or JSON). Syntax errors come back as diagnostics, never throws. */
+export function parse(text, opts = {}) {
+    const format = opts.format ?? (looksLikeJson(text) ? 'json' : 'yaml');
+    const lineCounter = new LineCounter();
+    const ydoc = parseDocument(text, { lineCounter, keepSourceTokens: true });
+    const diagnostics = ydoc.errors.map((err) => ({
+        code: CODES.PARSE,
+        severity: 'error',
+        message: err.message.split('\n')[0],
+        path: [],
+        line: err.linePos?.[0]?.line,
+        col: err.linePos?.[0]?.col,
+    }));
+    if (diagnostics.length > 0)
+        return { diagnostics };
+    return { parsed: new ParsedDocument(ydoc, lineCounter, format), diagnostics };
+}
+function looksLikeJson(text) {
+    return text.trimStart().startsWith('{');
+}

package/dist/schema-validate.d.ts

@@ -0,0 +1,3 @@
+import { type Diagnostic } from './diagnostics.js';
+import type { ParsedDocument } from './parse.js';
+export declare function schemaValidate(parsed: ParsedDocument): Diagnostic[];

package/dist/schema-validate.js

@@ -0,0 +1,97 @@
+import { Validator } from '@cfworker/json-schema';
+import { MAIAS_SCHEMA as schema } from './maias-schema.gen.js';
+import { CODES } from './diagnostics.js';
+// @cfworker/json-schema is an interpreting validator (no eval/new Function),
+// so this exact code path runs under Node and React Native/Hermes alike (D11).
+const validator = new Validator(schema, '2020-12', false);
+/** Keywords whose output units describe a concrete leaf problem (vs. structural bookkeeping). */
+const LEAF_KEYWORDS = new Set([
+    'type',
+    'required',
+    'pattern',
+    'enum',
+    'const',
+    'minItems',
+    'uniqueItems',
+    'minLength',
+    'additionalProperties',
+]);
+export function schemaValidate(parsed) {
+    const result = validator.validate(parsed.data);
+    if (result.valid)
+        return [];
+    const seen = new Set();
+    const diagnostics = [];
+    const units = result.errors.filter((u) => !isCascade(u, result.errors));
+    for (const unit of units) {
+        if (!LEAF_KEYWORDS.has(unit.keyword))
+            continue;
+        const path = pointerToPath(unit.instanceLocation);
+        const message = describe(unit.keyword, unit, path);
+        const key = `${unit.instanceLocation}|${message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        diagnostics.push({
+            code: CODES.SCHEMA,
+            severity: 'error',
+            message,
+            path,
+            ...parsed.position(path),
+        });
+    }
+    // Everything was filtered as structural noise — surface the raw root cause rather than nothing.
+    if (diagnostics.length === 0 && result.errors.length > 0) {
+        const unit = result.errors[result.errors.length - 1];
+        const path = pointerToPath(unit.instanceLocation);
+        diagnostics.push({
+            code: CODES.SCHEMA,
+            severity: 'error',
+            message: unit.error,
+            path,
+            ...parsed.position(path),
+        });
+    }
+    return diagnostics;
+}
+/**
+ * `additionalProperties: false` failures cascade: when `screens.0.elements.1.target`
+ * fails its pattern, every ancestor also reports "Property X does not match
+ * additional properties schema". A unit is such a cascade when the property it
+ * names has its own deeper error units. Genuine unknown keys (typos) have no
+ * deeper units and are kept.
+ */
+function isCascade(unit, all) {
+    if (unit.keyword !== 'additionalProperties')
+        return false;
+    const property = /^Property "([^"]+)"/.exec(unit.error)?.[1];
+    if (!property)
+        return false;
+    const childPointer = `${unit.instanceLocation === '#' ? '#' : unit.instanceLocation}/${escapePointer(property)}`;
+    return all.some((u) => u !== unit && (u.instanceLocation === childPointer || u.instanceLocation.startsWith(childPointer + '/')));
+}
+function escapePointer(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function pointerToPath(pointer) {
+    if (pointer === '#' || pointer === '')
+        return [];
+    return pointer
+        .replace(/^#\//, '')
+        .split('/')
+        .map((seg) => {
+        const dec = seg.replace(/~1/g, '/').replace(/~0/g, '~');
+        return /^\d+$/.test(dec) ? Number(dec) : dec;
+    });
+}
+function describe(keyword, unit, path) {
+    const where = path.length ? path.join('.') : 'document root';
+    switch (keyword) {
+        case 'additionalProperties':
+            return `${unit.error} at ${where} — unknown keys must be x_-prefixed (spec §10.3)`;
+        case 'pattern':
+            return `${unit.error} at ${where}`;
+        default:
+            return `${unit.error} at ${where}`;
+    }
+}

package/dist/validate.d.ts

@@ -0,0 +1,11 @@
+import { type Diagnostic } from './diagnostics.js';
+import { type ParsedDocument } from './parse.js';
+export interface ValidationResult {
+    /** No parse errors, no schema errors, no lint errors. Warnings do not affect validity. */
+    valid: boolean;
+    diagnostics: Diagnostic[];
+    /** Present whenever the source parsed, even if invalid. */
+    parsed?: ParsedDocument;
+}
+/** Full validation: parse (if given text) → JSON Schema → semantic lint. */
+export declare function validate(source: string | ParsedDocument): ValidationResult;

package/dist/validate.js

@@ -0,0 +1,19 @@
+import { hasErrors, sortDiagnostics } from './diagnostics.js';
+import { lint } from './lint.js';
+import { parse } from './parse.js';
+import { schemaValidate } from './schema-validate.js';
+/** Full validation: parse (if given text) → JSON Schema → semantic lint. */
+export function validate(source) {
+    let parsed;
+    if (typeof source === 'string') {
+        const result = parse(source);
+        if (!result.parsed)
+            return { valid: false, diagnostics: sortDiagnostics(result.diagnostics) };
+        parsed = result.parsed;
+    }
+    else {
+        parsed = source;
+    }
+    const diagnostics = sortDiagnostics([...schemaValidate(parsed), ...lint(parsed)]);
+    return { valid: !hasErrors(diagnostics), diagnostics, parsed };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@maias/core",
+  "version": "0.2.0",
+  "description": "MAIAS core library: parse, typed model, canonical serialise, graph utilities, safe edits, validation. The single implementation all MAIAS tooling builds on.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MAIAS-project/maias.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "maias",
+    "information-architecture",
+    "yaml",
+    "schema",
+    "validation",
+    "canonical-form",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "scripts": {
+    "sync-schema": "node scripts/sync-schema.mjs",
+    "prebuild": "npm run sync-schema",
+    "build": "tsc -p tsconfig.json",
+    "pretypecheck": "npm run sync-schema",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "yaml": "^2.8.0"
+  }
+}