@canonical/pragma-cli 0.27.1-experimental.0 → 0.29.0

package/src/domains/shared/packages.ts

@@ -1,126 +1,27 @@
 /**
- * Design system package registry and resolution.
+ * Default semantic graph package registry.
  *
- * Resolves semantic packages from three sources (in priority order):
- * 1. file:// local path (development)
- * 2. git ref cache (shared/CI)
- * 3. require.resolve from node_modules (npm fallback)
+ * Defines the default graph packages loaded when no config overrides
+ * are present. Each entry is a git ref pointing to the canonical
+ * repository so `pragma update-refs` fetches data out of the box.
  *
- * The package list itself is configurable via pragma.config.json `packages`
- * field. When absent, the hardcoded DEFAULT_PACKAGES are used.
+ * Resolution is handled by the loader chain in `loaders/`.
  */
 
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname } from "node:path";
-import type { PackageRef } from "../refs/operations/parseRef.js";
-import { gitCacheDir } from "../refs/operations/paths.js";
-
-const require = createRequire(import.meta.url);
-
-// ---------------------------------------------------------------------------
-// Default package registry (used when config.packages is absent)
-// ---------------------------------------------------------------------------
-
-/** Default semantic packages loaded when no config overrides are present. */
-export const DEFAULT_PACKAGES: readonly string[] = [
-  "@canonical/design-system",
-  "@canonical/anatomy-dsl",
-  "@canonical/code-standards",
-  "@canonical/pragma-cli",
+import type { RawPackageEntry } from "../refs/operations/parseRef.js";
+
+/** Default semantic graph packages loaded when no config overrides are present. */
+export const DEFAULT_PACKAGES: readonly RawPackageEntry[] = [
+  {
+    name: "@canonical/design-system",
+    source: "git+https://github.com/canonical/design-system.git#main",
+  },
+  {
+    name: "@canonical/anatomy-dsl",
+    source: "git+https://github.com/canonical/anatomy-dsl.git#main",
+  },
+  {
+    name: "@canonical/code-standards",
+    source: "git+https://github.com/canonical/web-code-standards.git#main",
+  },
 ];
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ResolvedPackage {
-  /** npm package name. */
-  readonly pkg: string;
-  /** Absolute path to the package root. */
-  readonly dir: string;
-}
-
-// ---------------------------------------------------------------------------
-// Resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve packages to filesystem directories.
- *
- * When `refs` is provided, each PackageRef is resolved according to its kind.
- * When `refs` is omitted, the DEFAULT_PACKAGES are resolved via require.resolve.
- *
- * @param refs - Parsed package references (from config merge). Omit for defaults.
- * @returns Array of resolved packages with absolute directory paths.
- */
-export function resolvePackages(
-  refs?: ReadonlyArray<PackageRef>,
-): ResolvedPackage[] {
-  if (!refs) {
-    return resolveNpmPackages(DEFAULT_PACKAGES);
-  }
-
-  const resolved: ResolvedPackage[] = [];
-
-  for (const ref of refs) {
-    switch (ref.kind) {
-      case "file": {
-        if (!existsSync(ref.path)) {
-          console.warn(
-            `pragma: package "${ref.pkg}" points to ${ref.path} which does not exist. Check the path or remove the file:// source.`,
-          );
-          break;
-        }
-        resolved.push({ pkg: ref.pkg, dir: ref.path });
-        break;
-      }
-
-      case "git": {
-        const cacheDir = gitCacheDir(ref.pkg, ref.ref);
-        if (existsSync(cacheDir)) {
-          resolved.push({ pkg: ref.pkg, dir: cacheDir });
-          break;
-        }
-        // Cache miss — warn and fall through to npm
-        console.warn(
-          `pragma: git ref for "${ref.pkg}" not cached. Run "pragma update-refs" to fetch it.`,
-        );
-        resolveNpmFallback(ref.pkg, resolved);
-        break;
-      }
-
-      case "npm": {
-        resolveNpmFallback(ref.pkg, resolved);
-        break;
-      }
-    }
-  }
-
-  return resolved;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Resolve a list of package names via require.resolve. */
-function resolveNpmPackages(pkgs: readonly string[]): ResolvedPackage[] {
-  const resolved: ResolvedPackage[] = [];
-  for (const pkg of pkgs) {
-    resolveNpmFallback(pkg, resolved);
-  }
-  return resolved;
-}
-
-/** Try to resolve a single package via require.resolve, push if found. */
-function resolveNpmFallback(pkg: string, resolved: ResolvedPackage[]): void {
-  try {
-    resolved.push({
-      pkg,
-      dir: dirname(require.resolve(`${pkg}/package.json`)),
-    });
-  } catch {
-    // package not installed — skip
-  }
-}

package/src/domains/shared/pickRandom.ts

@@ -0,0 +1,22 @@
+/**
+ * Pick `count` random items from an array without replacement.
+ *
+ * Uses Fisher-Yates partial shuffle for uniform distribution.
+ * Returns at most `arr.length` items if count exceeds the array size.
+ */
+export default function pickRandom<T>(
+  arr: readonly T[],
+  count: number,
+): readonly T[] {
+  const n = Math.min(count, arr.length);
+  if (n === 0) return [];
+
+  const copy = [...arr];
+  for (let i = 0; i < n; i++) {
+    const j = i + Math.floor(Math.random() * (copy.length - i));
+    const tmp = copy[i];
+    copy[i] = copy[j] as T;
+    copy[j] = tmp as T;
+  }
+  return copy.slice(0, n);
+}

package/src/domains/shared/runtime.ts

@@ -48,16 +48,18 @@ export async function bootPragma(options?: {
     ? undefined
     : mergeAndParseRefs(config.packages);
 
-  const store = await bootStore({
+  const { store, packages } = await bootStore({
     cwd,
     sources: options?.sources,
     refs,
+    trace: config.trace,
   });
 
   return {
     store,
     config,
     cwd,
+    packages,
     dispose: () => store.dispose(),
   };
 }
@@ -92,8 +94,9 @@ function mergeAndParseRefs(
   const merged = new Map<string, RawPackageEntry>();
 
   // Start with defaults (lowest priority)
-  for (const pkg of DEFAULT_PACKAGES) {
-    merged.set(pkg, pkg);
+  for (const entry of DEFAULT_PACKAGES) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    merged.set(name, entry);
   }
 
   // Global overrides defaults

package/src/domains/shared/sampleFormatters.ts

@@ -0,0 +1,47 @@
+/**
+ * Factory for sample command formatters.
+ *
+ * Every domain's sample formatter follows the same pattern: a count
+ * header, then each item rendered via the domain's lookup formatter.
+ * This factory eliminates the duplication.
+ */
+
+import type { Formatters } from "./formatters.js";
+import type { SampleOutput } from "./types/index.js";
+
+/**
+ * Create a three-mode formatter for `pragma <domain> sample`.
+ *
+ * @param domain - plural domain label for the header (e.g. "standards")
+ * @param renderItem - renders one item; receives the item and the mode
+ */
+export default function createSampleFormatters<T>(
+  domain: string,
+  renderItem: (item: T, mode: "plain" | "llm") => string,
+): Formatters<SampleOutput<T>> {
+  return {
+    plain(output) {
+      const header = `Showing ${output.samples.length} of ${output.totalCount} ${domain}\n`;
+      const items = output.samples.map((item) => renderItem(item, "plain"));
+      return header + items.join("\n\n");
+    },
+
+    llm(output) {
+      const header = `Showing ${output.samples.length} of ${output.totalCount} ${domain}\n`;
+      const items = output.samples.map((item) => renderItem(item, "llm"));
+      return header + items.join("\n\n");
+    },
+
+    json(output) {
+      return JSON.stringify(
+        {
+          samples: output.samples,
+          totalCount: output.totalCount,
+          nextSteps: output.nextSteps,
+        },
+        null,
+        2,
+      );
+    },
+  };
+}

package/src/domains/shared/semanticPackage.ts

@@ -0,0 +1,96 @@
+/**
+ * Semantic package contracts and resolution orchestrator.
+ *
+ * A semantic package is a resolved graph dependency containing TTL
+ * definitions, instance data, and skills. Three loaders produce the
+ * same `SemanticPackage` shape — local (file/npm), git cache, and
+ * bundled (compiled binary). The orchestrator tries each loader in
+ * precedence order: local > git > bundled.
+ */
+
+import type { PackageRef } from "../refs/operations/parseRef.js";
+
+// ---------------------------------------------------------------------------
+// Contracts
+// ---------------------------------------------------------------------------
+
+/** A single TTL file's content with provenance annotation. */
+export interface GraphContent {
+  /** Original file path or virtual identifier (for provenance/debugging). */
+  readonly path: string;
+  /** TTL content string. */
+  readonly content: string;
+  /** RDF serialization format. */
+  readonly format: "turtle";
+}
+
+/** A discovered skill directory with its filesystem path. */
+export interface SkillEntry {
+  /** Absolute path to the skill directory (must exist on disk for symlinking). */
+  readonly dir: string;
+  /** Skill folder name (e.g. "anatomy-author"). */
+  readonly folderName: string;
+}
+
+/** A resolved graph package. All loaders produce this uniform shape. */
+export interface SemanticPackage {
+  /** npm package name (e.g. "@canonical/design-system"). */
+  readonly name: string;
+  /** Version string from package.json. */
+  readonly version: string;
+  /** How this package was resolved. */
+  readonly source: "local" | "git" | "bundled";
+  /** TTL graph content to load into the ke store. */
+  readonly graphs: GraphContent[];
+  /** Skills available in this package. */
+  readonly skills: SkillEntry[];
+}
+
+/**
+ * Resolves a package reference to a SemanticPackage.
+ * Returns `undefined` if this loader cannot resolve the given ref.
+ * May be async (e.g. BundledLoader reads blob content asynchronously).
+ */
+export interface PackageLoader {
+  /** Loader identity for diagnostics. */
+  readonly name: "local" | "git" | "bundled";
+  /** Attempt to resolve a package reference. */
+  resolve(
+    ref: PackageRef,
+  ): SemanticPackage | undefined | Promise<SemanticPackage | undefined>;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve package references to semantic packages using a loader chain.
+ *
+ * Tries each loader in array order for each ref. The first loader that
+ * returns a result wins — subsequent loaders are skipped for that ref.
+ * Refs that no loader can resolve are silently dropped.
+ *
+ * @param refs - Parsed package references from config merge.
+ * @param loaders - Loaders in precedence order (local > git > bundled).
+ * @returns Array of resolved semantic packages.
+ */
+export async function resolveSemanticPackages(
+  refs: ReadonlyArray<PackageRef>,
+  loaders: ReadonlyArray<PackageLoader>,
+): Promise<SemanticPackage[]> {
+  const packages: SemanticPackage[] = [];
+
+  for (const ref of refs) {
+    let resolved: SemanticPackage | undefined;
+    for (const loader of loaders) {
+      resolved = await loader.resolve(ref);
+      if (resolved) break;
+    }
+    if (resolved) {
+      packages.push(resolved);
+    }
+  }
+
+  return packages;
+}

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

@@ -0,0 +1,43 @@
+import type { Store } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import detectCrossDomain from "./detectCrossDomain.js";
+
+let store: Store;
+let cleanup: () => void;
+
+describe("detectCrossDomain", () => {
+  beforeAll(async () => {
+    const result = await createTestStore({ ttl: DS_ALL_TTL });
+    store = result.store;
+    cleanup = result.cleanup;
+  });
+
+  afterAll(() => {
+    cleanup();
+  });
+
+  it("T2-4: returns undefined when name is not in any domain", async () => {
+    const hint = await detectCrossDomain("nonexistent_xyz", "token", store);
+    expect(hint).toBeUndefined();
+  });
+
+  it("returns a hint with the correct shape", async () => {
+    const hint = await detectCrossDomain("Button", "modifier", store);
+    if (hint) {
+      expect(hint).toHaveProperty("domain");
+      expect(hint).toHaveProperty("entityType");
+      expect(hint).toHaveProperty("cli");
+      expect(hint).toHaveProperty("mcp");
+      expect(hint.mcp).toHaveProperty("tool");
+      expect(hint.mcp).toHaveProperty("params");
+    }
+  });
+
+  it("skips the current domain", async () => {
+    const hint = await detectCrossDomain("Button", "block", store);
+    if (hint) {
+      expect(hint.domain).not.toBe("block");
+    }
+  });
+});

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

@@ -0,0 +1,116 @@
+import type { SPARQL, Store } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { buildQuery } from "../buildQuery.js";
+import { P } from "../prefixes.js";
+
+/**
+ * Structured hint pointing the user/agent to the correct domain
+ * when a name exists in a different domain than the one queried.
+ */
+export interface CrossDomainHint {
+  /** Domain where the name was found (e.g., "modifier"). */
+  readonly domain: string;
+  /** Entity type label for messages (e.g., "modifier"). */
+  readonly entityType: string;
+  /** CLI recovery command. */
+  readonly cli: string;
+  /** MCP recovery tool + params. */
+  readonly mcp: { tool: string; params: Record<string, unknown> };
+}
+
+interface DomainSpec {
+  readonly domain: string;
+  readonly entityType: string;
+  readonly lookupTool: string;
+  readonly cliCommand: string;
+  readonly query: (name: string) => SPARQL<string>;
+}
+
+const DOMAIN_SPECS: readonly DomainSpec[] = [
+  {
+    domain: "block",
+    entityType: "block",
+    lookupTool: "block_lookup",
+    cliCommand: "pragma block lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+          ?s a ?type ; ${P.ds}name ?name .
+          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+  {
+    domain: "token",
+    entityType: "token",
+    lookupTool: "token_lookup",
+    cliCommand: "pragma token lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          ?s a ${P.ds}Token ; ${P.ds}tokenId ?id .
+          FILTER(LCASE(STR(?id)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+  {
+    domain: "modifier",
+    entityType: "modifier",
+    lookupTool: "modifier_lookup",
+    cliCommand: "pragma modifier lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          ?s a ${P.ds}ModifierFamily ; ${P.ds}name ?name .
+          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+  {
+    domain: "standard",
+    entityType: "standard",
+    lookupTool: "standard_lookup",
+    cliCommand: "pragma standard lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          ?s a ${P.cs}CodeStandard ; ${P.cs}name ?name .
+          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+];
+
+/**
+ * Check if a name exists in a domain other than the current one.
+ *
+ * Queries each domain in a deterministic order (block → token → modifier → standard)
+ * and returns the first match. Returns undefined if the name is not found anywhere.
+ *
+ * @param name - The user-supplied name.
+ * @param currentDomain - The domain the user queried (e.g., "token").
+ * @param store - ke store for cross-domain queries.
+ * @returns Hint pointing to the correct domain, or undefined.
+ */
+export default async function detectCrossDomain(
+  name: string,
+  currentDomain: string,
+  store: Store,
+): Promise<CrossDomainHint | undefined> {
+  for (const spec of DOMAIN_SPECS) {
+    if (spec.domain === currentDomain) continue;
+
+    const result = await store.query(spec.query(name));
+    if (result.type === "ask" && result.result) {
+      return {
+        domain: spec.domain,
+        entityType: spec.entityType,
+        cli: `${spec.cliCommand} ${name}`,
+        mcp: { tool: spec.lookupTool, params: { names: [name] } },
+      };
+    }
+  }
+
+  return undefined;
+}

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

@@ -0,0 +1,92 @@
+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

@@ -0,0 +1,51 @@
+/**
+ * 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 += ".*";
+    } else if (".+^${}()|[]\\".includes(char)) {
+      pattern += `\\${char}`;
+    } else {
+      pattern += char;
+    }
+  }
+  return new RegExp(`^${pattern}$`, "i");
+}