@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/block/operations/lookup.ts

@@ -1,446 +0,0 @@
-/**
- * Look up detailed information for a single block.
- *
- * Queries the base block, then resolves related modifiers, implementations,
- * tokens, anatomy nodes, blank-node properties, and recursive subcomponents.
- * The result is assembled into a {@link BlockDetailed} object.
- *
- * @param store - ke store to query
- * @param name - block name (e.g. "Button")
- * @param filters - tier and channel filter configuration
- * @returns fully populated block detail
- * @throws PragmaError.notFound if the block does not exist
- * @note Queries ke store
- */
-
-import type { Store, URI } from "@canonical/ke";
-import { escapeSparqlValue } from "@canonical/ke";
-import { PragmaError } from "#error";
-import resolveUri from "../../graph/helpers/resolveUri.js";
-import { buildQuery } from "../../shared/buildQuery.js";
-import extractLocalName from "../../shared/extractLocalName.js";
-import { buildFilters } from "../../shared/filters/buildFilters.js";
-import { P } from "../../shared/prefixes.js";
-import {
-  detectCrossDomain,
-  listDomainNames,
-  suggestNames,
-} from "../../shared/suggestions/index.js";
-import type {
-  BlockDetailed,
-  BlockSubcomponent,
-  FilterConfig,
-  StandardRef,
-  TokenRef,
-} from "../../shared/types/index.js";
-
-function normalizeBlockType(value: string | undefined): BlockDetailed["type"] {
-  const localName = extractLocalName(value ?? "").toLowerCase();
-
-  switch (localName) {
-    case "pattern":
-    case "layout":
-    case "subcomponent":
-      return localName;
-    default:
-      return "component";
-  }
-}
-
-export default async function lookupBlock(
-  store: Store,
-  nameOrUri: string,
-  filters: FilterConfig,
-): Promise<BlockDetailed[]> {
-  const filterClauses = buildFilters(filters);
-  const subjectClause = buildLookupSubjectClause(nameOrUri, store.prefixes);
-  const bindClause =
-    subjectClause === null ? "" : `BIND(${subjectClause} AS ?component)`;
-  const matchClause =
-    subjectClause === null
-      ? `?component ${P.ds}name ?name . FILTER(LCASE(STR(?name)) = ${escapeSparqlValue(nameOrUri.toLowerCase())})`
-      : "";
-
-  // Base query: find the block(s) — no LIMIT so ambiguous names return all matches
-  const baseResult = await store.query(
-    buildQuery(`
-      SELECT ?component ?name ?type ?tier ?summary ?whenToUse ?whenNotToUse ?guidelines ?anatomyDsl ?anatomyClassic ?figmaLink
-      WHERE {
-        VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
-        ${bindClause}
-        ?component a ?type ;
-                   ${P.ds}name ?name ;
-                   ${P.ds}tier ?tier .
-        ${matchClause}
-        OPTIONAL { ?component ${P.ds}summary ?summary }
-        OPTIONAL { ?component ${P.ds}whenToUse ?whenToUse }
-        OPTIONAL { ?component ${P.ds}whenNotToUse ?whenNotToUse }
-        OPTIONAL { ?component ${P.ds}guidelines ?guidelines }
-        OPTIONAL { ?component ${P.ds}anatomyDsl ?anatomyDsl }
-        OPTIONAL { ?component ${P.ds}anatomyClassic ?anatomyClassic }
-        OPTIONAL { ?component ${P.ds}figmaLink ?figmaLink }
-        ${filterClauses}
-      }
-    `),
-  );
-
-  if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
-    const candidates = await listDomainNames(store, "block");
-    const crossDomain = await detectCrossDomain(nameOrUri, "block", store);
-    throw PragmaError.notFound("block", nameOrUri, {
-      suggestions: suggestNames(nameOrUri, candidates),
-      recovery: {
-        message: "List available blocks.",
-        cli: "pragma block list",
-        mcp: { tool: "block_list" },
-      },
-      crossDomain: crossDomain ?? undefined,
-    });
-  }
-
-  const results: BlockDetailed[] = [];
-  for (const base of baseResult.bindings) {
-    results.push(await resolveBlockDetail(store, base, nameOrUri));
-  }
-  return results;
-}
-
-async function resolveBlockDetail(
-  store: Store,
-  base: Record<string, string>,
-  nameOrUri: string,
-): Promise<BlockDetailed> {
-  const componentUri = base.component;
-
-  // Modifier families with values
-  const modResult = await store.query(
-    buildQuery(`
-      SELECT ?family ?modName ?value
-      WHERE {
-        <${componentUri}> ${P.ds}hasModifierFamily ?family .
-        ?family ${P.ds}name ?modName .
-        OPTIONAL {
-          ?mod a ${P.ds}Modifier ;
-               ${P.ds}modifierFamily ?family ;
-               ${P.ds}name ?value .
-        }
-      }
-      ORDER BY ?modName ?value
-    `),
-  );
-
-  const modifierMap = new Map<string, string[]>();
-  const modifierFamilyUriMap = new Map<string, URI>();
-  if (modResult.type === "select") {
-    for (const b of modResult.bindings) {
-      const existing = modifierMap.get(b.modName ?? "") ?? [];
-      if (b.value) {
-        existing.push(b.value);
-      }
-      modifierMap.set(b.modName ?? "", existing);
-
-      if (b.modName && b.family) {
-        modifierFamilyUriMap.set(b.modName, b.family as URI);
-      }
-    }
-  }
-
-  const modifierFamilies = [...modifierMap.entries()].map(([name, values]) => ({
-    uri: modifierFamilyUriMap.get(name) ?? ("" as URI),
-    name,
-    values,
-  }));
-
-  // Implementations
-  const implResult = await store.query(
-    buildQuery(`
-      SELECT ?framework ?path
-      WHERE {
-        ?lib ${P.ds}hasImplementation ?impl .
-        ?impl ${P.ds}implementsBlock <${componentUri}> ;
-              ${P.ds}headLink ?path .
-        ?lib ${P.ds}platform ?framework .
-      }
-      ORDER BY ?framework
-    `),
-  );
-
-  const implementationPaths =
-    implResult.type === "select"
-      ? implResult.bindings.map((b) => ({
-          framework: b.framework ?? "",
-          path: b.path ?? "",
-        }))
-      : [];
-
-  // Build implementations summary (which frameworks are available)
-  const frameworkSet = new Set(implementationPaths.map((i) => i.framework));
-  const allFrameworks = await listAllFrameworks(store);
-  const implementations = allFrameworks.map((fw) => ({
-    framework: fw,
-    available: frameworkSet.has(fw),
-  }));
-
-  // Tokens
-  const tokenResult = await store.query(
-    buildQuery(`
-      SELECT ?token ?tokenId
-      WHERE {
-        <${componentUri}> ${P.ds}usesToken ?token .
-        ?token ${P.ds}tokenId ?tokenId .
-      }
-      ORDER BY ?tokenId
-    `),
-  );
-
-  const tokens: TokenRef[] =
-    tokenResult.type === "select"
-      ? tokenResult.bindings.map((b) => ({
-          uri: (b.token ?? "") as URI,
-          name: b.tokenId ?? "",
-        }))
-      : [];
-
-  // Anatomy nodes
-  const anatomyResult = await store.query(
-    buildQuery(`
-      SELECT DISTINCT ?node ?name
-      WHERE {
-        <${componentUri}> ${P.ds}anatomyNode ?node .
-        OPTIONAL { ?node ${P.ds}name ?name }
-      }
-      ORDER BY ?node
-    `),
-  );
-
-  const anatomyNodes =
-    anatomyResult.type === "select"
-      ? anatomyResult.bindings.map((binding) => ({
-          uri: (binding.node ?? "") as URI,
-          name: binding.name,
-        }))
-      : [];
-  const nodeCount = anatomyNodes.length;
-  const anatomy = buildAnatomyTree(anatomyNodes);
-
-  // Component properties from blank nodes
-  const propertiesResult = await store.query(
-    buildQuery(`
-      SELECT ?property ?name ?propertyType ?optional ?defaultValue ?constraints
-      WHERE {
-        <${componentUri}> ${P.ds}hasProperty ?property .
-        ?property ${P.ds}name ?name .
-        OPTIONAL { ?property ${P.ds}propertyType ?propertyType }
-        OPTIONAL { ?property ${P.ds}optional ?optional }
-        OPTIONAL { ?property ${P.ds}defaultValue ?defaultValue }
-        OPTIONAL { ?property ${P.ds}constraints ?constraints }
-      }
-      ORDER BY ?name
-    `),
-  );
-
-  const properties =
-    propertiesResult.type === "select"
-      ? propertiesResult.bindings.map((binding) => ({
-          name: binding.name ?? "",
-          propertyType: binding.propertyType ?? "",
-          optional: binding.optional === "true",
-          defaultValue: binding.defaultValue ?? null,
-          constraints: binding.constraints ?? null,
-        }))
-      : [];
-
-  // Recursive subcomponents
-  const subcomponentsResult = await store.query(
-    buildQuery(`
-      SELECT DISTINCT ?parent ?subcomponent ?name
-      WHERE {
-        <${componentUri}> (${P.ds}hasSubcomponent|^${P.ds}parentComponent)+ ?subcomponent .
-        ?parent (${P.ds}hasSubcomponent|^${P.ds}parentComponent) ?subcomponent .
-        ?subcomponent ${P.ds}name ?name .
-        FILTER(
-          ?parent = <${componentUri}> ||
-          EXISTS {
-            <${componentUri}> (${P.ds}hasSubcomponent|^${P.ds}parentComponent)+ ?parent
-          }
-        )
-      }
-      ORDER BY ?parent ?name
-    `),
-  );
-
-  const subcomponents =
-    subcomponentsResult.type === "select"
-      ? buildSubcomponentTree(
-          (componentUri ?? "") as URI,
-          subcomponentsResult.bindings,
-        )
-      : [];
-
-  // Standards (not linked directly to blocks in current ontology;
-  // will be populated via @follows in v0.3)
-  const standards: StandardRef[] = [];
-
-  return {
-    uri: (componentUri ?? "") as URI,
-    name: base.name ?? nameOrUri,
-    type: normalizeBlockType(base.type),
-    tier: extractLocalName(base.tier ?? ""),
-    modifiers: [...modifierMap.keys()],
-    implementations,
-    summary: base.summary ?? null,
-    nodeCount,
-    tokenCount: tokens.length,
-    whenToUse: base.whenToUse ?? null,
-    whenNotToUse: base.whenNotToUse ?? null,
-    guidelines: base.guidelines ?? null,
-    anatomyDsl: base.anatomyDsl ?? null,
-    anatomyClassic: base.anatomyClassic ?? null,
-    figmaLink: base.figmaLink ?? null,
-    anatomy,
-    modifierValues: [...modifierMap.entries()].map(([family, values]) => ({
-      family,
-      values,
-    })),
-    modifierFamilies,
-    properties,
-    subcomponents,
-    implementationPaths,
-    tokens,
-    standards,
-  };
-}
-
-function buildLookupSubjectClause(
-  query: string,
-  prefixes: Readonly<Record<string, string>>,
-): string | null {
-  if (!looksLikeUri(query)) {
-    return null;
-  }
-
-  return `<${resolveUri(query, prefixes)}>`;
-}
-
-function looksLikeUri(query: string): boolean {
-  return (
-    query.startsWith("http://") ||
-    query.startsWith("https://") ||
-    query.includes(":")
-  );
-}
-
-function buildAnatomyTree(
-  nodes: readonly { uri: URI; name?: string }[],
-): BlockDetailed["anatomy"] {
-  if (nodes.length === 0) {
-    return null;
-  }
-
-  const sorted = [...nodes].sort(
-    (left, right) => scoreAnatomyNode(right) - scoreAnatomyNode(left),
-  );
-  const [root, ...children] = sorted;
-  return {
-    root: {
-      name: root?.name ?? extractLocalName(root?.uri ?? "node"),
-      type: root?.name ? "named" : "anonymous",
-      children: children.map((node) => ({
-        name: node.name ?? extractLocalName(node.uri),
-        type: node.name ? "named" : "anonymous",
-        children: [],
-      })),
-    },
-  };
-}
-
-function scoreAnatomyNode(node: { uri: URI; name?: string }): number {
-  const uri = String(node.uri);
-  if (uri.endsWith(".root") || node.name === "button" || node.name === "card") {
-    return 2;
-  }
-  if (node.name) {
-    return 1;
-  }
-  return 0;
-}
-
-/**
- * Get all known implementation frameworks from the store.
- */
-async function listAllFrameworks(store: Store): Promise<string[]> {
-  const result = await store.query(
-    buildQuery(`
-      SELECT DISTINCT ?framework
-      WHERE {
-        ?lib a ${P.ds}ImplementationLibrary ;
-             ${P.ds}platform ?framework .
-      }
-      ORDER BY ?framework
-    `),
-  );
-
-  if (result.type !== "select") return [];
-  return result.bindings.map((b) => b.framework ?? "");
-}
-
-function buildSubcomponentTree(
-  rootUri: URI,
-  bindings: readonly Record<string, string>[],
-): readonly BlockSubcomponent[] {
-  const nodeMap = new Map<string, BlockSubcomponent>();
-  const childrenByParent = new Map<string, string[]>();
-
-  for (const binding of bindings) {
-    const uri = (binding.subcomponent ?? "") as URI;
-    const parent = (binding.parent ?? "") as URI;
-    if (!uri || !parent) {
-      continue;
-    }
-
-    nodeMap.set(String(uri), {
-      uri,
-      name: binding.name ?? extractLocalName(String(uri)),
-      children: [],
-    });
-
-    const siblings = childrenByParent.get(String(parent)) ?? [];
-    if (!siblings.includes(String(uri))) {
-      siblings.push(String(uri));
-      childrenByParent.set(String(parent), siblings);
-    }
-  }
-
-  return buildSubcomponentChildren(String(rootUri), childrenByParent, nodeMap);
-}
-
-function buildSubcomponentChildren(
-  parentUri: string,
-  childrenByParent: ReadonlyMap<string, readonly string[]>,
-  nodeMap: ReadonlyMap<string, BlockSubcomponent>,
-  visited = new Set<string>(),
-): readonly BlockSubcomponent[] {
-  const childUris = childrenByParent.get(parentUri) ?? [];
-
-  return childUris.flatMap((childUri) => {
-    const node = nodeMap.get(childUri);
-    if (!node || visited.has(childUri)) {
-      return [];
-    }
-
-    const nextVisited = new Set(visited);
-    nextVisited.add(childUri);
-
-    return [
-      {
-        ...node,
-        children: buildSubcomponentChildren(
-          childUri,
-          childrenByParent,
-          nodeMap,
-          nextVisited,
-        ),
-      },
-    ];
-  });
-}

package/src/domains/block/operations/sample.ts

@@ -1,41 +0,0 @@
-/**
- * Returns a small number of complete block instances as exemplars.
- *
- * Composes the existing list and lookup operations to avoid duplicating
- * any SPARQL logic. Agents use this to learn the data shape before querying.
- *
- * @param store - ke store to query
- * @param filters - tier and channel filter configuration
- * @param count - number of samples (clamped 1–5, default 2)
- * @returns sample result with detailed blocks and total count
- * @note Queries ke store
- */
-
-import type { Store } from "@canonical/ke";
-import pickRandom from "../../shared/pickRandom.js";
-import type {
-  BlockDetailed,
-  FilterConfig,
-  SampleResult,
-} from "../../shared/types/index.js";
-import listBlocks from "./list.js";
-import lookupBlock from "./lookup.js";
-
-export default async function sampleBlocks(
-  store: Store,
-  filters: FilterConfig,
-  count = 2,
-): Promise<SampleResult<BlockDetailed>> {
-  const clamped = Math.max(1, Math.min(5, count));
-  const all = await listBlocks(store, filters);
-  const selected = pickRandom(all, clamped);
-
-  const samples = await Promise.all(
-    selected.map(async (b) => {
-      const results = await lookupBlock(store, b.name, filters);
-      return results[0] as BlockDetailed;
-    }),
-  );
-
-  return { samples, totalCount: all.length };
-}

package/src/domains/block/orchestration/blockEmptyError.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { FilterConfig } from "../../shared/types/index.js";
-import blockEmptyError from "./blockEmptyError.js";
-
-const filters: FilterConfig = { tier: "Apps/WPE", channel: "normal" };
-
-describe("blockEmptyError", () => {
-  it("filter-narrowing: a tier was active → widen to all tiers", () => {
-    const err = blockEmptyError(filters, false);
-
-    expect(err.filters).toEqual({ tier: "Apps/WPE", channel: "normal" });
-    expect(err.recovery).toEqual({
-      message: "Widen the search to show all tiers.",
-      cli: "pragma block list --all-tiers",
-      mcp: { tool: "block_list", params: { allTiers: true } },
-    });
-  });
-
-  it("honest terminal: already at all-tiers → no recovery (no self-loop)", () => {
-    const err = blockEmptyError({ tier: undefined, channel: "normal" }, true);
-
-    // The widest tier query already returned empty; suggesting --all-tiers
-    // again would loop. recovery: undefined is the correct terminal state.
-    expect(err.recovery).toBeUndefined();
-  });
-});

package/src/domains/block/orchestration/blockEmptyError.ts

@@ -1,19 +0,0 @@
-import { PragmaError } from "#error";
-import { describeFilters } from "../../shared/filters/index.js";
-import type { FilterConfig } from "../../shared/types/index.js";
-
-export default function blockEmptyError(
-  filters: FilterConfig,
-  allTiers?: boolean,
-): PragmaError {
-  return PragmaError.emptyResults("block", {
-    filters: describeFilters(filters),
-    recovery: allTiers
-      ? undefined
-      : {
-          message: "Widen the search to show all tiers.",
-          cli: "pragma block list --all-tiers",
-          mcp: { tool: "block_list", params: { allTiers: true } },
-        },
-  });
-}

package/src/domains/block/orchestration/buildBlockFilters.ts

@@ -1,12 +0,0 @@
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { FilterConfig } from "../../shared/types/index.js";
-
-export default function buildBlockFilters(
-  rt: Pick<PragmaRuntime, "config">,
-  allTiers?: boolean,
-): FilterConfig {
-  return {
-    tier: allTiers ? undefined : rt.config.tier,
-    channel: rt.config.channel,
-  };
-}

package/src/domains/block/orchestration/enrichBlocks.ts

@@ -1,44 +0,0 @@
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import type {
-  BlockDetailed,
-  BlockSummary,
-  Disclosure,
-  FilterConfig,
-} from "../../shared/types/index.js";
-import { lookupBlock } from "../operations/index.js";
-import type { BlockListDigest } from "../types.js";
-
-export default async function enrichBlocks(
-  summaries: readonly BlockSummary[],
-  store: Pick<PragmaRuntime, "store">["store"],
-  filters: FilterConfig,
-  disclosure: Disclosure,
-): Promise<readonly (BlockListDigest | BlockDetailed)[]> {
-  // Look up by each summary's stable unique URI, not its display name: names
-  // recur across tiers/packages, so a by-name lookup returns every same-named
-  // block and taking the first match collapses distinct blocks onto one.
-  const nested = await Promise.all(
-    summaries.map((summary) => lookupBlock(store, summary.uri, filters)),
-  );
-  // lookupBlock returns BlockDetailed[] — the URI resolves to exactly one match
-  const details: BlockDetailed[] = nested.flatMap((matches) =>
-    matches.at(0) ? [matches[0] as BlockDetailed] : [],
-  );
-
-  if (disclosure.level === "detailed") {
-    return details;
-  }
-
-  return details.map((detail) => ({
-    uri: detail.uri,
-    name: detail.name,
-    type: detail.type,
-    tier: detail.tier,
-    summary: detail.summary,
-    modifiers: detail.modifiers,
-    implementations: detail.implementations,
-    nodeCount: detail.nodeCount,
-    tokenCount: detail.tokenCount,
-    implementationPaths: detail.implementationPaths,
-  }));
-}

package/src/domains/block/orchestration/index.ts

@@ -1,5 +0,0 @@
-export { default as blockEmptyError } from "./blockEmptyError.js";
-export { default as buildBlockFilters } from "./buildBlockFilters.js";
-export { default as enrichBlocks } from "./enrichBlocks.js";
-export { default as resolveBlockList } from "./resolveBlockList.js";
-export { default as resolveBlockLookup } from "./resolveBlockLookup.js";

package/src/domains/block/orchestration/resolveBlockList.ts

@@ -1,39 +0,0 @@
-import type { ListParams } from "../../shared/contracts.js";
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { Disclosure } from "../../shared/types/index.js";
-import { listBlocks } from "../operations/index.js";
-import type { BlockListContract } from "../types.js";
-import blockEmptyError from "./blockEmptyError.js";
-import buildBlockFilters from "./buildBlockFilters.js";
-import enrichBlocks from "./enrichBlocks.js";
-
-export default async function resolveBlockList(
-  rt: Pick<PragmaRuntime, "store" | "config">,
-  params: ListParams,
-): Promise<BlockListContract> {
-  const filters = buildBlockFilters(rt, params.allTiers);
-  const disclosure: Disclosure = params.detailed
-    ? { level: "detailed" }
-    : params.digest
-      ? { level: "digest" }
-      : { level: "summary" };
-  const summaries = await listBlocks(rt.store, filters);
-
-  if (summaries.length === 0) {
-    throw blockEmptyError(filters, params.allTiers);
-  }
-
-  const items =
-    disclosure.level === "summary"
-      ? summaries
-      : await enrichBlocks(summaries, rt.store, filters, disclosure);
-
-  return {
-    params,
-    result: {
-      items,
-      filters,
-      disclosure,
-    },
-  };
-}

package/src/domains/block/orchestration/resolveBlockLookup.ts

@@ -1,35 +0,0 @@
-import type { LookupContract, LookupResult } from "../../shared/contracts.js";
-import lookupMany from "../../shared/lookupMany.js";
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import { expandLookupQueries } from "../../shared/suggestions/index.js";
-import type { BlockDetailed, FilterConfig } from "../../shared/types/index.js";
-import { lookupBlock } from "../operations/index.js";
-
-export default async function resolveBlockLookup(
-  store: Pick<PragmaRuntime, "store">["store"],
-  queries: readonly string[],
-  filters: FilterConfig,
-): Promise<LookupContract<BlockDetailed>> {
-  const { names, globErrors } = await expandLookupQueries(
-    queries,
-    store,
-    "block",
-  );
-
-  const nested: LookupResult<BlockDetailed[]> =
-    names.length > 0
-      ? await lookupMany(names, (query) => lookupBlock(store, query, filters))
-      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
-
-  // lookupBlock returns BlockDetailed[] (multiple matches per name) — flatten
-  const result: LookupResult<BlockDetailed> = {
-    results: nested.results.flat(),
-    errors: [...nested.errors, ...globErrors],
-    meta: nested.meta ?? { internalErrorCount: 0 },
-  };
-
-  return {
-    params: { names: queries },
-    result,
-  };
-}