@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/shared/prefixes.ts

@@ -1,37 +0,0 @@
-/**
- * Prefix map for ke store creation.
- *
- * Registered as PREFIX declarations in every SPARQL query.
- * Single source of truth — rename a key here and P updates automatically.
- */
-
-import type { PrefixMap } from "@canonical/ke";
-
-export const PREFIX_MAP = {
-  ds: "https://ds.canonical.com/",
-  cs: "http://pragma.canonical.com/codestandards#",
-  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
-  owl: "http://www.w3.org/2002/07/owl#",
-  skos: "http://www.w3.org/2004/02/skos/core#",
-} as const satisfies PrefixMap;
-
-/**
- * SPARQL prefix accessors derived from {@link PREFIX_MAP}.
- *
- * Use in query templates: `${P.ds}Component` → `"ds:Component"`.
- * Renaming a key in PREFIX_MAP automatically updates every query.
- */
-export const P = Object.fromEntries(
-  Object.keys(PREFIX_MAP).map((k) => [k, `${k}:`]),
-) as { readonly [K in keyof typeof PREFIX_MAP]: `${K}:` };
-
-/**
- * Turtle `@prefix` declarations derived from {@link PREFIX_MAP}.
- *
- * Includes `xsd:` which TTL data files commonly use but SPARQL queries
- * don't need (ke auto-injects PREFIX_MAP for queries).
- */
-export const TTL_PREFIXES = [
-  ...Object.entries(PREFIX_MAP).map(([k, uri]) => `@prefix ${k}: <${uri}> .`),
-  "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
-].join("\n");

package/src/domains/shared/renderers.ts

@@ -1,410 +0,0 @@
-/**
- * Generic list and lookup renderers for CLI and LLM output modes.
- *
- * All domain formatters delegate to these pure, layout-only functions.
- * Each renderer accepts a typed options bag (defined in contracts.ts)
- * and returns a fully formatted string — no I/O, no side effects.
- */
-
-import compactUri from "./compactUri.js";
-import type {
-  ColumnDef,
-  RenderListOptions,
-  RenderLookupOptions,
-  SectionDef,
-} from "./contracts.js";
-import { PREFIX_MAP } from "./prefixes.js";
-
-type RenderMode = "plain" | "llm";
-
-export function renderListPlain<T>(
-  items: readonly T[],
-  options: RenderListOptions<T>,
-): string {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
-  const rows = items.map((item) =>
-    options.columns
-      .map((column) => ({
-        column,
-        value: formatColumnValue(item, column, prefixes),
-      }))
-      .filter(({ column, value }) => shouldRenderColumn(column, value))
-      .map(({ value }) => value),
-  );
-
-  const widths = rows.reduce<number[]>(
-    (acc, row) =>
-      row.map((value, index) => Math.max(acc[index] ?? 0, value.length)),
-    [],
-  );
-
-  return rows
-    .map((row) =>
-      row
-        .map((value, index) => value.padEnd(widths[index] ?? value.length))
-        .join("  ")
-        .trimEnd(),
-    )
-    .join("\n");
-}
-
-export function renderListLlm<T>(
-  items: readonly T[],
-  options: RenderListOptions<T>,
-): string {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
-  const lines = [`## ${options.heading} (${items.length})`, ""];
-
-  for (const item of items) {
-    const values = options.columns
-      .map((column) => ({
-        column,
-        value: formatColumnValue(item, column, prefixes),
-      }))
-      .filter(({ column, value }) => shouldRenderColumn(column, value));
-
-    const iri = values.find(({ column }) => column.key === "uri")?.value;
-    const name = values.find(({ column }) => column.key === "name")?.value;
-    const rest = values
-      .filter(({ column }) => column.key !== "uri" && column.key !== "name")
-      .map(({ value }) => value)
-      .filter(Boolean);
-
-    const parts: string[] = [];
-    if (iri) parts.push(`\`${iri}\``);
-    if (name) {
-      parts.push(iri ? `— **${name}**` : `**${name}**`);
-    }
-    if (rest.length > 0) {
-      parts.push(rest.join(" | "));
-    }
-
-    lines.push(`- ${parts.join(" ")}`.trimEnd());
-  }
-
-  return lines.join("\n");
-}
-
-export function renderLookupPlain<T>(
-  entity: T,
-  options: RenderLookupOptions<T>,
-): string {
-  return renderLookup(entity, options, "plain");
-}
-
-export function renderLookupLlm<T>(
-  entity: T,
-  options: RenderLookupOptions<T>,
-): string {
-  return renderLookup(entity, options, "llm");
-}
-
-function renderLookup<T>(
-  entity: T,
-  options: RenderLookupOptions<T>,
-  mode: RenderMode,
-): string {
-  const title = options.title(entity);
-  const fields = renderLookupFields(entity, options, mode);
-  const sections = renderLookupSections(entity, options, mode);
-
-  if (mode === "llm") {
-    return [`## ${title}`, "", ...fields, ...sections].join("\n").trimEnd();
-  }
-
-  const headingRule = "═".repeat(Math.max(title.length, 24));
-  return [title, headingRule, "", ...fields, ...sections].join("\n").trimEnd();
-}
-
-function renderLookupFields<T>(
-  entity: T,
-  options: RenderLookupOptions<T>,
-  mode: RenderMode,
-): string[] {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
-  return options.fields.flatMap((field) => {
-    const value = field.value(entity);
-    if (isEmptyValue(value)) {
-      return [];
-    }
-
-    const formatted = formatInlineValue(value, prefixes);
-    return mode === "llm"
-      ? [`- ${field.label}: ${formatted}`]
-      : [`  ${field.label}: ${formatted}`];
-  });
-}
-
-function renderLookupSections<T>(
-  entity: T,
-  options: RenderLookupOptions<T>,
-  mode: RenderMode,
-): string[] {
-  const sections: string[] = [];
-
-  for (const section of options.sections) {
-    const value = entity[section.key];
-    if (!section.showWhenEmpty && isEmptyValue(value)) {
-      continue;
-    }
-
-    const override = options.sectionOverrides?.[section.key]?.[mode];
-    const body = override
-      ? override(entity, section)
-      : renderSectionValue(value, section, options, mode);
-
-    if (!body) {
-      continue;
-    }
-
-    sections.push("");
-    sections.push(
-      mode === "llm" ? `### ${section.heading}` : `${section.heading}:`,
-    );
-    sections.push(body);
-  }
-
-  return sections;
-}
-
-function renderSectionValue<T>(
-  value: unknown,
-  section: SectionDef<T>,
-  options: RenderLookupOptions<T>,
-  mode: RenderMode,
-): string | null {
-  const prefixes = options.prefixes ?? PREFIX_MAP;
-
-  switch (section.kind) {
-    case "field":
-      return renderFieldValue(value, prefixes, mode);
-    case "code":
-      return renderCodeValue(value, section, options, mode);
-    case "list":
-    case "table":
-    case "nested-table":
-      return renderCollectionValue(value, prefixes, mode);
-    case "tree":
-      return renderTreeValue(value, prefixes, mode);
-    default:
-      return null;
-  }
-}
-
-function renderFieldValue(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-  mode: RenderMode,
-): string | null {
-  if (isEmptyValue(value)) {
-    return null;
-  }
-
-  const text = formatScalarValue(value, prefixes);
-  return mode === "llm" ? text : indentBlock(text);
-}
-
-function renderCodeValue<T>(
-  value: unknown,
-  section: SectionDef<T>,
-  options: RenderLookupOptions<T>,
-  mode: RenderMode,
-): string | null {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    return null;
-  }
-
-  const language =
-    options.codeLanguage?.(section, value) ?? inferCodeLanguage(value);
-  if (mode === "llm") {
-    return [`\`\`\`${language}`, value, "```"].join("\n");
-  }
-
-  const header = language === "text" ? "" : `[${language}]\n`;
-  return indentBlock(`${header}${value}`.trimEnd());
-}
-
-function renderCollectionValue(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-  mode: RenderMode,
-): string | null {
-  if (!Array.isArray(value) || value.length === 0) {
-    return null;
-  }
-
-  const lines = value.map(
-    (entry) => `- ${formatCollectionEntry(entry, prefixes)}`,
-  );
-  return mode === "llm" ? lines.join("\n") : indentBlock(lines.join("\n"));
-}
-
-function renderTreeValue(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-  mode: RenderMode,
-): string | null {
-  const lines = buildTreeLines(value, prefixes);
-  if (lines.length === 0) {
-    return null;
-  }
-
-  return mode === "llm" ? lines.join("\n") : indentBlock(lines.join("\n"));
-}
-
-function buildTreeLines(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-  depth = 0,
-): string[] {
-  if (Array.isArray(value)) {
-    return value.flatMap((entry) => buildTreeLines(entry, prefixes, depth));
-  }
-
-  if (!value || typeof value !== "object") {
-    return typeof value === "string" && value.length > 0
-      ? [`${"  ".repeat(depth)}- ${formatScalarValue(value, prefixes)}`]
-      : [];
-  }
-
-  const rootedTree = value as { root?: unknown };
-  if (rootedTree.root) {
-    return buildTreeLines(rootedTree.root, prefixes, depth);
-  }
-
-  const treeNode = value as {
-    name?: unknown;
-    uri?: unknown;
-    children?: unknown;
-  };
-  const label =
-    typeof treeNode.name === "string" && treeNode.name.length > 0
-      ? treeNode.name
-      : typeof treeNode.uri === "string"
-        ? compactUri(treeNode.uri, prefixes)
-        : "item";
-
-  const lines = [`${"  ".repeat(depth)}- ${label}`];
-  if (Array.isArray(treeNode.children)) {
-    lines.push(...buildTreeLines(treeNode.children, prefixes, depth + 1));
-  }
-  return lines;
-}
-
-function formatCollectionEntry(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-): string {
-  if (!value || typeof value !== "object") {
-    return formatScalarValue(value, prefixes);
-  }
-
-  const object = value as Record<string, unknown>;
-  return Object.entries(object)
-    .filter(([, entryValue]) => !isEmptyValue(entryValue))
-    .map(
-      ([key, entryValue]) =>
-        `${key}: ${formatInlineValue(entryValue, prefixes)}`,
-    )
-    .join(" | ");
-}
-
-function formatColumnValue<T>(
-  item: T,
-  column: ColumnDef<T>,
-  prefixes: Readonly<Record<string, string>>,
-): string {
-  const raw = item[column.key];
-  if (column.format) {
-    return column.format(raw);
-  }
-
-  return formatInlineValue(raw, prefixes);
-}
-
-function formatInlineValue(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-): string {
-  if (Array.isArray(value)) {
-    return value.map((entry) => formatInlineValue(entry, prefixes)).join(", ");
-  }
-
-  if (value && typeof value === "object") {
-    return Object.entries(value as Record<string, unknown>)
-      .filter(([, entryValue]) => !isEmptyValue(entryValue))
-      .map(
-        ([key, entryValue]) =>
-          `${key}=${formatInlineValue(entryValue, prefixes)}`,
-      )
-      .join("; ");
-  }
-
-  return formatScalarValue(value, prefixes);
-}
-
-function formatScalarValue(
-  value: unknown,
-  prefixes: Readonly<Record<string, string>>,
-): string {
-  if (value === null || value === undefined) {
-    return "";
-  }
-
-  if (typeof value === "string") {
-    return looksLikeUri(value) ? compactUri(value, prefixes) : value;
-  }
-
-  return String(value);
-}
-
-function shouldRenderColumn<T>(column: ColumnDef<T>, value: string): boolean {
-  if (value.length > 0) {
-    return true;
-  }
-
-  return column.showWhenEmpty === true;
-}
-
-function inferCodeLanguage(value: string): string {
-  const trimmed = value.trim();
-  if (trimmed.startsWith("@prefix") || trimmed.includes(" a ")) {
-    return "ttl";
-  }
-  if (trimmed.includes(":") && trimmed.includes("\n")) {
-    return "yaml";
-  }
-  return "text";
-}
-
-function looksLikeUri(value: string): boolean {
-  return (
-    value.startsWith("http://") ||
-    value.startsWith("https://") ||
-    /^[a-z][a-z0-9+.-]*:/i.test(value)
-  );
-}
-
-function isEmptyValue(value: unknown): boolean {
-  if (value === null || value === undefined) {
-    return true;
-  }
-
-  if (typeof value === "string") {
-    return value.trim().length === 0;
-  }
-
-  if (Array.isArray(value)) {
-    return value.length === 0;
-  }
-
-  return false;
-}
-
-function indentBlock(value: string, spaces = 2): string {
-  const indent = " ".repeat(spaces);
-  return value
-    .split("\n")
-    .map((line) => `${indent}${line}`)
-    .join("\n");
-}

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

@@ -1,27 +0,0 @@
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import resolveConfiguredGraphs from "./resolveConfiguredGraphs.js";
-
-describe("resolveConfiguredGraphs", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "pragma-rcg-"));
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("resolves the default semantic packages' TTL graphs", async () => {
-    // No pragma.config.json in the temp dir → mergeAndParseRefs falls back to
-    // the default packages, which resolve from node_modules in the workspace.
-    const graphs = await resolveConfiguredGraphs(dir);
-
-    expect(graphs.length).toBeGreaterThan(0);
-    expect(graphs[0]).toMatchObject({ format: "turtle" });
-    expect(typeof graphs[0]?.content).toBe("string");
-  });
-});

package/src/domains/shared/resolveConfiguredGraphs.ts

@@ -1,41 +0,0 @@
-/**
- * Resolve every TTL graph from the semantically-configured packages.
- *
- * Reads `pragma.config.json`, merges its `packages` with the global refs
- * and the built-in defaults (a non-empty `packages` list replaces the set
- * entirely; an empty or absent list falls back to global refs merged over
- * the defaults), resolves each package through the loader chain
- * (local > git > bundled), and returns the union of their definitions/ and
- * data/ graph content — the same discovery the runtime store performs at
- * boot, minus the store.
- *
- * @note Impure — reads config and package files from disk.
- *
- * @param cwd - Working directory used to locate `pragma.config.json`.
- * @returns The TTL graph content of every resolved package.
- */
-
-import { readConfig } from "#config";
-import {
-  createBundledLoader,
-  createGitLoader,
-  createLocalLoader,
-} from "./loaders/index.js";
-import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
-import {
-  type GraphContent,
-  resolveSemanticPackages,
-} from "./semanticPackage.js";
-
-export default async function resolveConfiguredGraphs(
-  cwd: string,
-): Promise<GraphContent[]> {
-  const config = readConfig(cwd);
-  const refs = mergeAndParseRefs(config.packages);
-  const packages = await resolveSemanticPackages(refs, [
-    createLocalLoader(),
-    createGitLoader(),
-    createBundledLoader(),
-  ]);
-  return packages.flatMap((pkg) => pkg.graphs);
-}

package/src/domains/shared/runtime.ts

@@ -1,61 +0,0 @@
-/**
- * Unified boot path for pragma CLI, MCP, and completions server.
- *
- * `bootPragma()` is the single factory function that creates a
- * `PragmaRuntime`. All three surfaces (CLI, MCP, completions) call it
- * instead of manually assembling store + config.
- *
- * @note Impure — reads config from filesystem and boots ke store (WASM + TTL).
- */
-
-import type { SourceSpec } from "@canonical/ke";
-import { readConfig } from "#config";
-import { bootStore } from "./bootStore.js";
-import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
-import type { PragmaRuntime } from "./types/index.js";
-
-export type { PragmaRuntime } from "./types/index.js";
-
-/**
- * Create a fully initialized `PragmaRuntime`.
- *
- * Reads config from `cwd` (defaults to `process.cwd()`), merges global
- * and project package refs, boots the ke store from resolved sources,
- * and returns a runtime ready for operation calls.
- *
- * The caller owns the lifecycle and must call `dispose()`.
- *
- * @param options.cwd - Working directory for config and source resolution.
- * @param options.sources - Override sources for testing (skip filesystem resolution).
- * @throws PragmaError with code CONFIG_ERROR if config is invalid.
- * @throws PragmaError with code STORE_ERROR if store fails to initialize.
- */
-export async function bootPragma(options?: {
-  cwd?: string;
-  sources?: SourceSpec[];
-}): Promise<PragmaRuntime> {
-  const cwd = options?.cwd ?? process.cwd();
-  const config = readConfig(cwd);
-
-  // Merge package refs: a non-empty config list replaces global refs and
-  // defaults; otherwise global refs merge over the defaults.
-  const refs = options?.sources
-    ? undefined
-    : mergeAndParseRefs(config.packages);
-
-  const { store, packages } = await bootStore({
-    cwd,
-    sources: options?.sources,
-    refs,
-    trace: config.trace,
-    prefixes: config.prefixes,
-  });
-
-  return {
-    store,
-    config,
-    cwd,
-    packages,
-    dispose: () => store.dispose(),
-  };
-}

package/src/domains/shared/sampleFormatters.ts

@@ -1,47 +0,0 @@
-/**
- * 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,
-      );
-    },
-  };
-}