animl-cli 0.0.0-stage → 0.1.0

package/packages/cli/src/compare-png.js

@@ -0,0 +1,39 @@
+import { PNG } from "pngjs";
+function comparePNG(a, b, tolerance = 0, diff = false) {
+  const left = PNG.sync.read(a), right = PNG.sync.read(b);
+  if (left.width !== right.width || left.height !== right.height)
+    throw new Error("comparison image dimensions do not match");
+  return compareRGBA(left.data, right.data, left.width, left.height, tolerance, diff);
+}
+function compareRGBA(left, right, width, height, tolerance = 0, diff = false) {
+  if (left.length !== right.length || left.length !== width * height * 4)
+    throw Error("comparison raster dimensions do not match");
+  const image = new PNG({ width, height });
+  let differingPixels = 0, pixelsBeyondTolerance = 0, maxChannelDifference = 0, sum = 0;
+  for (let i = 0; i < left.length; i += 4) {
+    let delta = 0;
+    for (let c = 0; c < 4; c++) {
+      const d = Math.abs(left[i + c] - right[i + c]);
+      delta = Math.max(delta, d);
+      sum += d;
+    }
+    if (delta) differingPixels++;
+    if (delta > tolerance) pixelsBeyondTolerance++;
+    maxChannelDifference = Math.max(maxChannelDifference, delta);
+    image.data.set([delta, delta, delta, 255], i);
+  }
+  return {
+    width,
+    height,
+    differingPixels,
+    pixelsBeyondTolerance,
+    maxChannelDifference,
+    meanChannelDifference: sum / left.length,
+    pass: pixelsBeyondTolerance === 0,
+    ...diff ? { diff: PNG.sync.write(image) } : {}
+  };
+}
+export {
+  comparePNG,
+  compareRGBA
+};

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

@@ -0,0 +1,7 @@
+import { type Player } from 'animl';
+/** Our script for each Rive frame (Rive pointer (120, 120) px = glyph (10, 10)). */
+export declare const RIVE_STEPS: [frame: string, run: (p: Player) => void][];
+/** [frame, our SVG, mean absolute RGB difference 0..255 against Rive's PNG]. */
+export declare function compareWithRive(): Promise<[string, string, number][]>;
+/** A sheet: Rive on top, Anima below, one column per frame. */
+export declare function comparisonSheet(): Promise<string>;

package/packages/cli/src/compare.js

@@ -0,0 +1,84 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { load } from "animl";
+import { Resvg } from "@resvg/resvg-js";
+import { DARK, frameSVG, toPNG } from "./render.js";
+const ROOT = new URL("../../../", import.meta.url);
+const RIVE_STEPS = [
+  ["00-rest", (p) => p.step(1)],
+  [
+    "01-hover",
+    (p) => {
+      p.pointer("move", 10, 10);
+      p.step(0);
+      p.step(0.3);
+    }
+  ],
+  [
+    "02-ring-f3",
+    (p) => {
+      p.pointer("down", 10, 10);
+      p.step(0);
+      p.pointer("up", 10, 10);
+      p.step(0);
+      p.step(0.05);
+    }
+  ],
+  ["03-ring-f7", (p) => p.step(0.067)],
+  ["04-ring-f17", (p) => p.step(0.167)],
+  ["05-ring-f27", (p) => p.step(0.167)],
+  ["06-ring-f57", (p) => p.step(0.5)],
+  ["07-rested", (p) => p.step(0.7)],
+  [
+    "08-out",
+    (p) => {
+      p.pointer("leave");
+      p.step(0);
+      p.step(0.4);
+    }
+  ]
+];
+const SIZE = 240;
+async function compareWithRive() {
+  const { Player } = await import("animl");
+  const model = load(readFileSync(new URL("examples/bell.ani", ROOT), "utf8")).model;
+  const p = new Player(model);
+  const out = [];
+  for (const [frame, run] of RIVE_STEPS) {
+    run(p);
+    const svg = frameSVG(p, DARK, SIZE);
+    const ours = new Resvg(svg).render().pixels;
+    const rivePng = readFileSync(new URL(`fixtures/bell/rive-reference/frames/${frame}.png`, ROOT));
+    const theirs = new Resvg(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="${SIZE}" height="${SIZE}"><image width="${SIZE}" height="${SIZE}" href="data:image/png;base64,${rivePng.toString("base64")}"/></svg>`
+    ).render().pixels;
+    let sum = 0;
+    for (let i = 0; i < ours.length; i += 4)
+      for (let c = 0; c < 3; c++) sum += Math.abs(ours[i + c] - theirs[i + c]);
+    out.push([frame, svg, sum / (ours.length / 4 * 3)]);
+  }
+  return out;
+}
+async function comparisonSheet() {
+  const rows = await compareWithRive();
+  const w = SIZE * rows.length;
+  const cells = rows.map(([frame, svg, diff], k) => {
+    const png = readFileSync(
+      new URL(`fixtures/bell/rive-reference/frames/${frame}.png`, ROOT)
+    ).toString("base64");
+    const x = k * SIZE;
+    return `<image x="${x}" y="20" width="${SIZE}" height="${SIZE}" href="data:image/png;base64,${png}"/>` + svg.replace("<svg ", `<svg x="${x}" y="${SIZE + 20}" `) + `<text x="${x + SIZE / 2}" y="14" text-anchor="middle" font-family="monospace" font-size="12" fill="#f0eee6">${frame} \u0394${diff.toFixed(2)}</text>`;
+  });
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${2 * SIZE + 20}"><rect width="${w}" height="${2 * SIZE + 20}" fill="#000"/>${cells.join("")}</svg>`;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const out = process.argv[2] ?? "compare.png";
+  writeFileSync(out, toPNG(await comparisonSheet()));
+  for (const [f, , d] of await compareWithRive())
+    console.log(`${f}: mean |\u0394| ${d.toFixed(2)} / 255`);
+  console.log(`wrote ${out}`);
+}
+export {
+  RIVE_STEPS,
+  compareWithRive,
+  comparisonSheet
+};

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

@@ -0,0 +1,2 @@
+export type Shell = 'bash' | 'zsh' | 'fish';
+export declare function completion(shell: Shell): string;

package/packages/cli/src/completion.js

@@ -0,0 +1,153 @@
+import { COMMANDS, GLOBAL } from "./commands.js";
+function values(command) {
+  return [...command.subcommands?.map(({ name }) => name) ?? [], ...command.topics?.() ?? []];
+}
+function flags(command) {
+  return [...command.options, ...GLOBAL].flatMap((option) => [
+    `--${option.name}`,
+    ...option.short ? [`-${option.short}`] : []
+  ]);
+}
+function choiceCases(command) {
+  return [...command.options, ...GLOBAL].filter((option) => option.choices?.length).map(
+    (option) => `      --${option.name}${option.short ? `|-${option.short}` : ""}) COMPREPLY=( $(compgen -W '${option.choices.join(" ")}' -- "$cur") ); return ;;`
+  );
+}
+function bash() {
+  const commands = COMMANDS.flatMap((command) => [command.name, ...command.aliases ?? []]).join(
+    " "
+  );
+  const cases = COMMANDS.map((command) => {
+    const positional = values(command).join(" ");
+    return `    ${[command.name, ...command.aliases ?? []].join("|")})
+      case "$prev" in
+${choiceCases(command).join("\n")}
+      esac
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W '${flags(command).join(" ")}' -- "$cur") )
+      else
+        COMPREPLY=( $(compgen -W '${positional}' -- "$cur") )
+      fi
+      ;;`;
+  }).join("\n");
+  const globalChoices = GLOBAL.filter((option) => option.choices?.length).map(
+    (option) => `    --${option.name}) COMPREPLY=( $(compgen -W '${option.choices.join(" ")}' -- "$cur") ); return ;;`
+  ).join("\n");
+  const valued = [
+    ...new Set(
+      [...GLOBAL, ...COMMANDS.flatMap((command) => command.options)].filter((option) => option.value).flatMap((option) => [`--${option.name}`, ...option.short ? [`-${option.short}`] : []])
+    )
+  ].join("|");
+  return `# bash completion for anima
+_anima_completion() {
+  local cur prev cmd
+  cur="${"${COMP_WORDS[COMP_CWORD]}"}"
+  prev="${"${COMP_WORDS[COMP_CWORD-1]}"}"
+  # Global options with choices complete the same before or after the command.
+  case "$prev" in
+${globalChoices}
+  esac
+  # The command is the first word that is not a leading option or its value (anima --format json search \u2026).
+  local i word
+  cmd=""
+  for (( i = 1; i < COMP_CWORD; i++ )); do
+    word="${"${COMP_WORDS[i]}"}"
+    case "$word" in
+      ${valued}) (( i++ )) ;;
+      -*) ;;
+      *) cmd="$word"; break ;;
+    esac
+  done
+  if [[ -z "$cmd" ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $(compgen -W '--help --version --format' -- "$cur") )
+    else
+      COMPREPLY=( $(compgen -W '${commands}' -- "$cur") )
+    fi
+    return
+  fi
+  case "$cmd" in
+${cases}
+  esac
+}
+complete -F _anima_completion anima
+`;
+}
+function zshOption(option) {
+  const names = [`--${option.name}`, ...option.short ? [`-${option.short}`] : []].join(",");
+  const choice = option.choices?.length ? `:value:(${option.choices.join(" ")})` : option.value ? `:value:` : "";
+  return `'${names}[${option.summary.replaceAll("'", "'")}]${choice}'`;
+}
+function zsh() {
+  const commandRows = COMMANDS.flatMap(
+    (command) => [command.name, ...command.aliases ?? []].map(
+      (name) => `    '${name}:${command.summary.replaceAll("'", "")}'`
+    )
+  ).join("\n");
+  const cases = COMMANDS.map((command) => {
+    const args = [...command.options, ...GLOBAL].map((option) => `        ${zshOption(option)}`).join(" \\\n");
+    const topic = values(command);
+    const positional = topic.length ? ` \\
+        '*:value:(${topic.join(" ")})'` : "";
+    return `    ${[command.name, ...command.aliases ?? []].join("|")})
+      _arguments \\
+${args}${positional}
+      ;;`;
+  }).join("\n");
+  return `#compdef anima
+# zsh completion for anima
+_anima() {
+  local state command
+  _arguments '1:command:->command' '*::arg:->args'
+  case $state in
+    command)
+      _describe 'command' commands
+      ;;
+    args)
+      command=$words[2]
+      case $command in
+${cases}
+      esac
+      ;;
+  esac
+}
+local -a commands
+commands=(
+${commandRows}
+)
+_anima "$@"
+`;
+}
+function fishOption(command, option) {
+  const pieces = [
+    `complete -c anima -n '__fish_seen_subcommand_from ${[command.name, ...command.aliases ?? []].join(" ")}'`,
+    `-l ${option.name}`
+  ];
+  if (option.short) pieces.push(`-s ${option.short}`);
+  if (option.value) pieces.push("-r");
+  if (option.choices?.length) pieces.push(`-a '${option.choices.join(" ")}'`);
+  pieces.push(`-d '${option.summary.replaceAll("'", "\\'")}'`);
+  return pieces.join(" ");
+}
+function fish() {
+  const commandLines = COMMANDS.flatMap(
+    (command) => [command.name, ...command.aliases ?? []].map(
+      (name) => `complete -c anima -f -n '__fish_use_subcommand' -a '${name}' -d '${command.summary.replaceAll("'", "\\'")}'`
+    )
+  );
+  const detailLines = COMMANDS.flatMap((command) => [
+    ...[...command.options, ...GLOBAL].map((option) => fishOption(command, option)),
+    ...values(command).length ? [
+      `complete -c anima -f -n '__fish_seen_subcommand_from ${[command.name, ...command.aliases ?? []].join(" ")}' -a '${values(command).join(" ")}'`
+    ] : []
+  ]);
+  return ["# fish completion for anima", ...commandLines, ...detailLines, ""].join("\n");
+}
+function completion(shell) {
+  if (shell === "bash") return bash();
+  if (shell === "zsh") return zsh();
+  return fish();
+}
+export {
+  completion
+};

package/packages/cli/src/discover/api.d.ts

@@ -0,0 +1,55 @@
+export type EntryKind = 'feature' | 'type' | 'field' | 'element' | 'address' | 'ease' | 'function' | 'event' | 'script' | 'diagnostic' | 'doc' | 'example' | 'capability' | 'command';
+export interface Entry {
+    kind: EntryKind;
+    /** Canonical name, unique within its kind (`ik.bend`, `rigging.ik`, `examples/bell.animl`). */
+    name: string;
+    /** One line, plain text. */
+    summary: string;
+    /** Other spellings and concept words it answers to (AniML spelling, synonyms). */
+    aliases?: string[];
+    /** The `requires` feature that provides it, when there is one. */
+    feature?: string;
+    /** Parity row ids it implements or documents. */
+    rows?: string[];
+    /** Where to go next: `anima docs <topic>` topics. */
+    docs?: string[];
+    /** Example files (repo-relative) that use it. */
+    examples?: string[];
+    /** `anima schema <topic>` topic, when it has one. */
+    schema?: string;
+}
+export interface SearchOptions {
+    kinds?: EntryKind[];
+    /** Default 10. */
+    limit?: number;
+}
+export interface Hit {
+    entry: Entry;
+    /** Higher is better; only the order is meaningful. */
+    score: number;
+}
+/** Every entry, built from the sources of truth (cached per process). */
+export declare function index(): Entry[];
+/** Ranked search over `index()`; empty when nothing is relevant (never pads with noise). */
+export declare function search(query: string, options?: SearchOptions): Hit[];
+export interface FeatureInfo {
+    entry: Entry;
+    /** Everything the feature provides: types, fields, elements, addresses, events, eases, functions. */
+    provides: Entry[];
+    /** Features it needs loaded first (manifest `after`). */
+    after: string[];
+}
+/** All features, or one by name (`undefined` when unknown). */
+export declare function features(): FeatureInfo[];
+export declare function features(name: string): FeatureInfo | undefined;
+export interface ExampleInfo {
+    entry: Entry;
+    /** Repo-relative path. */
+    path: string;
+    /** Its `requires` features. */
+    requires: string[];
+}
+/** All examples, or those matching a feature, a file name or words (ranked). */
+export declare function examples(filter?: string): ExampleInfo[];
+/** Names close to `word` among `candidates` (D3 weighting), best first; empty below the cutoff. */
+export type Suggest = (word: string, candidates: readonly string[]) => string[];

package/packages/cli/src/discover/api.js

@@ -0,0 +1,185 @@
+import { buildIndex, featureAfter, exampleDetails, requirableFeatures } from "./build.js";
+import { suggest as suggestWords } from "../suggest.js";
+let CACHE;
+const idx = () => CACHE ??= buildIndex();
+function index() {
+  return idx();
+}
+const norm = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().replace(/[-_.<>/]+/g, " ").replace(/[^a-z0-9 ]+/g, " ").trim().replace(/\s+/g, " ");
+const STOP = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "my",
+  "it",
+  "i",
+  "on",
+  "to",
+  "of",
+  "for",
+  "with",
+  "when",
+  "is",
+  "does",
+  "and",
+  "or",
+  "change",
+  "make",
+  "add",
+  "use",
+  "create",
+  "show",
+  "do",
+  "get",
+  "want",
+  "how",
+  "please",
+  "can",
+  "draw",
+  "press",
+  "user"
+]);
+let SEARCH_DATA;
+function searchData() {
+  if (SEARCH_DATA) return SEARCH_DATA;
+  const entries = idx().map((entry) => {
+    const name = norm(entry.name);
+    const aliases = (entry.aliases || []).map(norm);
+    const summary = norm(entry.summary);
+    return {
+      entry,
+      name,
+      aliases,
+      summary,
+      nameTokens: name.split(" "),
+      aliasTokens: aliases.flatMap((alias) => alias.split(" ")),
+      summaryTokens: summary.split(" ")
+    };
+  });
+  const exact = /* @__PURE__ */ new Set();
+  const documentFrequency = /* @__PURE__ */ new Map();
+  for (const item of entries) {
+    for (const token of [...item.nameTokens, ...item.aliasTokens]) exact.add(token);
+    const seen = /* @__PURE__ */ new Set([...item.nameTokens, ...item.aliasTokens, ...item.summaryTokens]);
+    for (const token of seen) documentFrequency.set(token, (documentFrequency.get(token) || 0) + 1);
+  }
+  SEARCH_DATA = { entries, candidates: [...exact], exact, documentFrequency };
+  return SEARCH_DATA;
+}
+const KIND_BONUS = {
+  event: 65,
+  ease: 60,
+  function: 60,
+  address: 58,
+  field: 55,
+  script: 45,
+  element: 48,
+  type: 48,
+  feature: 45,
+  command: 45,
+  diagnostic: 40
+};
+function search(query, options = {}) {
+  const q = norm(query);
+  if (!q) return [];
+  const allTokens = q.split(" ");
+  const tokens = allTokens.filter((t) => !STOP.has(t));
+  if (!tokens.length) return [];
+  const data = searchData();
+  const entries = options.kinds ? data.entries.filter((item) => options.kinds.includes(item.entry.kind)) : data.entries;
+  const exactTokens = options.kinds ? new Set(entries.flatMap((item) => [...item.nameTokens, ...item.aliasTokens])) : data.exact;
+  const candidates = options.kinds ? [...exactTokens] : data.candidates;
+  const fuzzy = /* @__PURE__ */ new Map();
+  if (tokens.length === 1) {
+    const token = tokens[0];
+    if (token.length > 5 && !exactTokens.has(token))
+      fuzzy.set(token, new Set(suggestWords(token, candidates)));
+  }
+  const rarity = (token) => {
+    const frequency = data.documentFrequency.get(token) || 1;
+    return Math.min(2, 1 + Math.log((data.entries.length + 1) / (frequency + 1)) / 8);
+  };
+  const hits = [];
+  for (const item of entries) {
+    const e = item.entry, n = item.name, aliases = item.aliases, sum = item.summary, nameTokens = item.nameTokens, aliasTokens = item.aliasTokens, sumTokens = item.summaryTokens;
+    let score = 0, matched = 0;
+    if (n === q) {
+      score = 140;
+      matched = tokens.length;
+    } else if (aliases.includes(q)) {
+      score = 125;
+      matched = tokens.length;
+    } else if (sum === q || sum.startsWith(`${q} `)) {
+      score = e.kind === "capability" ? sum === q ? 400 : 108 : 90;
+      matched = tokens.length;
+    } else
+      for (const t of tokens) {
+        let s = 0;
+        if (nameTokens.includes(t)) s = e.kind === "capability" ? 45 : 58;
+        else if (aliasTokens.includes(t))
+          s = e.kind === "capability" ? 55 : e.kind === "feature" ? 90 : 52;
+        else if (t.length >= 3 && n.includes(t)) s = 38;
+        else if (t.length >= 3 && aliases.some((a) => a.includes(t))) s = 34;
+        else if (sumTokens.includes(t)) s = 17;
+        else if (fuzzy.get(t)?.has(nameTokens.find((x) => fuzzy.get(t)?.has(x)) || "") || aliasTokens.some((x) => fuzzy.get(t)?.has(x)))
+          s = 22;
+        if (s) {
+          matched++;
+          score += s * rarity(t);
+        }
+      }
+    if (!matched) continue;
+    const phraseAlias = aliases.some((alias) => alias.includes(" ") && q.includes(alias));
+    if (phraseAlias) score += 100;
+    if ((e.kind === "type" || e.kind === "element" || e.kind === "feature") && nameTokens.length === 1 && tokens.includes(nameTokens[0]))
+      score += 60;
+    if (e.kind === "capability") {
+      const need = tokens.length >= 3 ? 2 : 1;
+      if (matched < need) continue;
+      score += matched * 5;
+    } else score += KIND_BONUS[e.kind] || (e.kind === "doc" ? 6 : 0);
+    if (score >= 22) hits.push({ entry: e, score });
+  }
+  return hits.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name)).slice(0, options.limit ?? 10);
+}
+function features(name) {
+  const after = featureAfter();
+  const entries = idx();
+  const provided = /* @__PURE__ */ new Map();
+  for (const e of entries)
+    if (e.feature) provided.set(e.feature, [...provided.get(e.feature) || [], e]);
+  const all = entries.filter((e) => e.kind === "feature").map((entry) => ({
+    entry,
+    provides: (provided.get(entry.name) || []).filter((e) => e !== entry),
+    after: after.get(entry.name) || []
+  }));
+  const requirable = requirableFeatures();
+  return name === void 0 ? all.filter((f) => requirable.has(f.entry.name)) : all.find((x) => x.entry.name === name || x.entry.aliases?.includes(name));
+}
+function examples(filter) {
+  const entries = idx();
+  const byPath = new Map(
+    entries.filter((e) => e.kind === "example").map((e) => [e.name, e])
+  );
+  const rows = exampleDetails().map((d) => ({
+    entry: byPath.get(d.path),
+    path: d.path,
+    requires: d.requires
+  }));
+  if (!filter) return rows;
+  const q = norm(filter);
+  return rows.map((x) => ({
+    x,
+    s: Math.max(
+      x.requires.some((r) => norm(r) === q) ? 100 : 0,
+      norm(x.path).includes(q) ? 70 : 0,
+      norm(x.entry.summary).includes(q) ? 40 : 0
+    )
+  })).filter((y) => y.s > 0).sort((a, b) => b.s - a.s).map((y) => y.x);
+}
+export {
+  examples,
+  features,
+  index,
+  search
+};

package/packages/cli/src/discover/build.d.ts

@@ -0,0 +1,14 @@
+import 'animl/all';
+import type { Entry } from './api.js';
+type ExampleRaw = {
+    path: string;
+    requires: string[];
+    names: string[];
+    summary: string;
+};
+export declare function buildIndex(): Entry[];
+export declare function featureAfter(): Map<string, string[]>;
+export declare function exampleDetails(): ExampleRaw[];
+/** Features a document can name in `requires` (modules with a core entry). */
+export declare function requirableFeatures(): Set<string>;
+export {};