@archcode-io/engine 0.2.0-preview.0

package/dist/src/check.js

@@ -0,0 +1,192 @@
+import { diag } from './diagnostics.js';
+import { ATTR_KEYS, IFACE_VERBS, OBJECT_KINDS, PLACEMENT_KINDS, RESERVED_KINDS, RUN_KEYS, VERBS } from './vocab.js';
+/**
+ * Semantic diagnostics (spec §17.10). The parser only knows shapes; this pass
+ * knows names. It never changes the document and never stops a render — the
+ * lens still draws what it can — it only says what a reader would trip on.
+ *
+ *   AC100  duplicate id                      error
+ *   AC101  unresolved reference              warning
+ *   AC102  ambiguous reference               warning
+ *   AC103  reserved block kind               info      (rule · decision · board · profile — kept, not interpreted)
+ *   AC104  unknown attribute                 info      (`x-…` keys are silent: they are yours)
+ *   AC105  `archcode <version>` pragma       warning   (unknown version, or not the first statement)
+ *   AC106  `at` without a moment             error
+ *   AC107  relation between placement blocks warning   (a node does not `call` a cluster — put things inside)
+ *   AC108  `run` outside a placement block   error
+ *   AC109  `run` of something that cannot run warning  (an actor, an external, a topic)
+ */
+export const LANGUAGE_VERSIONS = new Set(['0.1', '0.2']);
+const RUNNABLE = new Set(['service', 'webapp', 'app', 'gateway', 'broker', 'datastore', 'cache', 'function', 'job', 'component']);
+const isMoment = (v) => /^(\d{4}(-\d{2}){0,2}|\+\d+[dwmy])$/.test(v);
+/** Every full id a reference could mean, from where it is written. */
+function candidates(ref, scope, m) {
+    if (m.objects.has(ref))
+        return [ref];
+    let s = scope;
+    while (s) {
+        const cand = `${s}.${ref}`;
+        if (m.objects.has(cand))
+            return [cand];
+        const dot = s.lastIndexOf('.');
+        s = dot < 0 ? undefined : s.slice(0, dot);
+    }
+    return [...m.objects.keys()].filter(k => k.endsWith(`.${ref}`));
+}
+export function check(doc, m) {
+    const out = [];
+    // Strictness follows the stage (§17.4): a sketch or a retired thing is not
+    // scolded at all, a proposal only warned. The stage a line sits under is the
+    // stage of the innermost declaration that carries one.
+    const stageOfLine = new Map();
+    const stageWalk = (nodes, inherited) => {
+        for (const n of nodes) {
+            if (n.type !== 'decl')
+                continue;
+            const d = n;
+            const own = d.inline.find(a => a.key === 'stage')?.values[0]
+                ?? (d.body ?? []).filter(c => c.type === 'attr').map(c => c).find(a => a.key === 'stage')?.values[0];
+            const stage = own ?? inherited;
+            const first = d.tokens[0]?.line ?? 0, last = d.tokens[d.tokens.length - 1]?.line ?? first;
+            if (stage)
+                for (let l = first; l <= last; l++)
+                    stageOfLine.set(l, stage);
+            stageWalk(d.body ?? [], stage);
+        }
+    };
+    stageWalk(doc.body, undefined);
+    const line = (n) => n.tokens[0]?.line ?? 0;
+    const col = (n) => n.tokens[0]?.col ?? 1;
+    // Reference lookups only ever see model objects, so a name that resolves
+    // is fine wherever it was written; a name that does not is reported once.
+    const refCheck = (ref, scope, what, n) => {
+        if (!ref || /^\d/.test(ref))
+            return;
+        const c = candidates(ref, scope, m);
+        if (c.length === 0)
+            out.push(diag('warning', 'AC101', `${what} \`${ref}\` is not declared anywhere`, line(n), col(n)));
+        else if (c.length > 1)
+            out.push(diag('warning', 'AC102', `${what} \`${ref}\` could be ${c.join(' or ')} — write the full path`, line(n), col(n)));
+    };
+    // ---- pragma: first statement or nowhere ----
+    let first = true;
+    const seen = new Map();
+    const walk = (nodes, parent, parentKind, depth) => {
+        for (const n of nodes) {
+            if (n.type === 'blank')
+                continue;
+            if (n.type === 'attr' && n.key === 'archcode' && depth === 0) {
+                const v = n.values[0] ?? '';
+                if (!first)
+                    out.push(diag('warning', 'AC105', '`archcode <version>` belongs at the top of the document', line(n), col(n)));
+                else if (!LANGUAGE_VERSIONS.has(v))
+                    out.push(diag('warning', 'AC105', `archcode ${v || '?'} — this engine reads ${[...LANGUAGE_VERSIONS].join(', ')}`, line(n), col(n)));
+                first = false;
+                continue;
+            }
+            first = false;
+            if (n.type === 'decl') {
+                const d = n;
+                const id = parent && !d.id.includes('.') ? `${parent}.${d.id}` : d.id;
+                if (seen.has(id))
+                    out.push(diag('error', 'AC100', `\`${id}\` is declared twice (first at line ${seen.get(id)})`, line(n), col(n)));
+                else
+                    seen.set(id, line(n));
+                if (RESERVED_KINDS.has(d.kind)) {
+                    out.push(diag('info', 'AC103', `\`${d.kind}\` is reserved in v0.2 — kept as written, not interpreted`, line(n), col(n)));
+                    continue; // its body is not the model's business
+                }
+                if (d.kind === 'view')
+                    continue; // the view vocabulary is checked by the picture, not here
+                for (const a of d.inline)
+                    attrCheck(a, parent, d.kind);
+                for (const c of d.body ?? [])
+                    if (c.type === 'attr')
+                        attrCheck(c, parent, d.kind);
+                walk(d.body ?? [], id, d.kind, depth + 1);
+                continue;
+            }
+            if (n.type === 'rel') {
+                const r = n;
+                const from = r.subject ?? parent ?? '';
+                if (r.subject)
+                    refCheck(r.subject, parent, 'subject', n);
+                else if (!parent)
+                    out.push(diag('warning', 'AC101', `\`${r.verb}\` at top level needs a subject: \`checkout ${r.verb} ${r.object}\``, line(n), col(n)));
+                refCheck(r.object, parent, `${r.verb} target`, n);
+                for (const v of r.via ?? [])
+                    refCheck(v, parent, 'via', n);
+                const kindOf = (ref) => { const c = candidates(ref, parent, m); return c.length === 1 ? m.objects.get(c[0])?.kind : undefined; };
+                const fk = kindOf(from), tk = kindOf(r.object);
+                if (fk && tk && PLACEMENT_KINDS.has(fk) && PLACEMENT_KINDS.has(tk))
+                    out.push(diag('warning', 'AC107', `a ${fk} does not \`${r.verb}\` a ${tk} — nest it (\`${tk} … { ${fk} … }\`) or \`run\` something on it`, line(n), col(n)));
+                for (const c of r.body ?? [])
+                    if (c.type === 'attr')
+                        attrCheck(c, parent, 'relation');
+                continue;
+            }
+            if (n.type === 'run') {
+                const r = n;
+                if (!parentKind || !PLACEMENT_KINDS.has(parentKind))
+                    out.push(diag('error', 'AC108', '`run` only makes sense inside an env, segment, cluster, managed service or node', line(n), col(n)));
+                for (const ref of r.refs) {
+                    refCheck(ref, parent, 'run target', n);
+                    const c = candidates(ref, parent, m);
+                    const k = c.length === 1 ? m.objects.get(c[0])?.kind : undefined;
+                    if (k && !RUNNABLE.has(k))
+                        out.push(diag('warning', 'AC109', `\`${ref}\` is a ${k} — it has nowhere to run`, line(n), col(n)));
+                }
+                for (const a of r.attrs)
+                    if (!RUN_KEYS.has(a.key) && !a.key.startsWith('x-'))
+                        out.push(diag('info', 'AC104', `\`${a.key}\` is not a sizing key (${[...RUN_KEYS].join(', ')})`, line(n), col(n)));
+                for (const c of r.body ?? [])
+                    if (c.type === 'attr')
+                        attrCheck(c, parent, 'run');
+                continue;
+            }
+            if (n.type === 'iface') {
+                const f = n;
+                if (f.subject)
+                    refCheck(f.subject, parent, 'subject', n);
+                else if (!parent)
+                    out.push(diag('warning', 'AC101', `\`${f.verb}\` at top level needs a subject: \`checkout ${f.verb} ${f.kind} …\``, line(n), col(n)));
+                continue;
+            }
+            if (n.type === 'attr' && depth === 0) {
+                const a = n;
+                // a lone verb line at the top means someone forgot the subject
+                if (VERBS.has(a.key) || IFACE_VERBS.has(a.key))
+                    out.push(diag('warning', 'AC101', `\`${a.key}\` needs a subject at top level`, line(n), col(n)));
+                else if (!ATTR_KEYS.has(a.key) && !a.key.startsWith('x-') && !OBJECT_KINDS.has(a.key))
+                    out.push(diag('info', 'AC104', `\`${a.key}\` is not something the document knows — an object kind or an attribute?`, line(n), col(n)));
+            }
+        }
+    };
+    const attrCheck = (a, scope, ownerKind) => {
+        if (a.key === 'at') {
+            if (!a.values[0] || !isMoment(a.values[0]))
+                out.push(diag('error', 'AC106', '`at` needs a moment first: `at 2026-12 cpu 12`, `at +1y replicas 8`', line(a), col(a)));
+            return;
+        }
+        if (a.key === 'owned_by') {
+            refCheck(a.values[0] ?? '', scope, 'owned_by', a);
+            return;
+        }
+        if (a.key === 'publisher' || a.key === 'subscriber' || a.key === 'via') {
+            for (const v of a.values)
+                refCheck(v, scope, a.key, a);
+            return;
+        }
+        if (!ATTR_KEYS.has(a.key) && !a.key.startsWith('x-') && !VERBS.has(a.key))
+            out.push(diag('info', 'AC104', `\`${a.key}\` is not a known attribute of a ${ownerKind} — kept as written (prefix \`x-\` to say it is yours)`, line(a), col(a)));
+    };
+    walk(doc.body, undefined, undefined, 0);
+    return out.filter(d => {
+        const st = stageOfLine.get(d.line);
+        if (st === 'sketch' || st === 'retired')
+            return false;
+        if (st === 'proposed' && d.severity === 'error')
+            d.severity = 'warning';
+        return true;
+    }).sort((a, b) => a.line - b.line || a.col - b.col);
+}

package/dist/src/compiled.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The compiled form (spec header: `arch.json`, schema `archcode/v1`) — the
+ * model as plain data, and the same data written as YAML.
+ *
+ * This is a projection of the model, not a second syntax: comments, spacing
+ * and the order of attributes on a line are gone, ids are full paths, every
+ * attribute value is a list. It is what a tool that does not want to parse
+ * ArchCode reads, and what the docs show under the YAML and JSON tabs.
+ * Authoring in YAML or JSON (reading them back) is reserved (spec §15).
+ */
+import type { Model } from './model.js';
+export interface CompiledObject {
+    id: string;
+    kind: string;
+    name?: string;
+    parent?: string;
+    attrs?: Record<string, string[]>;
+    interfaces?: {
+        verb: string;
+        kind: string;
+        pointer?: string;
+        rev?: string;
+        label?: string;
+        attrs?: Record<string, string[]>;
+    }[];
+    timeline?: {
+        at: string;
+        attrs: Record<string, string[]>;
+    }[];
+}
+export interface CompiledRelation {
+    from: string;
+    verb: string;
+    to: string;
+    over?: string;
+    via?: string[];
+    spec?: string;
+    as?: string;
+    port?: string;
+    label?: string;
+    attrs?: Record<string, string[]>;
+}
+export interface CompiledPlacement {
+    host: string;
+    run: string;
+    attrs?: Record<string, string[]>;
+    timeline?: {
+        at: string;
+        attrs: Record<string, string[]>;
+    }[];
+}
+export interface Compiled {
+    archcode: string;
+    objects: CompiledObject[];
+    relations: CompiledRelation[];
+    placements: CompiledPlacement[];
+}
+/** The model as data. `version` is the language version the document declared, or the engine's. */
+export declare function toCompiled(m: Model, version?: string): Compiled;
+export declare const toJSON: (m: Model, version?: string) => string;
+export declare function toYAML(m: Model, version?: string): string;

package/dist/src/compiled.js

@@ -0,0 +1,91 @@
+const nonEmpty = (o) => (Object.keys(o).length ? o : undefined);
+const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+function object(o) {
+    return clean({
+        id: o.id, kind: o.kind, name: o.name, parent: o.parent,
+        attrs: nonEmpty(o.attrs),
+        interfaces: o.interfaces.length ? o.interfaces.map((f) => clean({ verb: f.verb, kind: f.kind, pointer: f.pointer, rev: f.rev, label: f.label, attrs: nonEmpty(f.attrs) })) : undefined,
+        timeline: o.timeline.length ? o.timeline.map(m => ({ at: m.when, attrs: m.attrs })) : undefined,
+    });
+}
+function relation(r) {
+    return clean({ from: r.from, verb: r.verb, to: r.to, over: r.over, via: r.via?.length ? r.via : undefined, spec: r.spec, as: r.as, port: r.port, label: r.label, attrs: nonEmpty(r.attrs) });
+}
+function placement(p) {
+    return clean({ host: p.host, run: p.ref, attrs: nonEmpty(p.attrs), timeline: p.timeline.length ? p.timeline.map(m => ({ at: m.when, attrs: m.attrs })) : undefined });
+}
+/** The model as data. `version` is the language version the document declared, or the engine's. */
+export function toCompiled(m, version = '0.2') {
+    return {
+        archcode: version,
+        objects: [...m.objects.values()].map(object),
+        relations: m.relations.map(relation),
+        placements: m.placements.map(placement),
+    };
+}
+export const toJSON = (m, version) => JSON.stringify(toCompiled(m, version), null, 2) + '\n';
+// ---- YAML: a small emitter for the shapes above (maps, lists, strings) ----
+// Every value in the compiled form is a string. A YAML reader must get the same
+// string back, so anything it would read as a number, a boolean or a tag is quoted;
+// a token with a unit or a date (`8Gi`, `2027-01`, `0.7/2`) is a string either way.
+const PLAIN = /^[A-Za-z0-9_][\w.\-\/+]*$/;
+const RESERVED = new Set(['true', 'false', 'null', 'yes', 'no', 'on', 'off', '~']);
+const scalar = (v) => (PLAIN.test(v) && !RESERVED.has(v.toLowerCase()) && !/^-?\d+(\.\d+)?$/.test(v) && !/^[\d.]+$/.test(v) ? v : JSON.stringify(v));
+const flow = (list) => `[${list.map(scalar).join(', ')}]`;
+function attrsYaml(attrs, indent) {
+    return Object.entries(attrs).map(([k, v]) => `${indent}${scalar(k)}: ${flow(v)}`);
+}
+export function toYAML(m, version) {
+    const c = toCompiled(m, version);
+    const out = [`archcode: "${c.archcode}"`];
+    const kv = (indent, k, v) => (v === undefined ? [] : [`${indent}${k}: ${scalar(v)}`]);
+    out.push('objects:');
+    for (const o of c.objects) {
+        out.push(`  - id: ${scalar(o.id)}`, `    kind: ${o.kind}`, ...kv('    ', 'name', o.name), ...kv('    ', 'parent', o.parent));
+        if (o.attrs) {
+            out.push('    attrs:');
+            out.push(...attrsYaml(o.attrs, '      '));
+        }
+        if (o.interfaces) {
+            out.push('    interfaces:');
+            for (const f of o.interfaces) {
+                out.push(`      - verb: ${f.verb}`, `        kind: ${f.kind}`, ...kv('        ', 'pointer', f.pointer), ...kv('        ', 'rev', f.rev), ...kv('        ', 'label', f.label));
+                if (f.attrs) {
+                    out.push('        attrs:');
+                    out.push(...attrsYaml(f.attrs, '          '));
+                }
+            }
+        }
+        if (o.timeline) {
+            out.push('    timeline:');
+            for (const t of o.timeline) {
+                out.push(`      - at: ${scalar(t.at)}`, '        attrs:');
+                out.push(...attrsYaml(t.attrs, '          '));
+            }
+        }
+    }
+    out.push(c.relations.length ? 'relations:' : 'relations: []');
+    for (const r of c.relations) {
+        out.push(`  - from: ${scalar(r.from)}`, `    verb: ${r.verb}`, `    to: ${scalar(r.to)}`, ...kv('    ', 'over', r.over), ...(r.via ? [`    via: ${flow(r.via)}`] : []), ...kv('    ', 'spec', r.spec), ...kv('    ', 'as', r.as), ...kv('    ', 'port', r.port), ...kv('    ', 'label', r.label));
+        if (r.attrs) {
+            out.push('    attrs:');
+            out.push(...attrsYaml(r.attrs, '      '));
+        }
+    }
+    out.push(c.placements.length ? 'placements:' : 'placements: []');
+    for (const p of c.placements) {
+        out.push(`  - host: ${scalar(p.host)}`, `    run: ${scalar(p.run)}`);
+        if (p.attrs) {
+            out.push('    attrs:');
+            out.push(...attrsYaml(p.attrs, '      '));
+        }
+        if (p.timeline) {
+            out.push('    timeline:');
+            for (const t of p.timeline) {
+                out.push(`      - at: ${scalar(t.at)}`, '        attrs:');
+                out.push(...attrsYaml(t.attrs, '          '));
+            }
+        }
+    }
+    return out.join('\n') + '\n';
+}

package/dist/src/cst.d.ts

@@ -0,0 +1,76 @@
+import type { Token } from './tokens.js';
+/**
+ * Concrete syntax tree. Every node owns a contiguous slice of the token stream,
+ * so serialization is concatenation and round-trip is byte-exact by construction.
+ */
+export type Node = Doc | Decl | Attr | Rel | Run | Iface | Raw | Blank;
+export interface Base {
+    tokens: Token[];
+}
+export interface Doc extends Base {
+    type: 'doc';
+    body: Node[];
+    /** The EOF token, which carries any trailing whitespace or comment. */
+    tail: Token[];
+}
+/** `service checkout "Checkout" tech Go { … }` */
+export interface Decl extends Base {
+    type: 'decl';
+    kind: string;
+    id: string;
+    name?: string;
+    inline: Attr[];
+    body?: Node[];
+}
+/** `tech Go` · `tags core, sales` */
+export interface Attr extends Base {
+    type: 'attr';
+    key: string;
+    values: string[];
+}
+/** `checkout writes orders_db over SQL via gw "label"` */
+export interface Rel extends Base {
+    type: 'rel';
+    subject?: string;
+    verb: string;
+    canonicalVerb: string;
+    object: string;
+    over?: string;
+    via?: string[];
+    spec?: string;
+    as?: string;
+    port?: string;
+    label?: string;
+    body?: Node[];
+}
+/**
+ * `exposes http openapi://checkout.yaml @9f3c2e1` · `stores schema sql://payments.dbml` · `exposes cli`
+ * An interface the enclosing object offers (spec §4.3): the kind names the
+ * standard, the pointer is an address, never content; `@rev` is the revision
+ * the declaration was made against.
+ */
+export interface Iface extends Base {
+    type: 'iface';
+    subject?: string;
+    verb: 'exposes' | 'stores';
+    kind: string;
+    pointer?: string;
+    rev?: string;
+    label?: string;
+    body?: Node[];
+}
+/** `run checkout, fulfillment replicas 6 cpu 2 mem 4Gi { at 2026-12 replicas 12 }` */
+export interface Run extends Base {
+    type: 'run';
+    refs: string[];
+    attrs: Attr[];
+    body?: Node[];
+}
+/** The body of a reserved or `view` block: kept as tokens, read by nobody here. */
+export interface Raw extends Base {
+    type: 'raw';
+}
+/** A line that carries no statement: blank, or comment-only. */
+export interface Blank extends Base {
+    type: 'blank';
+}

package/dist/src/cst.js

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

package/dist/src/diagnostics.d.ts

@@ -0,0 +1,9 @@
+export type Severity = 'error' | 'warning' | 'info';
+export interface Diagnostic {
+    severity: Severity;
+    code: string;
+    message: string;
+    line: number;
+    col: number;
+}
+export declare const diag: (severity: Severity, code: string, message: string, line: number, col: number) => Diagnostic;

package/dist/src/diagnostics.js

@@ -0,0 +1 @@
+export const diag = (severity, code, message, line, col) => ({ severity, code, message, line, col });

package/dist/src/edit.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Append one statement written in the notation itself — a declaration or a
+ * relation typed into the canvas terminal. The line goes in verbatim, before
+ * the first `view`/`board` block, so what the person typed is what the file
+ * says; nothing is normalised on the way in.
+ */
+export declare function insertStatement(src: string, line: string): string;
+export declare function addObject(src: string, o: {
+    kind: string;
+    id: string;
+    name?: string;
+    attrs?: Record<string, string>;
+}): string;
+export declare function deleteObject(src: string, id: string): string;
+/** Rename everywhere: the declaration and every reference to it. */
+export declare function renameObject(src: string, oldId: string, newId: string): string;
+export declare function setDisplayName(src: string, id: string, name: string): string;
+export declare function setAttribute(src: string, id: string, key: string, value: string | null): string;
+export declare function addRelation(src: string, from: string, verb: string, to: string, over?: string): string;
+/**
+ * Move one end of a relation to another object — the text edit behind
+ * dropping an arrow's end on a different card. Only the token that names the
+ * end changes; `over`, `via`, the label and the body stay as written. Matching
+ * is by local id at either end, as `deleteRelation` does.
+ */
+export declare function retargetRelation(src: string, from: string, verb: string, to: string, end: 'from' | 'to', newId: string): string;
+/** `a calls b` → `a uses b`: only the verb changes, everything else stays as written. */
+export declare function setRelationVerb(src: string, from: string, verb: string, to: string, newVerb: string): string;
+/**
+ * Set, change or drop (`value` null) an inline fact of a relation: `over`,
+ * `via`, `port`, `spec`, `as`, or the quoted `label`. A fact that is there is
+ * rewritten where it stands; a new one goes at the end of the statement's
+ * first line, before the body. `via` takes a comma-separated list.
+ */
+export declare function setRelationAttr(src: string, from: string, verb: string, to: string, key: 'over' | 'via' | 'port' | 'spec' | 'as' | 'label', value: string | null): string;
+export declare function deleteRelation(src: string, from: string, verb: string, to: string): string;
+export declare function moveOut(src: string, id: string): string;
+/** Move a declaration inside a system's block, creating the block if needed. */
+export declare function moveInto(src: string, id: string, parentId: string): string;
+/**
+ * Place a logical object on a host: `run <ref> [sizing]` goes into the host's
+ * body. A host without a body gets one; a one-line body opens up.
+ */
+export declare function addRun(src: string, hostId: string, ref: string, sizing?: string): string;
+/** Take a logical object off a host. A `run a, b` line loses one name; a `run a` line goes. */
+export declare function deleteRun(src: string, hostId: string, ref: string): string;
+/** Re-size a placement: `run checkout` → `run checkout replicas 3 cpu 2`. A shared line is split first. */
+export declare function setRunSizing(src: string, hostId: string, ref: string, sizing: string): string;