@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/shared/suggestions/suggestNames.test.ts

@@ -1,70 +0,0 @@
-import { describe, expect, it } from "vitest";
-import suggestNames from "./suggestNames.js";
-
-describe("suggestNames", () => {
-  it("T1-1: suggests edit-distance match for single-char typo", () => {
-    expect(suggestNames("Buton", ["Button", "Card", "Input"])).toEqual([
-      "Button",
-    ]);
-  });
-
-  it("T1-2: suggests dot-separated names with typo in last segment", () => {
-    const candidates = [
-      "react.component.props",
-      "react.component.props.wrapper",
-      "react.component.props.html_rendering",
-      "react.component.naming",
-      "css.selectors.namespace",
-    ];
-    const result = suggestNames("react.component.prosp", candidates);
-    expect(result.at(0)).toBe("react.component.props");
-    expect(result.length).toBeGreaterThanOrEqual(1);
-  });
-
-  it("T1-3: matches case-insensitively, preserves original casing", () => {
-    expect(
-      suggestNames("buton-background", ["Button-Background", "color-primary"]),
-    ).toEqual(["Button-Background"]);
-  });
-
-  it("T1-4: returns prefix matches ranked first", () => {
-    const result = suggestNames("Accordion", [
-      "AccordionItem",
-      "AccordionGroup",
-      "Button",
-    ]);
-    expect(result).toHaveLength(2);
-    expect(result).toContain("AccordionItem");
-    expect(result).toContain("AccordionGroup");
-  });
-
-  it("T1-5: returns empty for completely unrelated input", () => {
-    expect(suggestNames("zzzzz", ["Button", "Card", "Input"])).toEqual([]);
-  });
-
-  it("T1-6: returns empty for empty query", () => {
-    expect(suggestNames("", ["Button"])).toEqual([]);
-  });
-
-  it("T1-7: excludes exact matches", () => {
-    expect(suggestNames("Button", ["Button", "Card"])).toEqual([]);
-  });
-
-  it("T1-8: ranks multiple candidates by distance", () => {
-    const result = suggestNames("Buttn", ["Button", "Butter", "Bitten"]);
-    expect(result).toContain("Button");
-    expect(result).toContain("Butter");
-    expect(result.indexOf("Button")).toBeLessThan(result.indexOf("Butter"));
-  });
-
-  it("respects maxResults option", () => {
-    const candidates = Array.from({ length: 20 }, (_, i) => `Item${i}`);
-    const result = suggestNames("Item", candidates, { maxResults: 3 });
-    expect(result.length).toBeLessThanOrEqual(3);
-  });
-
-  it("respects threshold option", () => {
-    const result = suggestNames("Buton", ["Button"], { threshold: 0.05 });
-    expect(result).toEqual([]);
-  });
-});

package/src/domains/shared/suggestions/suggestNames.ts

@@ -1,130 +0,0 @@
-/**
- * Rank candidates by similarity to a failed lookup query.
- *
- * Returns up to {@link maxResults} names sorted by relevance:
- * 1. Prefix matches (query is a case-insensitive prefix of candidate)
- * 2. Edit-distance matches (Damerau-Levenshtein, normalized ≤ threshold)
- *
- * Exact matches are excluded — if the query exactly matches a candidate,
- * the caller should have found it and never reached this function.
- *
- * @param query - The user-supplied name that failed lookup.
- * @param candidates - All known names in the domain.
- * @param opts.maxResults - Max suggestions to return (default: 5).
- * @param opts.threshold - Max normalized edit distance (default: 0.4).
- * @returns Ranked suggestions with original casing preserved.
- */
-export default function suggestNames(
-  query: string,
-  candidates: readonly string[],
-  opts?: { maxResults?: number; threshold?: number },
-): string[] {
-  if (query === "") return [];
-
-  const maxResults = opts?.maxResults ?? 5;
-  const threshold = opts?.threshold ?? 0.4;
-  const queryLower = query.toLowerCase();
-
-  type Scored = { name: string; score: number };
-  const scored: Scored[] = [];
-
-  for (const candidate of candidates) {
-    const candidateLower = candidate.toLowerCase();
-
-    if (candidateLower === queryLower) continue;
-
-    if (candidateLower.startsWith(queryLower)) {
-      scored.push({ name: candidate, score: 0 });
-      continue;
-    }
-
-    const distance = damerauLevenshtein(queryLower, candidateLower);
-    const maxLen = Math.max(queryLower.length, candidateLower.length);
-    const normalized = maxLen === 0 ? 0 : distance / maxLen;
-
-    if (normalized <= threshold) {
-      scored.push({ name: candidate, score: normalized });
-    }
-  }
-
-  scored.sort((a, b) => a.score - b.score);
-  return scored.slice(0, maxResults).map((s) => s.name);
-}
-
-/**
- * Damerau-Levenshtein distance between two strings.
- *
- * Counts insertions, deletions, substitutions, and adjacent transpositions.
- */
-function damerauLevenshtein(a: string, b: string): number {
-  const lenA = a.length;
-  const lenB = b.length;
-
-  if (lenA === 0) return lenB;
-  if (lenB === 0) return lenA;
-
-  // Fully allocated (lenA + 1) × (lenB + 1) grid: every row/column index in
-  // [0, lenA] × [0, lenB] below is provably in bounds, so `row.at(j)` never
-  // yields undefined for the indices we read.
-  const matrix: number[][] = Array.from({ length: lenA + 1 }, () =>
-    Array.from<number>({ length: lenB + 1 }).fill(0),
-  );
-
-  for (let i = 0; i <= lenA; i++) {
-    getRow(matrix, i)[0] = i;
-  }
-  const firstRow = getRow(matrix, 0);
-  for (let j = 0; j <= lenB; j++) {
-    firstRow[j] = j;
-  }
-
-  for (let i = 1; i <= lenA; i++) {
-    const prevRow = getRow(matrix, i - 1);
-    const row = getRow(matrix, i);
-    for (let j = 1; j <= lenB; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-
-      row[j] = Math.min(
-        getCell(prevRow, j) + 1, // deletion
-        getCell(row, j - 1) + 1, // insertion
-        getCell(prevRow, j - 1) + cost, // substitution
-      );
-
-      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
-        const prevPrevRow = getRow(matrix, i - 2);
-        row[j] = Math.min(
-          getCell(row, j),
-          getCell(prevPrevRow, j - 2) + cost, // transposition
-        );
-      }
-    }
-  }
-
-  return getCell(getRow(matrix, lenA), lenB);
-}
-
-/**
- * Read a matrix row that is structurally guaranteed to exist.
- *
- * @throws if the row is missing, signalling a broken allocation invariant.
- */
-function getRow(matrix: number[][], index: number): number[] {
-  const row = matrix.at(index);
-  if (row === undefined) {
-    throw new Error(`matrix row ${index} is out of bounds`);
-  }
-  return row;
-}
-
-/**
- * Read a matrix cell that is structurally guaranteed to exist.
- *
- * @throws if the cell is missing, signalling a broken allocation invariant.
- */
-function getCell(row: number[], index: number): number {
-  const cell = row.at(index);
-  if (cell === undefined) {
-    throw new Error(`matrix cell ${index} is out of bounds`);
-  }
-  return cell;
-}

package/src/domains/shared/types/block.ts

@@ -1,107 +0,0 @@
-/** Block domain return types. */
-
-import type { URI } from "@canonical/ke";
-import type { StandardRef } from "./standard.js";
-import type { TokenRef } from "./token.js";
-
-/** Summary view of a design-system block (component, pattern, or primitive). */
-export interface BlockSummary {
-  /** Full RDF URI identifying this block in the ke store. */
-  readonly uri: URI;
-  /** Human-readable name (local name extracted from URI). */
-  readonly name: string;
-  /** Normalized ontology type for the block. */
-  readonly type: "component" | "pattern" | "layout" | "subcomponent";
-  /** Tier path this block belongs to (e.g., `"global"`, `"apps/lxd"`). */
-  readonly tier: string;
-  /** Active modifier names applied to this block. */
-  readonly modifiers: readonly string[];
-  /** Framework implementations declared for this block, with availability flags. */
-  readonly implementations: readonly {
-    framework: string;
-    available: boolean;
-  }[];
-  /** Number of anatomy nodes (DOM elements) in this block's anatomy tree. */
-  readonly nodeCount: number;
-  /** Number of design tokens referenced by this block. */
-  readonly tokenCount: number;
-}
-
-/** Digest view of a block for richer summary displays. */
-export interface BlockDigest extends BlockSummary {
-  /** Summary guidance when present in the graph. */
-  readonly summary: string | null;
-}
-
-/** Single node in a block's anatomy tree (recursive). */
-export interface AnatomyNode {
-  /** Element name (e.g., `"trigger"`, `"panel"`). */
-  readonly name: string;
-  /** Whether the node is explicitly named or inferred as anonymous. */
-  readonly type: "named" | "anonymous";
-  /** Child nodes nested under this element. */
-  readonly children: readonly AnatomyNode[];
-  /** Named slot this node exposes, if any. */
-  readonly slot?: string;
-}
-
-/** Wrapper around the root of a block's anatomy tree. */
-export interface AnatomyTree {
-  /** Top-level anatomy node from which all children descend. */
-  readonly root: AnatomyNode;
-}
-
-/** Recursive subcomponent entry used in block detailed views. */
-export interface BlockSubcomponent {
-  /** Full RDF URI of the subcomponent. */
-  readonly uri: URI;
-  /** Human-readable subcomponent name. */
-  readonly name: string;
-  /** Nested subcomponents owned by this subcomponent. */
-  readonly children: readonly BlockSubcomponent[];
-}
-
-/** Detailed view of a block, extending the digest with anatomy, tokens, and standards. */
-export interface BlockDetailed extends BlockDigest {
-  /** Guidance on when the block should be used. */
-  readonly whenToUse: string | null;
-  /** Guidance on when the block should not be used. */
-  readonly whenNotToUse: string | null;
-  /** Additional usage guidance. */
-  readonly guidelines: string | null;
-  /** YAML anatomy DSL payload when present. */
-  readonly anatomyDsl: string | null;
-  /** Legacy anatomy payload when present. */
-  readonly anatomyClassic: string | null;
-  /** Figma reference link when present. */
-  readonly figmaLink: string | null;
-  /** Full anatomy tree, or `null` if the block declares no anatomy. */
-  readonly anatomy: AnatomyTree | null;
-  /** Modifier families with their allowed values. */
-  readonly modifierValues: readonly {
-    family: string;
-    values: readonly string[];
-  }[];
-  /** Modifier families resolved as richer objects. */
-  readonly modifierFamilies: readonly {
-    uri: URI;
-    name: string;
-    values: readonly string[];
-  }[];
-  /** Property metadata resolved from blank nodes. */
-  readonly properties: readonly {
-    name: string;
-    propertyType: string;
-    optional: boolean;
-    defaultValue: string | null;
-    constraints: string | null;
-  }[];
-  /** Direct subcomponents of the block. */
-  readonly subcomponents: readonly BlockSubcomponent[];
-  /** File paths to framework-specific implementations. */
-  readonly implementationPaths: readonly { framework: string; path: string }[];
-  /** Design tokens referenced by this block. */
-  readonly tokens: readonly TokenRef[];
-  /** Standards (guidelines/rules) that apply to this block. */
-  readonly standards: readonly StandardRef[];
-}

package/src/domains/shared/types/common.ts

@@ -1,33 +0,0 @@
-/** Shared cross-domain types used by multiple domains and contracts. */
-
-/** Runtime filter settings controlling tier and channel visibility in queries. */
-export interface FilterConfig {
-  /** Active tier path, or `undefined` for all-tiers visibility. */
-  readonly tier: string | undefined;
-  /** Release channel determining which stability levels are visible. */
-  readonly channel: "normal" | "experimental" | "prerelease";
-}
-
-/**
- * Controls how much detail an operation returns.
- *
- * - `"summary"` — minimal fields (names and counts).
- * - `"digest"` — intermediate detail with optional example length cap.
- * - `"detailed"` — full content including code blocks and anatomy.
- */
-export type Disclosure =
-  | { readonly level: "summary" }
-  | { readonly level: "digest"; readonly maxExampleLength?: number }
-  | { readonly level: "detailed" };
-
-/** Outcome of a batch operation: successful results alongside per-item errors. */
-export interface BatchResult<T> {
-  /** Items that were processed successfully. */
-  readonly results: readonly T[];
-  /** Items that failed, each carrying the entity name, error code, and message. */
-  readonly errors: readonly {
-    name: string;
-    code: string;
-    message: string;
-  }[];
-}

package/src/domains/shared/types/graph.ts

@@ -1,17 +0,0 @@
-/** Graph inspection return types. */
-
-/** A predicate group from `graph inspect`: one predicate with all its objects. */
-export interface PredicateGroup {
-  /** RDF predicate URI (e.g., `"rdfs:label"`). */
-  readonly predicate: string;
-  /** Object values (URIs or literals) associated with this predicate. */
-  readonly objects: readonly string[];
-}
-
-/** Result of `graph inspect <uri>`: all triples where URI is subject. */
-export interface InspectResult {
-  /** The inspected subject URI. */
-  readonly uri: string;
-  /** Predicate groups aggregating all outgoing triples. */
-  readonly groups: readonly PredicateGroup[];
-}

package/src/domains/shared/types/index.ts

@@ -1,50 +0,0 @@
-/**
- * @module types
- *
- * Shared operation return types — contract between operations (D3) and
- * CLI/MCP adapters. Same data, different presentations.
- *
- * Per-domain files keep each concern isolated; this barrel re-exports
- * everything for consumers that import from `shared/types/index.js`.
- */
-
-export type {
-  AnatomyNode,
-  AnatomyTree,
-  BlockDetailed,
-  BlockDigest,
-  BlockSubcomponent,
-  BlockSummary,
-} from "./block.js";
-export type { BatchResult, Disclosure, FilterConfig } from "./common.js";
-export type { InspectResult, PredicateGroup } from "./graph.js";
-export type {
-  ModifierDetailed,
-  ModifierDigest,
-  ModifierFamily,
-  ModifierSummary,
-} from "./modifier.js";
-export type {
-  OntologyClass,
-  OntologyDetailed,
-  OntologyProperty,
-  OntologySummary,
-} from "./ontology.js";
-export type { PragmaRuntime } from "./runtime.js";
-export type { SampleOutput, SampleResult } from "./sample.js";
-export type {
-  CategorySummary,
-  CodeBlock,
-  StandardDetailed,
-  StandardDigest,
-  StandardListFilters,
-  StandardRef,
-  StandardSummary,
-} from "./standard.js";
-export type { TierEntry } from "./tier.js";
-export type {
-  TokenDetailed,
-  TokenDigest,
-  TokenRef,
-  TokenSummary,
-} from "./token.js";

package/src/domains/shared/types/modifier.ts

@@ -1,22 +0,0 @@
-/** Modifier domain return types. */
-
-import type { URI } from "@canonical/ke";
-
-/** A modifier family (e.g., "size", "variant") with its allowed values. */
-export interface ModifierFamily {
-  /** Full RDF URI identifying this modifier family. */
-  readonly uri: URI;
-  /** Human-readable family name. */
-  readonly name: string;
-  /** Allowed values within this family (e.g., `["small", "medium", "large"]`). */
-  readonly values: readonly string[];
-}
-
-/** Summary view of a modifier family. */
-export type ModifierSummary = ModifierFamily;
-
-/** Digest view of a modifier family for generic list contracts. */
-export type ModifierDigest = ModifierSummary;
-
-/** Detailed view of a modifier family. */
-export type ModifierDetailed = ModifierFamily;

package/src/domains/shared/types/ontology.ts

@@ -1,50 +0,0 @@
-/** Ontology inspection return types. */
-
-/** Summary of a loaded ontology namespace from `ontology list`. */
-export interface OntologySummary {
-  /** Short prefix alias (e.g., `"ds"`, `"cs"`). */
-  readonly prefix: string;
-  /** Full namespace URI the prefix expands to. */
-  readonly namespace: string;
-  /** Number of OWL/RDFS classes defined in this namespace. */
-  readonly classCount: number;
-  /** Number of properties (object + datatype) defined in this namespace. */
-  readonly propertyCount: number;
-  readonly anatomyCount: number;
-}
-
-/** A class in an ontology's class hierarchy. */
-export interface OntologyClass {
-  /** Full URI of the class. */
-  readonly uri: string;
-  /** Human-readable label (rdfs:label). */
-  readonly label: string;
-  /** URI of the direct superclass, if declared. */
-  readonly superclass?: string;
-}
-
-/** A property in an ontology namespace. */
-export interface OntologyProperty {
-  /** Full URI of the property. */
-  readonly uri: string;
-  /** Human-readable label (rdfs:label). */
-  readonly label: string;
-  /** URI of the domain class this property applies to, if declared. */
-  readonly domain?: string;
-  /** URI of the range class or datatype, if declared. */
-  readonly range?: string;
-  /** Whether this is an object property (links classes) or datatype property (links to literals). */
-  readonly type: "object" | "datatype";
-}
-
-/** Detailed view of a single ontology namespace from `ontology show`. */
-export interface OntologyDetailed {
-  /** Short prefix alias (e.g., `"ds"`). */
-  readonly prefix: string;
-  /** Full namespace URI the prefix expands to. */
-  readonly namespace: string;
-  /** All classes defined in this namespace. */
-  readonly classes: readonly OntologyClass[];
-  /** All properties defined in this namespace. */
-  readonly properties: readonly OntologyProperty[];
-}

package/src/domains/shared/types/runtime.ts

@@ -1,24 +0,0 @@
-/** Boot-time state shared by CLI, MCP, and completions server. */
-
-import type { Store } from "@canonical/ke";
-import type { PragmaConfig } from "#config";
-import type { SemanticPackage } from "../semanticPackage.js";
-
-/**
- * Boot-time state shared by CLI, MCP, and completions server.
- *
- * Five members:
- * - `store` — the ke triple store, loaded and ready for SPARQL queries.
- * - `config` — resolved pragma config (tier, channel).
- * - `cwd` — working directory used for config and source resolution.
- * - `packages` — resolved semantic packages (for diagnostics and skills).
- * - `dispose()` — tears down the store and frees WASM memory. Must be
- *   called exactly once; calling operations after dispose is undefined.
- */
-export interface PragmaRuntime {
-  readonly store: Store;
-  readonly config: PragmaConfig;
-  readonly cwd: string;
-  readonly packages: readonly SemanticPackage[];
-  dispose(): void;
-}

package/src/domains/shared/types/sample.ts

@@ -1,17 +0,0 @@
-/**
- * Shared types for sample operations across domains.
- *
- * Sample returns 1–5 complete instances as exemplars so agents
- * can learn actual data shapes before writing queries.
- */
-
-/** Raw result from a sample operation — instances plus total count. */
-export interface SampleResult<T> {
-  readonly samples: readonly T[];
-  readonly totalCount: number;
-}
-
-/** Full sample output including agent guidance. */
-export interface SampleOutput<T> extends SampleResult<T> {
-  readonly nextSteps: readonly string[];
-}

package/src/domains/shared/types/standard.ts

@@ -1,64 +0,0 @@
-/** Standard domain return types. */
-
-import type { URI } from "@canonical/ke";
-
-/** Summary view of a design-system standard (guideline or rule). */
-export interface StandardSummary {
-  /** Full RDF URI identifying this standard in the ke store. */
-  readonly uri: URI;
-  /** Human-readable name of the standard. */
-  readonly name: string;
-  /** Category grouping (e.g., `"accessibility"`, `"layout"`). */
-  readonly category: string;
-  /** Brief prose description of what the standard prescribes. */
-  readonly description: string;
-  /** URI of the parent standard this one extends, if any. */
-  readonly extends?: string;
-}
-
-/** Digest view of a standard for generic list contracts. */
-export type StandardDigest = StandardSummary;
-
-/** Fenced code block used in standard do/don't examples. */
-export interface CodeBlock {
-  /** Programming language identifier for syntax highlighting. */
-  readonly language: string;
-  /** Source code content of the example. */
-  readonly code: string;
-  /** Optional explanatory caption displayed alongside the code. */
-  readonly caption?: string;
-}
-
-/** Detailed view of a standard, extending the summary with code examples. */
-export interface StandardDetailed extends StandardSummary {
-  /** Positive examples demonstrating correct usage. */
-  readonly dos: readonly CodeBlock[];
-  /** Negative examples demonstrating incorrect usage. */
-  readonly donts: readonly CodeBlock[];
-}
-
-/** Summary of a standards category with its member count. */
-export interface CategorySummary {
-  /** Category name (e.g., `"accessibility"`, `"layout"`). */
-  readonly name: string;
-  /** Number of standards belonging to this category. */
-  readonly standardCount: number;
-}
-
-/** Optional filters for narrowing the standards list. */
-export interface StandardListFilters {
-  /** Restrict results to a single category name. */
-  readonly category?: string;
-  /** Free-text search term matched against standard names and descriptions. */
-  readonly search?: string;
-}
-
-/** Lightweight reference to a standard, used in block cross-references. */
-export interface StandardRef {
-  /** Human-readable standard name. */
-  readonly name: string;
-  /** Full RDF URI of the referenced standard. */
-  readonly uri: URI;
-  /** Category the referenced standard belongs to. */
-  readonly category: string;
-}

package/src/domains/shared/types/tier.ts

@@ -1,15 +0,0 @@
-/** Tier hierarchy return types. */
-
-import type { URI } from "@canonical/ke";
-
-/** A single entry in the tier hierarchy (e.g., `global`, `apps`, `apps/lxd`). */
-export interface TierEntry {
-  /** Full RDF URI identifying this tier in the ke store. */
-  readonly uri: URI;
-  /** Slash-separated tier path (e.g., `"apps/lxd"`). */
-  readonly path: string;
-  /** Path of the parent tier, if this is not the root. */
-  readonly parent?: string;
-  /** Nesting depth in the tier hierarchy (0 = root). */
-  readonly depth: number;
-}

package/src/domains/shared/types/token.ts

@@ -1,30 +0,0 @@
-/** Token domain return types. */
-
-import type { URI } from "@canonical/ke";
-
-/** Summary view of a design token. */
-export interface TokenSummary {
-  /** Full RDF URI identifying this token in the ke store. */
-  readonly uri: URI;
-  /** Human-readable token name (e.g., `"color-primary"`). */
-  readonly name: string;
-  /** Token category (e.g., `"color"`, `"spacing"`, `"typography"`). */
-  readonly category: string;
-}
-
-/** Digest view of a token for generic list contracts. */
-export type TokenDigest = TokenSummary;
-
-/** Detailed view of a token, extending the summary with per-theme resolved values. */
-export interface TokenDetailed extends TokenSummary {
-  /** Resolved values keyed by theme (e.g., `{ theme: "dark", value: "#fff" }`). */
-  readonly values: readonly { theme: string; value: string }[];
-}
-
-/** Lightweight reference to a token (name + URI), used in cross-references. */
-export interface TokenRef {
-  /** Human-readable token name. */
-  readonly name: string;
-  /** Full RDF URI of the referenced token. */
-  readonly uri: URI;
-}

package/src/domains/skill/commands/index.ts

@@ -1,4 +0,0 @@
-/** @module Re-exports skill command builders (`list`, `lookup`). */
-
-export { default as listCommand } from "./list.js";
-export { default as lookupCommand } from "./lookup.js";