design-constraint-validator 1.0.0

package/cli/result.js

@@ -0,0 +1,29 @@
+export function ok(value) { return { ok: true, value }; }
+export function err(error) { return { ok: false, error }; }
+export function wrap(fn) {
+    try {
+        return ok(fn());
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function wrapAsync(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export function map(r, f) {
+    return r.ok ? ok(f(r.value)) : r;
+}
+export function chain(r, f) {
+    return r.ok ? f(r.value) : r;
+}
+export function getOrThrow(r) {
+    if (!r.ok)
+        throw r.error; // consumer decides how to handle
+    return r.value;
+}

package/cli/result.ts

@@ -0,0 +1,27 @@
+export type Ok<T> = { ok: true; value: T };
+export type Err<E> = { ok: false; error: E };
+export type Result<T, E = Error> = Ok<T> | Err<E>;
+
+export function ok<T>(value: T): Ok<T> { return { ok: true, value }; }
+export function err<E>(error: E): Err<E> { return { ok: false, error }; }
+
+export function wrap<T>(fn: () => T): Result<T, unknown> {
+  try { return ok(fn()); } catch (e) { return err(e); }
+}
+
+export async function wrapAsync<T>(fn: () => Promise<T>): Promise<Result<T, unknown>> {
+  try { return ok(await fn()); } catch (e) { return err(e); }
+}
+
+export function map<T, U, E>(r: Result<T, E>, f: (v: T) => U): Result<U, E> {
+  return r.ok ? ok(f(r.value)) : r;
+}
+
+export function chain<T, U, E>(r: Result<T, E>, f: (v: T) => Result<U, E>): Result<U, E> {
+  return r.ok ? f(r.value) : r;
+}
+
+export function getOrThrow<T, E>(r: Result<T, E>): T {
+  if (!r.ok) throw r.error as any; // consumer decides how to handle
+  return r.value;
+}

package/cli/run.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env ts-node
+export {};
+//# sourceMappingURL=run.d.ts.map

package/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["run.ts"],"names":[],"mappings":""}

package/cli/run.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env ts-node
+import { readFileSync } from "node:fs";
+import { flattenTokens } from "../core/flatten.js";
+import { Engine } from "../core/engine.js";
+import { WcagContrastPlugin } from "../core/constraints/wcag.js";
+const tokensRoot = JSON.parse(readFileSync("tokens/tokens.example.json", "utf8"));
+const { flat, edges } = flattenTokens(tokensRoot);
+// Build init values map
+const init = {};
+for (const [id, t] of Object.entries(flat))
+    init[id] = t.value;
+// Engine + plugin (example pairs; adjust IDs to your roles)
+const engine = new Engine(init, edges).use(WcagContrastPlugin([
+    { fg: "color.role.text.default", bg: "color.role.surface.default", min: 4.5, where: "Body text" },
+    { fg: "color.role.accent.default", bg: "color.role.surface.default", min: 3.0, where: "Accent on surface" }
+]));
+// Apply overrides if present
+let overrides = {};
+try {
+    const maybe = JSON.parse(readFileSync("tokens/overrides/local.json", "utf8"));
+    overrides = maybe.overrides ?? maybe;
+}
+catch {
+    // File doesn't exist or invalid JSON, use empty overrides
+}
+import { patchToJson } from "../adapters/json.js";
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+const argvPromise = yargs(hideBin(process.argv)).option('json', {
+    alias: 'j',
+    type: 'boolean',
+    description: 'Output result as JSON'
+}).argv;
+// ... existing code ...
+(async () => {
+    const argv = await argvPromise;
+    for (const [id, val] of Object.entries(overrides)) {
+        const res = engine.commit(id, val);
+        if (argv.json) {
+            const jsonOutput = patchToJson(res);
+            console.log(JSON.stringify(jsonOutput, null, 2));
+        }
+        else {
+            console.log(JSON.stringify(res, null, 2));
+        }
+    }
+})();

package/cli/run.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env ts-node
+import { readFileSync } from "node:fs";
+import { flattenTokens } from "../core/flatten.js";
+import { Engine } from "../core/engine.js";
+import { WcagContrastPlugin } from "../core/constraints/wcag.js";
+
+const tokensRoot = JSON.parse(readFileSync("tokens/tokens.example.json","utf8"));
+const { flat, edges } = flattenTokens(tokensRoot);
+
+// Build init values map
+const init: Record<string, string|number> = {};
+for (const [id, t] of Object.entries(flat)) init[id] = t.value;
+
+// Engine + plugin (example pairs; adjust IDs to your roles)
+const engine = new Engine(init, edges).use(
+  WcagContrastPlugin([
+    { fg: "color.role.text.default", bg: "color.role.surface.default", min: 4.5, where: "Body text" },
+    { fg: "color.role.accent.default", bg: "color.role.surface.default", min: 3.0, where: "Accent on surface" }
+  ])
+);
+
+// Apply overrides if present
+let overrides: Record<string, string|number> = {};
+try {
+  const maybe = JSON.parse(readFileSync("tokens/overrides/local.json","utf8"));
+  overrides = maybe.overrides ?? maybe;
+} catch {
+  // File doesn't exist or invalid JSON, use empty overrides
+}
+
+import { patchToJson } from "../adapters/json.js";
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+
+const argvPromise = yargs(hideBin(process.argv)).option('json', {
+  alias: 'j',
+  type: 'boolean',
+  description: 'Output result as JSON'
+}).argv;
+
+// ... existing code ...
+
+(async () => {
+  const argv = await argvPromise;
+  for (const [id, val] of Object.entries(overrides)) {
+    const res = engine.commit(id, val);
+    if (argv.json) {
+      const jsonOutput = patchToJson(res);
+      console.log(JSON.stringify(jsonOutput, null, 2));
+    } else {
+      console.log(JSON.stringify(res, null, 2));
+    }
+  }
+})();

package/cli/smoke-test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=smoke-test.d.ts.map

package/cli/smoke-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoke-test.d.ts","sourceRoot":"","sources":["smoke-test.ts"],"names":[],"mappings":""}

package/cli/smoke-test.js

@@ -0,0 +1,33 @@
+// cli/smoke-test.ts
+import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { flattenTokens } from "../core/flatten.js";
+import { Engine } from "../core/engine.js";
+import { WcagContrastPlugin } from "../core/constraints/wcag.js";
+import { patchToCss } from "../adapters/css.js";
+// 1. Flatten tokens
+const tokensRoot = JSON.parse(readFileSync("tokens/tokens.example.json", "utf8"));
+const { flat, edges } = flattenTokens(tokensRoot);
+// 2. Build engine
+const init = {};
+for (const [id, t] of Object.entries(flat))
+    init[id] = t.value;
+const engine = new Engine(init, edges).use(WcagContrastPlugin([
+    { fg: "color.role.text.default", bg: "color.role.bg.surface", min: 4.5, where: "Body text" },
+]));
+// 3. Commit one change
+const overrideId = "color.palette.brand.600";
+const overrideValue = "#FF00FF"; // A loud magenta to make it obvious
+const result = engine.commit(overrideId, overrideValue);
+console.log("--- Smoke Test ---");
+console.log(`Committed: ${overrideId} = ${overrideValue}`);
+console.log("Affected:", result.affected);
+console.log("Issues:", result.issues);
+console.log("Patch:", result.patch);
+// 4. Write overrides.css using the adapter
+const css = patchToCss(result.patch);
+const outFile = "css/overrides.css";
+mkdirSync(dirname(outFile), { recursive: true });
+writeFileSync(outFile, css);
+console.log(`\nWrote ${outFile}`);
+console.log("--- End Smoke Test ---");

package/cli/smoke-test.ts

@@ -0,0 +1,40 @@
+// cli/smoke-test.ts
+import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { flattenTokens } from "../core/flatten.js";
+import { Engine } from "../core/engine.js";
+import { WcagContrastPlugin } from "../core/constraints/wcag.js";
+import { patchToCss } from "../adapters/css.js";
+
+// 1. Flatten tokens
+const tokensRoot = JSON.parse(readFileSync("tokens/tokens.example.json", "utf8"));
+const { flat, edges } = flattenTokens(tokensRoot);
+
+// 2. Build engine
+const init: Record<string, string | number> = {};
+for (const [id, t] of Object.entries(flat)) init[id] = t.value;
+
+const engine = new Engine(init, edges).use(
+  WcagContrastPlugin([
+    { fg: "color.role.text.default", bg: "color.role.bg.surface", min: 4.5, where: "Body text" },
+  ])
+);
+
+// 3. Commit one change
+const overrideId = "color.palette.brand.600";
+const overrideValue = "#FF00FF"; // A loud magenta to make it obvious
+const result = engine.commit(overrideId, overrideValue);
+
+console.log("--- Smoke Test ---");
+console.log(`Committed: ${overrideId} = ${overrideValue}`);
+console.log("Affected:", result.affected);
+console.log("Issues:", result.issues);
+console.log("Patch:", result.patch);
+
+// 4. Write overrides.css using the adapter
+const css = patchToCss(result.patch);
+const outFile = "css/overrides.css";
+mkdirSync(dirname(outFile), { recursive: true });
+writeFileSync(outFile, css);
+console.log(`\nWrote ${outFile}`);
+console.log("--- End Smoke Test ---");

package/cli/types.d.ts

@@ -0,0 +1,86 @@
+import type { TokenValue } from '../core/flatten.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import type { DcvConfigParsed } from './config-schema.js';
+export interface WcagRuleConfig {
+    foreground: string;
+    background: string;
+    ratio?: number;
+    description?: string;
+}
+export type DcvConfig = DcvConfigParsed;
+export type ValuesPatch = Record<string, TokenValue>;
+export interface OverridesLeaf {
+    $value?: string | number | null;
+}
+export type OverridesTree = {
+    [k: string]: OverridesTree | OverridesLeaf;
+} & OverridesLeaf;
+export interface GlobalOptions {
+    tokens?: string;
+    config?: string;
+    verbose?: boolean;
+    quiet?: boolean;
+    breakpoint?: 'sm' | 'md' | 'lg';
+    allBreakpoints?: boolean;
+}
+export interface SetOptions extends GlobalOptions {
+    expressions: string[];
+    output?: string;
+    format?: 'json' | 'css' | 'js';
+    theme?: string;
+    write?: boolean;
+    json?: string;
+    unset?: string[];
+}
+export interface BuildOptions extends GlobalOptions {
+    output?: string;
+    format?: 'css' | 'json' | 'js';
+    watch?: boolean;
+    theme?: string;
+    mapper?: string;
+    dryRun?: boolean;
+    allFormats?: boolean;
+}
+export interface ValidateOptions extends GlobalOptions {
+    strict?: boolean;
+    constraints?: string[];
+    perf?: boolean;
+    budgetTotalMs?: number;
+    budgetPerBpMs?: number;
+}
+export interface GraphOptions extends GlobalOptions {
+    output?: string;
+    format?: 'dot' | 'mermaid' | 'json' | 'svg' | 'png';
+    imageFrom?: 'mermaid' | 'dot';
+    filter?: string;
+    hasse?: string;
+    filterPrefix?: string;
+    excludePrefix?: string;
+    onlyViolations?: boolean;
+    highlightViolations?: boolean;
+    violationColor?: string;
+    labelViolations?: boolean;
+    labelTruncate?: number;
+    minSeverity?: 'warn' | 'error';
+    focus?: string;
+    radius?: number;
+    tokens?: string;
+}
+export interface WhyOptions extends GlobalOptions {
+    tokenId: string;
+    format?: 'json' | 'table';
+}
+export interface PatchOptions extends GlobalOptions {
+    overrides?: string;
+    output?: string;
+    format?: 'json' | 'css' | 'js';
+    tokens?: string;
+}
+export interface PatchApplyOptions extends GlobalOptions {
+    patch: string;
+    output?: string;
+    tokens?: string;
+    dryRun?: boolean;
+}
+export type { Breakpoint };
+//# sourceMappingURL=types.d.ts.map

package/cli/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"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"}

package/cli/types.js

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

package/cli/types.ts

@@ -0,0 +1,78 @@
+import type { TokenValue } from '../core/flatten.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import type { DcvConfigParsed } from './config-schema.js';
+
+export interface WcagRuleConfig { foreground: string; background: string; ratio?: number; description?: string }
+export type DcvConfig = DcvConfigParsed;
+export type ValuesPatch = Record<string, TokenValue>;
+export interface OverridesLeaf { $value?: string | number | null }
+export type OverridesTree = { [k: string]: OverridesTree | OverridesLeaf } & OverridesLeaf;
+
+export interface GlobalOptions {
+  tokens?: string;
+  config?: string;
+  verbose?: boolean;
+  quiet?: boolean;
+  breakpoint?: 'sm' | 'md' | 'lg';
+  allBreakpoints?: boolean;
+}
+export interface SetOptions extends GlobalOptions {
+  expressions: string[];
+  output?: string;
+  format?: 'json' | 'css' | 'js';
+  theme?: string;
+  write?: boolean;
+  json?: string;
+  unset?: string[];
+}
+export interface BuildOptions extends GlobalOptions {
+  output?: string;
+  format?: 'css' | 'json' | 'js';
+  watch?: boolean;
+  theme?: string;
+  mapper?: string;
+  dryRun?: boolean;
+  allFormats?: boolean;
+}
+export interface ValidateOptions extends GlobalOptions {
+  strict?: boolean;
+  constraints?: string[];
+  perf?: boolean;
+  budgetTotalMs?: number;
+  budgetPerBpMs?: number;
+}
+export interface GraphOptions extends GlobalOptions {
+  output?: string;
+  format?: 'dot' | 'mermaid' | 'json' | 'svg' | 'png';
+  imageFrom?: 'mermaid' | 'dot';
+  filter?: string;
+  hasse?: string;
+  filterPrefix?: string;
+  excludePrefix?: string;
+  onlyViolations?: boolean;
+  highlightViolations?: boolean;
+  violationColor?: string;
+  labelViolations?: boolean;
+  labelTruncate?: number;
+  minSeverity?: 'warn' | 'error';
+  focus?: string;
+  radius?: number;
+  tokens?: string;
+}
+export interface WhyOptions extends GlobalOptions {
+  tokenId: string;
+  format?: 'json' | 'table';
+}
+export interface PatchOptions extends GlobalOptions {
+  overrides?: string; // path to flat overrides json or inline json
+  output?: string;
+  format?: 'json' | 'css' | 'js';
+  tokens?: string;
+}
+export interface PatchApplyOptions extends GlobalOptions {
+  patch: string; // path or inline patch JSON
+  output?: string; // where to write updated tokens (if omitted, prints result)
+  tokens?: string; // source tokens file (baseline)
+  dryRun?: boolean; // if true do not write
+}
+export type { Breakpoint };

package/core/breakpoints.d.ts

@@ -0,0 +1,12 @@
+import type { TokenNode } from "./flatten.js";
+export type Breakpoint = "sm" | "md" | "lg";
+export declare function parseBreakpoints(argv: string[]): Breakpoint[];
+export declare function loadJsonSafe<T = unknown>(path: string): T | null;
+export declare function loadOrders(axis: string, bp?: Breakpoint): [string, "<=" | ">=", string][];
+export declare function mergeTokens(base: unknown, overlay: unknown): TokenNode;
+/** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
+/**
+ * Load tokens with override precedence: base < local < breakpoint
+ */
+export declare function loadTokensWithBreakpoint(bp?: Breakpoint): TokenNode;
+//# sourceMappingURL=breakpoints.d.ts.map

package/core/breakpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAM7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAKnE"}

package/core/breakpoints.js

@@ -0,0 +1,48 @@
+// core/breakpoints.ts
+import fs from "node:fs";
+export function parseBreakpoints(argv) {
+    const allIdx = argv.indexOf("--all-breakpoints");
+    if (allIdx >= 0)
+        return ["sm", "md", "lg"];
+    const bpIdx = argv.indexOf("--breakpoint");
+    if (bpIdx >= 0)
+        return [argv[bpIdx + 1]];
+    return []; // no BP slicing requested
+}
+export function loadJsonSafe(path) {
+    try {
+        const data = JSON.parse(fs.readFileSync(path, "utf8"));
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadOrders(axis, bp) {
+    const withBp = bp ? loadJsonSafe(`themes/${axis}.${bp}.order.json`) : null;
+    if (withBp?.order)
+        return withBp.order;
+    const global = loadJsonSafe(`themes/${axis}.order.json`);
+    return (global?.order ?? []);
+}
+export function mergeTokens(base, overlay) {
+    if (!overlay)
+        return base;
+    if (typeof base !== "object" || base === null)
+        return overlay;
+    const out = Array.isArray(base) ? [...base] : { ...base };
+    for (const k of Object.keys(overlay)) {
+        out[k] = mergeTokens(base?.[k], overlay[k]);
+    }
+    return out;
+}
+/** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
+/**
+ * Load tokens with override precedence: base < local < breakpoint
+ */
+export function loadTokensWithBreakpoint(bp) {
+    const base = loadJsonSafe("tokens/tokens.example.json") ?? {};
+    const local = loadJsonSafe("tokens/overrides/local.json");
+    const ov = bp ? loadJsonSafe(`tokens/overrides/${bp}.json`) : null;
+    return mergeTokens(mergeTokens(base, local), ov);
+}

package/core/breakpoints.ts

@@ -0,0 +1,50 @@
+// core/breakpoints.ts
+import fs from "node:fs";
+import type { TokenNode } from "./flatten.js";
+
+export type Breakpoint = "sm" | "md" | "lg";
+
+export function parseBreakpoints(argv: string[]): Breakpoint[] {
+  const allIdx = argv.indexOf("--all-breakpoints");
+  if (allIdx >= 0) return ["sm", "md", "lg"];
+  const bpIdx = argv.indexOf("--breakpoint");
+  if (bpIdx >= 0) return [argv[bpIdx + 1] as Breakpoint];
+  return []; // no BP slicing requested
+}
+
+export function loadJsonSafe<T = unknown>(path: string): T | null {
+  try {
+    const data = JSON.parse(fs.readFileSync(path, "utf8"));
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export function loadOrders(axis: string, bp?: Breakpoint): [string, "<=" | ">=", string][] {
+  const withBp = bp ? loadJsonSafe<{ order: unknown[] }>(`themes/${axis}.${bp}.order.json`) : null;
+  if (withBp?.order) return withBp.order as [string, "<=" | ">=", string][];
+  const global = loadJsonSafe<{ order: unknown[] }>(`themes/${axis}.order.json`);
+  return (global?.order ?? []) as [string, "<=" | ">=", string][];
+}
+
+export function mergeTokens(base: unknown, overlay: unknown): TokenNode {
+  if (!overlay) return base as TokenNode;
+  if (typeof base !== "object" || base === null) return overlay as TokenNode;
+  const out = Array.isArray(base) ? [...base] : { ...base };
+  for (const k of Object.keys(overlay as Record<string, unknown>)) {
+    (out as Record<string, unknown>)[k] = mergeTokens((base as Record<string, unknown>)?.[k], (overlay as Record<string, unknown>)[k]);
+  }
+  return out as TokenNode;
+}
+
+/** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
+/**
+ * Load tokens with override precedence: base < local < breakpoint
+ */
+export function loadTokensWithBreakpoint(bp?: Breakpoint): TokenNode {
+  const base = loadJsonSafe<TokenNode>("tokens/tokens.example.json") ?? {};
+  const local = loadJsonSafe<TokenNode>("tokens/overrides/local.json");
+  const ov = bp ? loadJsonSafe<TokenNode>(`tokens/overrides/${bp}.json`) : null;
+  return mergeTokens(mergeTokens(base, local), ov);
+}

package/core/cli-format.d.ts

@@ -0,0 +1,8 @@
+export declare function pad(s: string, w: number): string;
+export declare function trunc(s: string, w: number): string;
+export declare function levenshtein(a: string, b: string): number;
+export declare function suggestIds(id: string, candidates: string[], k?: number): {
+    id: string;
+    d: number;
+}[];
+//# sourceMappingURL=cli-format.d.ts.map

package/core/cli-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-format.d.ts","sourceRoot":"","sources":["cli-format.ts"],"names":[],"mappings":"AACA,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,UAGvC;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,UAEzC;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAaxD;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC,SAAI,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAK/F"}

package/core/cli-format.js

@@ -0,0 +1,29 @@
+// core/cli-format.ts
+export function pad(s, w) {
+    if (s.length >= w)
+        return s;
+    return s + " ".repeat(w - s.length);
+}
+export function trunc(s, w) {
+    return s.length <= w ? s : s.slice(0, Math.max(0, w - 1)) + "…";
+}
+export function levenshtein(a, b) {
+    const dp = Array(b.length + 1).fill(0).map((_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = i - 1, cur = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = cur;
+            cur = Math.min(dp[j] + 1, cur + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            dp[j] = tmp;
+            prev = tmp;
+        }
+        dp[b.length] = cur;
+    }
+    return dp[b.length];
+}
+export function suggestIds(id, candidates, k = 3) {
+    return candidates
+        .map(c => ({ id: c, d: levenshtein(id, c) }))
+        .sort((x, y) => x.d - y.d)
+        .slice(0, k);
+}

package/core/cli-format.ts

@@ -0,0 +1,31 @@
+// core/cli-format.ts
+export function pad(s: string, w: number) {
+  if (s.length >= w) return s;
+  return s + " ".repeat(w - s.length);
+}
+
+export function trunc(s: string, w: number) {
+  return s.length <= w ? s : s.slice(0, Math.max(0, w - 1)) + "…";
+}
+
+export function levenshtein(a: string, b: string): number {
+  const dp = Array(b.length + 1).fill(0).map((_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = i - 1, cur = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = cur;
+      cur = Math.min(dp[j] + 1, cur + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      dp[j] = tmp;
+      prev = tmp;
+    }
+    dp[b.length] = cur;
+  }
+  return dp[b.length];
+}
+
+export function suggestIds(id: string, candidates: string[], k = 3): { id: string; d: number }[] {
+  return candidates
+    .map(c => ({ id: c, d: levenshtein(id, c) }))
+    .sort((x, y) => x.d - y.d)
+    .slice(0, k);
+}

package/core/color.d.ts

@@ -0,0 +1,14 @@
+export type RGBA = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+export declare function srgbToLin(c: number): number;
+export declare function linToSrgb(c: number): number;
+export declare function relativeLuminance(rgb: RGBA): number;
+export declare function contrastRatio(L1: number, L2: number): number;
+export declare function parseCssColor(input: string | undefined | null): RGBA | null;
+export declare function compositeOver(fg: RGBA, bg: RGBA): RGBA;
+export declare function isOpaque(c: RGBA): boolean;
+//# sourceMappingURL=color.d.ts.map

package/core/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["color.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,IAAI,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3C;AACD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3C;AAGD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAMnD;AACD,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAG5D;AAMD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CA4D3E;AAsCD,wBAAgB,aAAa,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,CAStD;AAGD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAyB"}