@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/shared/bootStore.ts

@@ -1,171 +0,0 @@
-/**
- * Boot a ke store from resolved semantic packages.
- *
- * Resolves packages via the loader chain (local > git > bundled),
- * then loads all graph content into the store.
- *
- * @note Impure — reads filesystem, creates ke store.
- */
-
-import {
-  createStore,
-  definePlugin,
-  type Plugin,
-  type SourceSpec,
-  type Store,
-} from "@canonical/ke";
-import { PragmaError } from "../../error/index.js";
-import type { PackageRef } from "../refs/operations/parseRef.js";
-import { parsePackageEntry } from "../refs/operations/parseRef.js";
-import {
-  createBundledLoader,
-  createGitLoader,
-  createLocalLoader,
-} from "./loaders/index.js";
-import { DEFAULT_PACKAGES } from "./packages.js";
-import { resolvePrefixes } from "./prefixes.js";
-import type { GraphContent, SemanticPackage } from "./semanticPackage.js";
-import { resolveSemanticPackages } from "./semanticPackage.js";
-
-export interface BootStoreOptions {
-  /** Override sources (skip package resolution — for testing). */
-  sources?: SourceSpec[];
-  /** Working directory for resolving relative paths. */
-  cwd?: string;
-  /** Cache path for serialized store. */
-  cache?: string;
-  /** Parsed package references for loader-based resolution. */
-  refs?: ReadonlyArray<PackageRef>;
-  /** Enable query tracing (from config). Env var PRAGMA_TRACE=1 overrides. */
-  trace?: boolean;
-  /** Additional namespace prefixes merged over the built-in prefix map. */
-  prefixes?: Readonly<Record<string, string>>;
-}
-
-export interface BootResult {
-  /** The initialized ke store. */
-  readonly store: Store;
-  /** Resolved semantic packages (empty when sources override is used). */
-  readonly packages: readonly SemanticPackage[];
-}
-
-/**
- * Boot a ke store from configuration.
- *
- * When `sources` is provided, uses them directly (testing path).
- * Otherwise, resolves packages via the loader chain and loads their
- * graph content into the store.
- *
- * @throws PragmaError with code STORE_ERROR on failure.
- */
-export async function bootStore(
-  options: BootStoreOptions = {},
-): Promise<BootResult> {
-  try {
-    // Testing/programmatic override — use explicit sources. No packages are
-    // resolved, so the prefix map is the core base plus the transitional DS
-    // fallback and any caller override.
-    if (options.sources) {
-      const store = await createStore({
-        sources: options.sources,
-        prefixes: resolvePrefixes([], options.prefixes),
-        cache: options.cache,
-        cwd: options.cwd,
-      });
-      return { store, packages: [] };
-    }
-
-    // Resolve packages via loader chain: local > git > bundled
-    const refs =
-      options.refs && options.refs.length > 0
-        ? options.refs
-        : DEFAULT_PACKAGES.map(parsePackageEntry);
-    // Precedence: local (file:// + node_modules) > git cache > bundled
-    const loaders = [
-      createLocalLoader(),
-      createGitLoader(),
-      createBundledLoader(),
-    ];
-    const packages = await resolveSemanticPackages(refs, loaders);
-
-    // Collect all graph content from resolved packages
-    const allGraphs = packages.flatMap((pkg) => pkg.graphs);
-
-    // `Plugin<T>` is invariant in its API type and createStore expects
-    // `Plugin<void>[]`, so heterogeneous plugins (graph loader + trace) can only
-    // share an array via `any`. `unknown` does not satisfy `Plugin<void>`.
-    // biome-ignore lint/suspicious/noExplicitAny: intentional — see above
-    const plugins: Plugin<any>[] = [createGraphLoaderPlugin(allGraphs)];
-    const traceEnabled =
-      process.env.PRAGMA_TRACE === "1" || options.trace === true;
-    if (traceEnabled) {
-      const { createTracePlugin } = await import("../trace/tracePlugin.js");
-      const { traceDir } = await import("../refs/operations/paths.js");
-      plugins.push(createTracePlugin({ traceDir: traceDir() }));
-    }
-
-    // Merge every resolved package's declared prefixes (and the transitional
-    // DS fallback) over the generic core, then config overrides — so the
-    // store and every query see the packages' own namespaces.
-    const store = await createStore({
-      sources: [],
-      prefixes: resolvePrefixes(packages, options.prefixes),
-      cache: options.cache,
-      cwd: options.cwd,
-      plugins,
-    });
-
-    return { store, packages };
-  } catch (error) {
-    if (error instanceof PragmaError) throw error;
-    throw PragmaError.storeError(
-      error instanceof Error ? error.message : String(error),
-      {
-        recovery: {
-          message:
-            "If this is a parser error, check the TTL syntax of the source graphs " +
-            "(the message above names the line and column). Otherwise ensure design " +
-            "system packages are installed: bun add -D @canonical/design-system " +
-            "@canonical/code-standards @canonical/anatomy-dsl",
-        },
-      },
-    );
-  }
-}
-
-/**
- * Build the ke plugin that loads resolved graph content into the store.
- *
- * Each graph is loaded independently inside its own try/catch: a single
- * malformed TTL file (e.g. invalid Turtle emitted by an upstream authoring
- * tool) must not abort the entire boot and take the whole CLI down with it.
- * Failed graphs are skipped and surfaced as warnings, mirroring the
- * resilience the story loader already provides ("one bad file cannot break
- * boot"). A store built from N-1 good graphs is far more useful than a store
- * that refuses to boot because of one bad graph.
- *
- * @note Impure — writes warnings to stderr on parse failure.
- */
-export function createGraphLoaderPlugin(
-  graphs: readonly GraphContent[],
-): Plugin {
-  return definePlugin({
-    name: "pragma-graph-loader",
-    onReady(ctx) {
-      for (const graph of graphs) {
-        try {
-          ctx.load(graph.content, { format: graph.format });
-        } catch (error) {
-          const reason = error instanceof Error ? error.message : String(error);
-          // Name the offending file and the parse error, and point at the fix.
-          // The store still boots from the remaining graphs, so this is a
-          // warning, not a fatal error.
-          process.stderr.write(
-            `Warning: skipping malformed graph "${graph.path}" — ${reason}. ` +
-              "Check the TTL syntax of this source file; the remaining graphs still load.\n",
-          );
-        }
-      }
-    },
-  });
-}

package/src/domains/shared/buildQuery.ts

@@ -1,18 +0,0 @@
-/**
- * Brand an internally-constructed query string as SPARQL.
- *
- * The `sparql` tagged template cannot interpolate raw SPARQL fragments
- * (it would escape them as string literals). Operations that include
- * dynamic filter clauses construct the query as a plain string and
- * brand it via this helper.
- *
- * Safe because filter content is generated internally, never from
- * user input. User-supplied values (e.g., component names) are
- * escaped via `escapeSparqlValue()` before interpolation.
- */
-
-import type { SPARQL } from "@canonical/ke";
-
-export function buildQuery(query: string): SPARQL<string> {
-  return query as SPARQL<string>;
-}

package/src/domains/shared/compactUri.test.ts

@@ -1,32 +0,0 @@
-import { describe, expect, it } from "vitest";
-import compactUri from "./compactUri.js";
-
-describe("compactUri", () => {
-  const prefixes = {
-    ds: "https://ds.canonical.com/",
-    cs: "http://pragma.canonical.com/codestandards#",
-  } as const;
-
-  it("compacts a URI when a matching prefix exists", () => {
-    expect(
-      compactUri("https://ds.canonical.com/global.component.button", prefixes),
-    ).toBe("ds:global.component.button");
-  });
-
-  it("returns the original URI when no prefix matches", () => {
-    expect(compactUri("https://example.com/thing", prefixes)).toBe(
-      "https://example.com/thing",
-    );
-  });
-
-  it("picks the longest matching namespace when namespaces overlap", () => {
-    const overlapping = {
-      base: "https://ex.org/",
-      sub: "https://ex.org/sub/",
-    } as const;
-    // Both `base` and `sub` are prefixes of the URI; the longer wins.
-    expect(compactUri("https://ex.org/sub/Thing", overlapping)).toBe(
-      "sub:Thing",
-    );
-  });
-});

package/src/domains/shared/compactUri.ts

@@ -1,21 +0,0 @@
-/**
- * Convert a full URI to its compact prefixed form using the longest matching
- * namespace. When two registered namespaces are both prefixes of the URI
- * (e.g. a base namespace and a sub-namespace), the longer — more specific —
- * one wins. Falls back to the original URI when no namespace matches.
- */
-export default function compactUri(
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-): string {
-  let best: { prefix: string; namespace: string } | undefined;
-  for (const [prefix, namespace] of Object.entries(prefixes)) {
-    if (!fullUri.startsWith(namespace)) continue;
-    if (best === undefined || namespace.length > best.namespace.length) {
-      best = { prefix, namespace };
-    }
-  }
-
-  if (best === undefined) return fullUri;
-  return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
-}

package/src/domains/shared/context.ts

@@ -1,16 +0,0 @@
-/**
- * Extended command context for pragma CLI commands.
- *
- * Extends `PragmaRuntime` with CLI-specific global flags so commands
- * access store, config, cwd, and output preferences uniformly via `ctx`.
- *
- * cli-core remains unaware of Store or FilterConfig.
- */
-
-import type { GlobalFlags, PromptSessionFactory } from "@canonical/cli-core";
-import type { PragmaRuntime } from "./types/index.js";
-
-export interface PragmaContext extends PragmaRuntime {
-  readonly globalFlags: GlobalFlags;
-  readonly promptSession?: PromptSessionFactory | undefined;
-}

package/src/domains/shared/contracts.ts

@@ -1,164 +0,0 @@
-/**
- * Shared command and entity-display contracts.
- *
- * These types provide the structural common ground for CLI and MCP surfaces.
- */
-
-import type { FilterConfig } from "./types/index.js";
-
-export interface ColumnDef<T> {
-  readonly key: keyof T & string;
-  readonly label: string;
-  readonly format?: (value: unknown) => string;
-  readonly showWhenEmpty?: boolean;
-}
-
-export type SectionKind =
-  | "field"
-  | "code"
-  | "list"
-  | "table"
-  | "nested-table"
-  | "tree";
-
-export interface SectionDef<T> {
-  readonly key: keyof T & string;
-  readonly heading: string;
-  readonly kind: SectionKind;
-  readonly showWhenEmpty?: boolean;
-}
-
-export interface ListParams {
-  readonly allTiers?: boolean;
-  readonly digest?: boolean;
-  readonly detailed?: boolean;
-  readonly condensed?: boolean;
-}
-
-export interface LookupParams {
-  readonly names: readonly string[];
-  readonly detailed?: boolean;
-  readonly condensed?: boolean;
-}
-
-export interface ListResult<T> {
-  readonly items: readonly T[];
-  readonly filters: FilterConfig;
-  readonly disclosure:
-    | { readonly level: "summary" }
-    | { readonly level: "digest"; readonly maxExampleLength?: number }
-    | { readonly level: "detailed" };
-}
-
-/** Aggregate metadata about a multi-query lookup. */
-export interface LookupResultMeta {
-  /**
-   * Number of queries that failed with an unexpected (non-Pragma) error.
-   * Each such failure is also present in `errors` with code `INTERNAL_ERROR`.
-   */
-  readonly internalErrorCount: number;
-}
-
-export interface LookupResult<T> {
-  readonly results: readonly T[];
-  readonly errors: readonly {
-    query: string;
-    code: string;
-    message: string;
-    suggestions?: readonly string[];
-  }[];
-  /** Populated by `lookupMany`; may be absent on hand-built results. */
-  readonly meta?: LookupResultMeta;
-}
-
-export interface ShowContract<T> {
-  readonly result: T;
-}
-
-export interface MutateContract<TParams, TResult> {
-  readonly params: TParams;
-  readonly result: TResult;
-  readonly confirmation: string;
-}
-
-export interface ListContract<
-  TSummary,
-  TDigest extends TSummary,
-  TDetailed extends TDigest,
-> {
-  readonly params: ListParams;
-  readonly result: ListResult<TSummary | TDigest | TDetailed>;
-}
-
-export interface LookupContract<TDetailed> {
-  readonly params: LookupParams;
-  readonly result: LookupResult<TDetailed>;
-}
-
-// ---------------------------------------------------------------------------
-// Renderer contracts
-// ---------------------------------------------------------------------------
-
-/** A single inline field rendered in a lookup heading block. */
-export interface LookupField<T> {
-  readonly label: string;
-  readonly value: (entity: T) => unknown;
-}
-
-/** Per-mode override callbacks for a lookup section. */
-export interface LookupSectionOverride<T> {
-  readonly plain?: (entity: T, section: SectionDef<T>) => string | null;
-  readonly llm?: (entity: T, section: SectionDef<T>) => string | null;
-}
-
-/** Options controlling the generic list renderer. */
-export interface RenderListOptions<T> {
-  readonly heading: string;
-  readonly columns: readonly ColumnDef<T>[];
-  readonly prefixes?: Readonly<Record<string, string>>;
-}
-
-/** Options controlling the generic lookup renderer. */
-export interface RenderLookupOptions<T> {
-  readonly title: (entity: T) => string;
-  readonly fields: readonly LookupField<T>[];
-  readonly sections: readonly SectionDef<T>[];
-  readonly prefixes?: Readonly<Record<string, string>>;
-  readonly sectionOverrides?: Partial<
-    Record<keyof T & string, LookupSectionOverride<T>>
-  >;
-  readonly codeLanguage?: (section: SectionDef<T>, value: unknown) => string;
-}
-
-// ---------------------------------------------------------------------------
-// Entity display configuration
-// ---------------------------------------------------------------------------
-
-export interface EntityDisplayConfig<
-  TSummary,
-  TDigest extends TSummary,
-  TDetailed extends TDigest,
-> {
-  readonly domain: string;
-  readonly entityName: string;
-  readonly rdfTypes: readonly string[];
-  readonly listColumns: readonly ColumnDef<TSummary>[];
-  readonly digestColumns: readonly ColumnDef<TDigest>[];
-  readonly lookupSections: readonly SectionDef<TDetailed>[];
-  readonly emptyRecovery: (filters: FilterConfig) => {
-    readonly message: string;
-    readonly cli?: string;
-    readonly mcp?: {
-      readonly tool: string;
-      readonly params?: Record<string, unknown>;
-    };
-  };
-  readonly notFoundRecovery: (query: string) => {
-    readonly message: string;
-    readonly cli?: string;
-    readonly mcp?: {
-      readonly tool: string;
-      readonly params?: Record<string, unknown>;
-    };
-  };
-}