animl-cli 0.0.0-stage → 0.1.1

package/packages/cli/src/inspect-summary.js

@@ -0,0 +1,158 @@
+import { ptr } from "animl";
+function wiringSummary(model, diagnostics = []) {
+  const doc = model.doc;
+  const own = (value) => Object.entries(value ?? {}).filter(([key]) => key !== "$comment");
+  const findings = [];
+  const add = (code, pointer, message, hint) => findings.push({ code, pointer, message, hint });
+  for (const d of diagnostics)
+    if (d.code === "unused-input")
+      add(
+        "unbound-input",
+        d.pointer,
+        d.message,
+        "bind the input, use it in a condition/listener, or remove it"
+      );
+  const instanced = /* @__PURE__ */ new Set();
+  const walk = (value) => {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+      return;
+    }
+    for (const [key, v] of own(value)) {
+      if (key === "component") {
+        if (typeof v === "string") instanced.add(v);
+        else if (v && typeof v === "object")
+          Object.values(v).forEach((n) => {
+            if (typeof n === "string") instanced.add(n);
+          });
+      }
+      walk(v);
+    }
+  };
+  walk(doc);
+  for (const name of own(doc.components).map(([name2]) => name2))
+    if (!instanced.has(name))
+      add(
+        "unused-component",
+        ptr("/components", name),
+        "component is never instanced: " + name,
+        "add an instance or remove the declaration"
+      );
+  const machines = [
+    ["/machine", doc.machine],
+    ...own(doc.machines).map(([name, machine]) => [ptr("/machines", name), machine])
+  ];
+  for (const [machinePath, machine] of machines)
+    for (const [name, layer] of own(
+      machine?.layers ?? {}
+    )) {
+      const reached = /* @__PURE__ */ new Set([layer.initial]);
+      const states = own(layer.states);
+      for (const [n, s] of states) if (s.kind === "any") reached.add(n);
+      let changed = true;
+      while (changed) {
+        changed = false;
+        for (const [n, s] of states)
+          if (reached.has(n)) {
+            for (const t of s.on ?? [])
+              if (!reached.has(t.to)) {
+                reached.add(t.to);
+                changed = true;
+              }
+          }
+      }
+      for (const [n] of states)
+        if (!reached.has(n))
+          add(
+            "unreachable-state",
+            ptr(ptr(machinePath + "/layers", name) + "/states", n),
+            "state is unreachable: " + n,
+            "add a transition from a reachable state"
+          );
+    }
+  const data = doc.data;
+  const models = Object.fromEntries(own(data?.models));
+  const instances = Object.fromEntries(own(data?.instances));
+  const defaultModel = data?.model ?? Object.values(instances).find((instance) => instance.default)?.model ?? Object.values(instances)[0]?.model ?? Object.keys(models)[0];
+  const usedModels = /* @__PURE__ */ new Set([
+    ...defaultModel ? [defaultModel] : [],
+    ...Object.values(instances).map((instance) => instance.model)
+  ]);
+  const usedProperties = /* @__PURE__ */ new Set();
+  const markPath = (path, context = defaultModel) => {
+    const [instance, relative] = path.includes(":") ? path.slice(1).split(":") : [void 0, path.slice(1)];
+    let model2 = instance ? instances[instance]?.model : context;
+    for (const key of relative?.split(".") ?? []) {
+      if (!model2 || /^\d+$/.test(key)) continue;
+      const property = models[model2]?.properties[key];
+      if (!property) break;
+      usedModels.add(model2);
+      usedProperties.add(model2 + ":" + key);
+      if (property.type === "model-ref" || property.type === "list")
+        model2 = property.model ?? property.of;
+      else break;
+    }
+  };
+  const scan = (value, context = defaultModel) => {
+    if (typeof value === "string") {
+      for (const path of value.match(/\$[A-Za-z][\w-]*(?::[A-Za-z][\w-]*)?(?:\.[\w-]+)*/g) ?? [])
+        markPath(path, context);
+    } else if (Array.isArray(value)) value.forEach((v) => scan(v, context));
+    else if (value && typeof value === "object") {
+      const object = value;
+      if (typeof object.data === "string" && models[object.data]) {
+        context = object.data;
+        usedModels.add(context);
+      }
+      for (const [key, child] of own(object)) {
+        if (key === "data" && typeof child === "object") continue;
+        scan(key, context);
+        scan(child, context);
+      }
+    }
+  };
+  scan(doc);
+  for (const [name, definition] of Object.entries(models)) scan(definition.properties, name);
+  let growing = true;
+  while (growing) {
+    growing = false;
+    for (const name of [...usedModels])
+      for (const property of Object.values(models[name]?.properties ?? {})) {
+        const child = property.model ?? property.of;
+        if (child && models[child] && !usedModels.has(child)) {
+          usedModels.add(child);
+          growing = true;
+        }
+      }
+  }
+  for (const [name, m] of Object.entries(models)) {
+    if (!usedModels.has(name))
+      add(
+        "unused-model",
+        ptr("/data/models", name),
+        "model is unused: " + name,
+        "select this model or remove it"
+      );
+    for (const prop of own(m.properties).map(([name2]) => name2))
+      if (!usedProperties.has(name + ":" + prop))
+        add(
+          "unused-property",
+          ptr(ptr("/data/models", name) + "/properties", prop),
+          "property is unused: " + prop,
+          "bind the property or remove it"
+        );
+  }
+  for (const [i, l] of (doc.listeners ?? []).entries())
+    if ("target" in l && !model.nodes.some((n) => n.id === l.target))
+      add(
+        "listener-target",
+        "/listeners/" + i + "/target",
+        "listener target does not exist",
+        "choose a node id"
+      );
+  return findings;
+}
+export {
+  wiringSummary
+};

package/packages/cli/src/library.d.ts

@@ -0,0 +1,6 @@
+export interface LibraryUpdate {
+    source: string;
+    file: string;
+    changed: boolean;
+}
+export declare function updateLibraries(file: string, check?: boolean): LibraryUpdate[];

package/packages/cli/src/library.js

@@ -0,0 +1,67 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseXml } from "animl/internal/packages/markup/src/xml.js";
+function updateLibraries(file, check = false) {
+  const seen = /* @__PURE__ */ new Set(), pending = /* @__PURE__ */ new Map();
+  const local = (path, base) => {
+    if (/^[a-z][a-z\d+.-]*:|^\/\//i.test(path))
+      throw Object.assign(new Error("library update accepts local files only"), {
+        code: "library-local-only",
+        pointer: "/imports",
+        hint: "use a local source path on the import"
+      });
+    return resolve(dirname(base), path);
+  };
+  const visit = (file2, text = readFileSync(file2, "utf8")) => {
+    if (seen.has(file2)) return;
+    seen.add(file2);
+    const parsed = parseXml(text);
+    if (parsed.errors.length || !parsed.doc.root || !["anima", "library"].includes(parsed.doc.root.name))
+      throw Object.assign(new Error("invalid AniML library source " + file2), {
+        code: "library-source",
+        pointer: "",
+        hint: "fix the XML and use an anima or library root"
+      });
+    for (const el of parsed.doc.root.children) {
+      if (el.kind !== "element" || el.name !== "import") continue;
+      const attr = (name) => el.attrs.find((a) => a.name === name)?.value;
+      const src = attr("src");
+      if (!src) continue;
+      const destination = local(src, file2), source = attr("source");
+      if (!source) {
+        visit(destination);
+        continue;
+      }
+      const upstream = local(source, file2), next = readFileSync(upstream, "utf8"), lib = parseXml(next);
+      if (lib.errors.length || lib.doc.root?.name !== "library")
+        throw Object.assign(new Error("upstream must be an AniML library " + upstream), {
+          code: "library-source",
+          pointer: "/imports",
+          hint: "point source at a valid local library"
+        });
+      const previous = pending.get(destination);
+      if (previous && previous.source !== upstream)
+        throw Object.assign(new Error("conflicting sources for " + destination), {
+          code: "library-source",
+          pointer: "/imports",
+          hint: "use one upstream per vendored file"
+        });
+      pending.set(destination, { source: upstream, text: next });
+      visit(destination, next);
+    }
+  };
+  visit(resolve(file));
+  const updates = [...pending].map(([file2, { source, text }]) => ({
+    file: file2,
+    source,
+    text,
+    changed: readFileSync(file2, "utf8") !== text
+  }));
+  if (!check) {
+    for (const update of updates) if (update.changed) writeFileSync(update.file, update.text);
+  }
+  return updates.map(({ file: file2, source, changed }) => ({ file: file2, source, changed }));
+}
+export {
+  updateLibraries
+};

package/packages/cli/src/locate.d.ts

@@ -0,0 +1,13 @@
+export interface Located {
+    /** Pointer → offset of the value (for keys: of the key's value). */
+    at: Map<string, number>;
+    duplicates: {
+        pointer: string;
+        offset: number;
+    }[];
+}
+export declare function locate(text: string): Located;
+/** 1-based line and column of an offset. */
+export declare function lineCol(text: string, offset: number): [number, number];
+/** Offset of the first JSON syntax error, or null if the text is JSON (RFC 8259). */
+export declare function syntaxErrorAt(text: string): number | null;

package/packages/cli/src/locate.js

@@ -0,0 +1,118 @@
+const esc = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+function locate(text) {
+  const at = /* @__PURE__ */ new Map();
+  const duplicates = [];
+  let i = 0;
+  const ws = () => {
+    while (/\s/.test(text[i] ?? "")) i++;
+  };
+  const str = () => {
+    const start = i;
+    i++;
+    while (text[i] !== '"') i += text[i] === "\\" ? 2 : 1;
+    i++;
+    return JSON.parse(text.slice(start, i));
+  };
+  const open = [];
+  const next = (f) => {
+    if (!f.seen) return `${f.p}/${f.n++}`;
+    ws();
+    const keyAt = i;
+    const k = str();
+    const kp = `${f.p}/${esc(k)}`;
+    if (f.seen.has(k)) duplicates.push({ pointer: kp, offset: keyAt });
+    f.seen.add(k);
+    ws();
+    i++;
+    return kp;
+  };
+  let p = "";
+  for (; ; ) {
+    ws();
+    at.set(p, i);
+    const c = text[i];
+    if (c === "{" || c === "[") {
+      i++;
+      ws();
+      if (text[i] === (c === "{" ? "}" : "]")) i++;
+      else {
+        const f = { p, seen: c === "{" ? /* @__PURE__ */ new Set() : void 0, n: 0 };
+        open.push(f);
+        p = next(f);
+        continue;
+      }
+    } else if (c === '"') str();
+    else while (i < text.length && !/[\s,\]}]/.test(text[i])) i++;
+    for (; ; ) {
+      const f = open.at(-1);
+      if (!f) return { at, duplicates };
+      ws();
+      if (text[i++] !== ",") open.pop();
+      else {
+        p = next(f);
+        break;
+      }
+    }
+  }
+}
+function lineCol(text, offset) {
+  const before = text.slice(0, offset);
+  const line = before.split("\n").length;
+  return [line, offset - before.lastIndexOf("\n")];
+}
+const STRING = /"(?:[^"\\\u0000-\u001f]|\\["\\/bfnrt]|\\u[0-9a-fA-F]{4})*"/y;
+function syntaxErrorAt(text) {
+  let i = 0;
+  const fail = () => {
+    throw i;
+  };
+  const ws = () => {
+    while (/[ \t\n\r]/.test(text[i] ?? "")) i++;
+  };
+  const lit = (re) => {
+    re.lastIndex = i;
+    if (!re.test(text)) fail();
+    i = re.lastIndex;
+  };
+  const value = (depth) => {
+    if (depth > 512) fail();
+    ws();
+    const c = text[i];
+    if (c === "{" || c === "[") {
+      const close = c === "{" ? "}" : "]";
+      i++;
+      ws();
+      if (text[i] === close) return void i++;
+      for (; ; ) {
+        if (c === "{") {
+          ws();
+          if (text[i] !== '"') fail();
+          lit(STRING);
+          ws();
+          if (text[i] !== ":") fail();
+          i++;
+        }
+        value(depth + 1);
+        ws();
+        if (text[i] === ",") i++;
+        else if (text[i] === close) return void i++;
+        else fail();
+      }
+    }
+    if (c === '"') return lit(STRING);
+    if (c === "t" || c === "f" || c === "n") return lit(/true|false|null/y);
+    lit(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][-+]?\d+)?/y);
+  };
+  try {
+    value(0);
+    ws();
+    return i < text.length ? i : null;
+  } catch (at) {
+    return at;
+  }
+}
+export {
+  lineCol,
+  locate,
+  syntaxErrorAt
+};

package/packages/cli/src/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/packages/cli/src/main.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+try {
+  const { run } = await import("./cli.js");
+  process.exitCode = await run(process.argv.slice(2), {
+    write: (s) => process.stdout.write(s),
+    out: (s) => process.stdout.write(s + "\n"),
+    err: (s) => process.stderr.write(s + "\n")
+  });
+} catch (error) {
+  if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+  process.stderr.write("Anima CLI dependencies are missing; run npm ci at the repo root.\n");
+  process.exitCode = 2;
+}

package/packages/cli/src/playground.d.ts

@@ -0,0 +1,11 @@
+import { type Server } from 'node:http';
+export interface PlaygroundServer {
+    server: Server;
+    url: string;
+    close(): Promise<void>;
+}
+export declare function startPlayground(options?: {
+    file?: string;
+    port?: number;
+    html?: string;
+}): Promise<PlaygroundServer>;

package/packages/cli/src/playground.js

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, realpath } from "node:fs/promises";
+import { createServer } from "node:http";
+import { basename, resolve, dirname, relative, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "animl/markup";
+import { readFileSync, realpathSync } from "node:fs";
+import { buildPlayground } from "animl/internal/tools/build-playground.js";
+const revision = (s) => createHash("sha256").update(s).digest("hex");
+async function startPlayground(options = {}) {
+  const file = options.file ? resolve(options.file) : new URL("../../../examples/bell.animl", import.meta.url);
+  if (options.file && !options.file.endsWith(".animl"))
+    throw new Error("playground opens .animl files");
+  await readFile(file, "utf8");
+  const html = options.html ?? await buildPlayground();
+  const writable = !!options.file;
+  const sourceFile = typeof file === "string" ? file : fileURLToPath(file);
+  const project = await realpath(process.cwd());
+  let origin = "";
+  let writing = Promise.resolve();
+  const server = createServer(async (req, res) => {
+    const send = (status, body) => {
+      res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store"
+      });
+      res.end(JSON.stringify(body));
+    };
+    if (req.headers.host !== origin.slice("http://".length) || req.headers.origin && req.headers.origin !== origin) {
+      send(403, { error: "local-origin", message: "Use the playground\u2019s loopback URL." });
+      return;
+    }
+    try {
+      if (req.url === "/" && req.method === "GET") {
+        res.writeHead(200, {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff"
+        });
+        res.end(html);
+        return;
+      }
+      if (req.url === "/api/compile" && req.method === "POST") {
+        let body2 = "";
+        for await (const chunk of req) {
+          body2 += chunk;
+          if (Buffer.byteLength(body2) > 1024 * 1024) {
+            send(413, { error: "limit-exceeded" });
+            return;
+          }
+        }
+        const result = compile(body2, {
+          file: sourceFile,
+          resolve: (path) => {
+            const target = realpathSync(resolve(dirname(sourceFile), path));
+            const rel = relative(project, target);
+            if (rel === ".." || rel.startsWith("../") || isAbsolute(rel))
+              throw Error("outside project directory");
+            return readFileSync(target, "utf8");
+          }
+        });
+        send(200, { doc: result.doc, text: result.text, diagnostics: result.diagnostics });
+        return;
+      }
+      if (req.url !== "/api/file") {
+        send(404, { error: "not-found" });
+        return;
+      }
+      if (req.method === "GET") {
+        const source2 = await readFile(file, "utf8");
+        send(200, {
+          source: source2,
+          revision: revision(source2),
+          writable,
+          name: options.file ? basename(options.file) : "examples/bell.animl"
+        });
+        return;
+      }
+      if (req.method !== "PUT") {
+        res.setHeader("Allow", "GET, PUT");
+        send(405, { error: "method" });
+        return;
+      }
+      if (!writable) {
+        send(403, { error: "read-only", message: "The built-in example is read-only." });
+        return;
+      }
+      if (!req.headers["content-type"]?.startsWith("application/json")) {
+        send(415, { error: "content-type" });
+        return;
+      }
+      req.setEncoding("utf8");
+      let body = "";
+      let size = 0;
+      for await (const chunk of req) {
+        size += Buffer.byteLength(chunk);
+        if (size > 2 * 1024 * 1024) {
+          send(413, { error: "limit-exceeded" });
+          return;
+        }
+        body += chunk;
+      }
+      const data = JSON.parse(body);
+      if (!data || typeof data !== "object" || typeof data.source !== "string" || Buffer.byteLength(data.source) > 1024 * 1024 || typeof data.revision !== "string") {
+        send(400, { error: "invalid-save" });
+        return;
+      }
+      const source = data.source;
+      const save = writing.then(async () => {
+        const current = await readFile(file, "utf8");
+        if (data.revision !== revision(current)) {
+          send(409, {
+            error: "file-changed",
+            message: "The file changed on disk. Reload before saving."
+          });
+          return;
+        }
+        await writeFile(file, source, "utf8");
+        send(200, { revision: revision(source) });
+      });
+      writing = save.catch(() => {
+      });
+      await save;
+    } catch (e) {
+      send(e instanceof SyntaxError ? 400 : 500, {
+        error: "file-io",
+        message: e.message
+      });
+    }
+  });
+  let port = options.port ?? 4519;
+  if (!Number.isInteger(port) || port < 0 || port > 65535)
+    throw new Error("--port takes an integer from 0 to 65535");
+  for (; ; ) {
+    try {
+      await new Promise((ok, fail) => {
+        const error = (e) => {
+          server.off("listening", ready);
+          fail(e);
+        };
+        const ready = () => {
+          server.off("error", error);
+          ok();
+        };
+        server.once("error", error);
+        server.once("listening", ready);
+        server.listen(port, "127.0.0.1");
+      });
+      break;
+    } catch (e) {
+      if (e.code !== "EADDRINUSE" || port === 0 || port >= 65535)
+        throw e;
+      port++;
+    }
+  }
+  const address = server.address();
+  origin = `http://127.0.0.1:${typeof address === "object" && address ? address.port : port}`;
+  return {
+    server,
+    url: origin,
+    close: () => new Promise((ok, fail) => {
+      server.close((e) => e ? fail(e) : ok());
+      server.closeIdleConnections();
+    })
+  };
+}
+export {
+  startPlayground
+};

package/packages/cli/src/project.d.ts

@@ -0,0 +1,15 @@
+export interface Project {
+    file: string;
+    entry?: string;
+    exclude?: string[];
+    constants?: Record<string, string | number | boolean>;
+    sources?: string[];
+    presets?: Record<string, Record<string, string | number | boolean | string[]>>;
+    out?: string;
+}
+export declare function projectError(pointer: string, message: string): Error;
+export declare function findProject(cwd?: string): Project | undefined;
+/** Sources are ordinary AniML libraries, imported using their declared names as namespaces. */
+export declare function projectSource(file: string): string;
+/** Replace placeholders in parsed attribute ranges only; preserve XML escaping and source layout. */
+export declare function substituteConstants(text: string, constants: Project['constants']): string;