@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,92 +0,0 @@
-import { describe, expect, it } from "vitest";
-import expandGlob, { isGlobPattern } from "./expandGlob.js";
-
-const standardNames = [
-  "react.component.props",
-  "react.component.structure.folder",
-  "react.component.barrel_exports",
-  "react.hooks.naming",
-  "css.selectors.namespace",
-  "css.selectors.specificity",
-  "css.component.encapsulation",
-  "git.branch.name",
-  "git.commit.message",
-];
-
-describe("expandGlob", () => {
-  it("T5-1: expands react.component.* to all matching entries", () => {
-    const result = expandGlob("react.component.*", standardNames);
-    expect(result).toContain("react.component.props");
-    expect(result).toContain("react.component.structure.folder");
-    expect(result).toContain("react.component.barrel_exports");
-    expect(result).not.toContain("react.hooks.naming");
-    expect(result).toHaveLength(3);
-  });
-
-  it("T5-2: expands css.* to all CSS entries", () => {
-    const result = expandGlob("css.*", standardNames);
-    expect(result).toHaveLength(3);
-    expect(result).toContain("css.selectors.namespace");
-  });
-
-  it("T5-3: expands prefix wildcard against plain names", () => {
-    const names = ["NavigationBar", "NavigationMenu", "Button"];
-    expect(expandGlob("Nav*", names)).toEqual([
-      "NavigationBar",
-      "NavigationMenu",
-    ]);
-  });
-
-  it("T5-4: full wildcard returns all candidates", () => {
-    expect(expandGlob("*", ["A", "B", "C"])).toEqual(["A", "B", "C"]);
-  });
-
-  it("T5-5: unmatched glob returns empty", () => {
-    expect(expandGlob("nonexistent.*", standardNames)).toEqual([]);
-  });
-
-  it("T5-6: non-glob name passes through unchanged", () => {
-    expect(expandGlob("Button", ["Button", "Card"])).toEqual(["Button"]);
-  });
-
-  it("T5-7: trailing dot treated as prefix glob", () => {
-    const withDot = expandGlob("react.component.", standardNames);
-    const withStar = expandGlob("react.component.*", standardNames);
-    expect(withDot).toEqual(withStar);
-  });
-
-  it("T5-8: suffix wildcard matches end of name", () => {
-    const result = expandGlob("*.props", [
-      "react.component.props",
-      "react.component.props.wrapper",
-      "css.selectors.namespace",
-    ]);
-    expect(result).toEqual(["react.component.props"]);
-  });
-
-  it("matches case-insensitively", () => {
-    expect(expandGlob("REACT.*", standardNames)).toHaveLength(4);
-  });
-});
-
-describe("isGlobPattern", () => {
-  it("T5-9: detects star pattern", () => {
-    expect(isGlobPattern("react.component.*")).toBe(true);
-  });
-
-  it("T5-10: detects prefix star", () => {
-    expect(isGlobPattern("Nav*")).toBe(true);
-  });
-
-  it("T5-11: detects trailing dot", () => {
-    expect(isGlobPattern("react.component.")).toBe(true);
-  });
-
-  it("T5-12: rejects plain name", () => {
-    expect(isGlobPattern("Button")).toBe(false);
-  });
-
-  it("T5-13: rejects empty string", () => {
-    expect(isGlobPattern("")).toBe(false);
-  });
-});

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

@@ -1,52 +0,0 @@
-/**
- * Expand a glob pattern against a list of known names.
- *
- * Supports:
- * - `*` anywhere: wildcard matching (`react.component.*`, `Nav*`, `*.props`)
- * - Trailing `.`: shorthand for `.*` (`react.component.` = `react.component.*`)
- *
- * Non-glob names are returned unchanged (wrapped in a single-element array)
- * so callers can pass the result directly to the lookup pipeline.
- *
- * @param pattern - User-supplied name, possibly containing glob characters.
- * @param candidates - All known names in the domain.
- * @returns Expanded concrete names, or empty array if no matches.
- */
-export default function expandGlob(
-  pattern: string,
-  candidates: readonly string[],
-): string[] {
-  if (!isGlobPattern(pattern)) {
-    return [pattern];
-  }
-
-  const normalized = pattern.endsWith(".") ? `${pattern}*` : pattern;
-  const regex = globToRegex(normalized);
-
-  return candidates.filter((name) => regex.test(name));
-}
-
-/**
- * Check whether a string contains glob meta-characters.
- *
- * A string is a glob pattern if it contains `*` or ends with `.` (trailing dot).
- */
-export function isGlobPattern(name: string): boolean {
-  if (name === "") return false;
-  return name.includes("*") || name.endsWith(".");
-}
-
-function globToRegex(glob: string): RegExp {
-  let pattern = "";
-  for (const char of glob) {
-    if (char === "*") {
-      pattern += ".*";
-      // biome-ignore lint/suspicious/noTemplateCurlyInString: regex meta-characters to escape, not a JS template
-    } else if (".+^${}()|[]\\".includes(char)) {
-      pattern += `\\${char}`;
-    } else {
-      pattern += char;
-    }
-  }
-  return new RegExp(`^${pattern}$`, "i");
-}

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

@@ -1,57 +0,0 @@
-import type { Store } from "@canonical/ke";
-import expandGlob, { isGlobPattern } from "./expandGlob.js";
-import type { Domain } from "./listDomainNames.js";
-import listDomainNames from "./listDomainNames.js";
-
-interface ExpandedQueries {
-  /** Concrete names to pass to lookupMany. */
-  readonly names: string[];
-  /** Errors for glob patterns that matched nothing. */
-  readonly globErrors: readonly {
-    query: string;
-    code: string;
-    message: string;
-  }[];
-}
-
-/**
- * Partition lookup queries into concrete names and expanded globs.
- *
- * Literal names pass through unchanged. Glob patterns are expanded against
- * the domain's full name list. Globs that match nothing produce an
- * EMPTY_RESULTS error entry.
- */
-export default async function expandLookupQueries(
-  queries: readonly string[],
-  store: Store,
-  domain: Domain,
-): Promise<ExpandedQueries> {
-  const hasGlobs = queries.some(isGlobPattern);
-  if (!hasGlobs) {
-    return { names: [...queries], globErrors: [] };
-  }
-
-  const allNames = await listDomainNames(store, domain);
-  const names: string[] = [];
-  const globErrors: { query: string; code: string; message: string }[] = [];
-
-  for (const query of queries) {
-    if (!isGlobPattern(query)) {
-      names.push(query);
-      continue;
-    }
-
-    const expanded = expandGlob(query, allNames);
-    if (expanded.length === 0) {
-      globErrors.push({
-        query,
-        code: "EMPTY_RESULTS",
-        message: `No ${domain}s matching "${query}".`,
-      });
-    } else {
-      names.push(...expanded);
-    }
-  }
-
-  return { names, globErrors };
-}

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

@@ -1,7 +0,0 @@
-export type { CrossDomainHint } from "./detectCrossDomain.js";
-export { default as detectCrossDomain } from "./detectCrossDomain.js";
-export { default as expandGlob, isGlobPattern } from "./expandGlob.js";
-export { default as expandLookupQueries } from "./expandLookupQueries.js";
-export type { Domain } from "./listDomainNames.js";
-export { default as listDomainNames } from "./listDomainNames.js";
-export { default as suggestNames } from "./suggestNames.js";

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

@@ -1,61 +0,0 @@
-/**
- * Lightweight name queries for each domain.
- *
- * Used by suggestNames to fetch candidate lists when a lookup fails.
- * Each query returns only names (no detail) for minimal overhead.
- */
-
-import type { SPARQL, Store } from "@canonical/ke";
-import { buildQuery } from "../buildQuery.js";
-import { P } from "../prefixes.js";
-
-type Domain = "block" | "token" | "modifier" | "standard" | "ontology";
-
-const QUERIES: Record<Domain, SPARQL<string>> = {
-  block: buildQuery(`
-    SELECT DISTINCT ?name WHERE {
-      VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
-      ?s a ?type ; ${P.ds}name ?name .
-    }
-  `),
-  token: buildQuery(`
-    SELECT DISTINCT ?name WHERE {
-      ?s a ${P.ds}Token ; ${P.ds}tokenId ?name .
-    }
-  `),
-  modifier: buildQuery(`
-    SELECT DISTINCT ?name WHERE {
-      ?s a ${P.ds}ModifierFamily ; ${P.ds}name ?name .
-    }
-  `),
-  standard: buildQuery(`
-    SELECT DISTINCT ?name WHERE {
-      ?s a ${P.cs}CodeStandard ; ${P.cs}name ?name .
-    }
-  `),
-  ontology: buildQuery(`
-    SELECT DISTINCT ?name WHERE {
-      ?s a owl:Ontology .
-      BIND(STR(?s) AS ?name)
-    }
-  `),
-};
-
-/**
- * Fetch all entity names for a domain from the store.
- *
- * @note - This function is impure — it queries the ke store.
- */
-export default async function listDomainNames(
-  store: Store,
-  domain: Domain,
-): Promise<string[]> {
-  const query = QUERIES[domain];
-  const result = await store.query(query);
-  if (result.type !== "select") return [];
-  return result.bindings
-    .map((b) => b.name)
-    .filter((n): n is string => typeof n === "string" && n !== "");
-}
-
-export type { Domain };

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,46 +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,
-  OntologyClassFocus,
-  OntologyConstraint,
-  OntologyDetailed,
-  OntologyMeta,
-  OntologyProperty,
-  OntologyQueryHint,
-  OntologySummary,
-} from "./ontology.js";
-export type { PragmaRuntime } from "./runtime.js";
-export type { SampleOutput, SampleResult } from "./sample.js";
-export type { StandardRef } from "./standard.js";
-export type { TierEntry } from "./tier.js";
-export type {
-  TokenDetailed,
-  TokenDigest,
-  TokenRef,
-  TokenSummary,
-} from "./token.js";