@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/graph/mcp/specs.ts

@@ -1,82 +0,0 @@
-/**
- * MCP tool specs for graph domain — graph_query, graph_inspect.
- */
-
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { executeQuery, inspectUri } from "../operations/index.js";
-
-const specs: readonly ToolSpec[] = [
-  {
-    name: "graph_query",
-    description:
-      "Execute a SPARQL query against the knowledge graph. Returns raw query results. Use ontology_list to discover available namespaces and prefixes.",
-    params: {
-      sparql: {
-        type: "string",
-        description: "SPARQL query string",
-        optional: false,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, params) {
-      const result = await executeQuery(rt.store, params.sparql as string);
-
-      if (params.condensed) {
-        const text = JSON.stringify(result, null, 2);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result };
-    },
-  },
-  {
-    name: "graph_inspect",
-    description:
-      "Inspect a URI in the knowledge graph. Returns all predicates and objects for the given subject.",
-    params: {
-      uri: {
-        type: "string",
-        description: "URI to inspect (full or prefixed, e.g. 'ds:Button')",
-        optional: false,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, params) {
-      const result = await inspectUri(rt.store, params.uri as string);
-
-      if (params.condensed) {
-        const lines = [`## ${result.uri}`, ""];
-        for (const g of result.groups) {
-          lines.push(`**${g.predicate}:**`);
-          for (const o of g.objects) {
-            lines.push(`  - ${o}`);
-          }
-        }
-        const text = lines.join("\n");
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result };
-    },
-  },
-];
-
-export default specs;

package/src/domains/graph/operations/executeQuery.test.ts

@@ -1,68 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import { P } from "../../shared/prefixes.js";
-import executeQuery from "./executeQuery.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-describe("executeQuery", () => {
-  it("executes a SELECT query and returns bindings", async () => {
-    const result = await executeQuery(
-      store,
-      `SELECT ?name WHERE { ?c a ${P.ds}Component ; ${P.ds}name ?name } ORDER BY ?name`,
-    );
-    expect(result.type).toBe("select");
-    if (result.type === "select") {
-      const names = result.bindings.map((b) => b.name);
-      expect(names).toContain("Button");
-      expect(names).toContain("Card");
-    }
-  });
-
-  it("executes a CONSTRUCT query and returns triples", async () => {
-    const result = await executeQuery(
-      store,
-      `CONSTRUCT { ?c ${P.ds}name ?name } WHERE { ?c a ${P.ds}Component ; ${P.ds}name ?name }`,
-    );
-    expect(result.type).toBe("construct");
-    if (result.type === "construct") {
-      expect(result.triples.length).toBeGreaterThan(0);
-      const names = result.triples.map((t) => t.object);
-      expect(names).toContain("Button");
-    }
-  });
-
-  it("executes an ASK query and returns boolean", async () => {
-    const result = await executeQuery(
-      store,
-      `ASK { ?c a ${P.ds}Component ; ${P.ds}name ?name }`,
-    );
-    expect(result.type).toBe("ask");
-    if (result.type === "ask") {
-      expect(result.result).toBe(true);
-    }
-  });
-
-  it("throws PragmaError on invalid SPARQL", async () => {
-    await expect(executeQuery(store, "SELECT INVALID SPARQL")).rejects.toThrow(
-      PragmaError,
-    );
-
-    try {
-      await executeQuery(store, "SELECT INVALID SPARQL");
-    } catch (e) {
-      expect((e as PragmaError).code).toBe("STORE_ERROR");
-    }
-  });
-});

package/src/domains/graph/operations/executeQuery.ts

@@ -1,32 +0,0 @@
-import type { QueryResult, Store } from "@canonical/ke";
-import { PragmaError } from "#error";
-import { buildQuery } from "../../shared/buildQuery.js";
-
-/**
- * Executes a raw SPARQL query against the ke store.
- *
- * @note Queries ke store
- *
- * @param store - The ke store to query.
- * @param sparql - A raw SPARQL query string.
- * @returns The query result (select bindings, ask boolean, or construct triples).
- * @throws PragmaError with code `STORE_ERROR` on query failure.
- */
-export default async function executeQuery(
-  store: Store,
-  sparql: string,
-): Promise<QueryResult> {
-  try {
-    return await store.query(buildQuery(sparql));
-  } catch (error) {
-    throw new PragmaError({
-      code: "STORE_ERROR",
-      message: `Failed to execute query. ${error instanceof Error ? error.message : String(error)}`,
-      recovery: {
-        message: "Check your SPARQL syntax and see loaded namespaces.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
-    });
-  }
-}

package/src/domains/graph/operations/index.ts

@@ -1,4 +0,0 @@
-/** @module Barrel for graph operations. */
-
-export { default as executeQuery } from "./executeQuery.js";
-export { default as inspectUri } from "./inspectUri.js";

package/src/domains/graph/operations/inspectUri.test.ts

@@ -1,101 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import { DEFAULT_PREFIX_MAP, P } from "../../shared/prefixes.js";
-import inspectUri from "./inspectUri.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-describe("inspectUri", () => {
-  it("returns grouped triples for a known URI", async () => {
-    const result = await inspectUri(store, `${P.ds}global.component.button`);
-    expect(result.uri).toBe(`${DEFAULT_PREFIX_MAP.ds}global.component.button`);
-    expect(result.groups.length).toBeGreaterThan(0);
-
-    const predicates = result.groups.map((g) => g.predicate);
-    expect(predicates).toContain(
-      "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-    );
-  });
-
-  it("resolves prefixed URIs", async () => {
-    const result = await inspectUri(store, `${P.ds}global.component.button`);
-    expect(result.uri).toBe(`${DEFAULT_PREFIX_MAP.ds}global.component.button`);
-  });
-
-  it("accepts full URIs", async () => {
-    const result = await inspectUri(
-      store,
-      `${DEFAULT_PREFIX_MAP.ds}global.component.button`,
-    );
-    expect(result.uri).toBe(`${DEFAULT_PREFIX_MAP.ds}global.component.button`);
-    expect(result.groups.length).toBeGreaterThan(0);
-  });
-
-  it("groups objects by predicate", async () => {
-    const result = await inspectUri(store, `${P.ds}global.component.button`);
-    const modifierGroup = result.groups.find((g) =>
-      g.predicate.includes("modifier"),
-    );
-    // Button has two modifiers (importance, density)
-    if (modifierGroup) {
-      expect(modifierGroup.objects.length).toBe(2);
-    }
-  });
-
-  it("throws PragmaError.notFound for unknown URI", async () => {
-    await expect(
-      inspectUri(store, `${P.ds}nonexistent_entity`),
-    ).rejects.toThrow(PragmaError);
-
-    try {
-      await inspectUri(store, `${P.ds}nonexistent_entity`);
-    } catch (e) {
-      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
-    }
-  });
-
-  it("throws PragmaError.invalidInput for unknown prefix", async () => {
-    await expect(inspectUri(store, "unknown:something")).rejects.toThrow(
-      PragmaError,
-    );
-
-    try {
-      await inspectUri(store, "unknown:something");
-    } catch (e) {
-      expect((e as PragmaError).code).toBe("INVALID_INPUT");
-    }
-  });
-
-  it("throws PragmaError.invalidInput for bare string without prefix", async () => {
-    await expect(inspectUri(store, "button")).rejects.toThrow(PragmaError);
-
-    try {
-      await inspectUri(store, "button");
-    } catch (e) {
-      expect((e as PragmaError).code).toBe("INVALID_INPUT");
-    }
-  });
-
-  it("throws PragmaError.invalidInput for URI with unsafe IRI characters", async () => {
-    await expect(
-      inspectUri(store, "https://example.com/<injected>"),
-    ).rejects.toThrow(PragmaError);
-
-    try {
-      await inspectUri(store, "https://example.com/<injected>");
-    } catch (e) {
-      expect((e as PragmaError).code).toBe("INVALID_INPUT");
-    }
-  });
-});

package/src/domains/graph/operations/inspectUri.ts

@@ -1,64 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { PragmaError } from "#error";
-import { buildQuery } from "../../shared/buildQuery.js";
-import type {
-  InspectResult,
-  PredicateGroup,
-} from "../../shared/types/index.js";
-import resolveUri from "../helpers/resolveUri.js";
-
-/**
- * Inspects a URI by retrieving all triples where it is the subject,
- * grouped by predicate.
- *
- * Resolves prefixed URIs (e.g. `ds:Button`) to full URIs before querying.
- *
- * @note Queries ke store
- *
- * @param store - The ke store to query.
- * @param uri - A full or prefixed URI to inspect.
- * @returns An {@link InspectResult} with the resolved URI and predicate groups.
- * @throws PragmaError.notFound if the URI has no triples in the store.
- */
-export default async function inspectUri(
-  store: Store,
-  uri: string,
-): Promise<InspectResult> {
-  const resolvedUri = resolveUri(uri, store.prefixes);
-
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?predicate ?object
-      WHERE {
-        <${resolvedUri}> ?predicate ?object .
-      }
-      ORDER BY ?predicate ?object
-    `),
-  );
-
-  if (result.type !== "select" || result.bindings.length === 0) {
-    throw PragmaError.notFound("entity", uri, {
-      recovery: {
-        message:
-          "Check the URI is correct and run a SPARQL query to find valid URIs.",
-        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
-        mcp: { tool: "graph_query" },
-      },
-    });
-  }
-
-  const groupMap = new Map<string, string[]>();
-  for (const b of result.bindings) {
-    const predicate = b.predicate ?? "";
-    const object = b.object ?? "";
-    const existing = groupMap.get(predicate) ?? [];
-    existing.push(object);
-    groupMap.set(predicate, existing);
-  }
-
-  const groups: PredicateGroup[] = [...groupMap.entries()].map(
-    ([predicate, objects]) => ({ predicate, objects }),
-  );
-
-  return { uri: resolvedUri, groups };
-}

package/src/domains/graphql/commands/build.test.ts

@@ -1,196 +0,0 @@
-import {
-  existsSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { CommandDefinition } from "@canonical/cli-core";
-import { hashSources } from "@canonical/ke-graphql";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  EX_PREFIX_ENTRY,
-  GRAPHQL_CLEAN_TTL,
-  GRAPHQL_ERROR_TTL,
-  GRAPHQL_FATAL_TTL,
-} from "#testing";
-import type { PragmaContext } from "../../shared/context.js";
-import type { GraphqlCompileReport } from "../types.js";
-import buildCommand from "./build.js";
-
-let dir: string;
-let stdoutSpy: ReturnType<typeof vi.spyOn>;
-
-beforeEach(() => {
-  dir = mkdtempSync(join(tmpdir(), "pragma-graphql-build-"));
-  writeFileSync(join(dir, "clean.ttl"), GRAPHQL_CLEAN_TTL);
-  writeFileSync(join(dir, "error.ttl"), GRAPHQL_ERROR_TTL);
-  writeFileSync(join(dir, "fatal.ttl"), GRAPHQL_FATAL_TTL);
-  stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
-});
-
-afterEach(() => {
-  stdoutSpy.mockRestore();
-  rmSync(dir, { recursive: true, force: true });
-});
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    cwd: dir,
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    store: {} as PragmaContext["store"],
-    config: { tier: undefined, channel: "normal" },
-    ...overrides,
-  } as PragmaContext;
-}
-
-async function executeOutput(
-  cmd: CommandDefinition,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<{ value: GraphqlCompileReport; text: string }> {
-  const result = await cmd.execute(params, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  return {
-    value: result.value as GraphqlCompileReport,
-    text: result.render.plain(result.value),
-  };
-}
-
-describe("graphql build command", () => {
-  it("writes the SDL and extraction artifacts to the default paths", async () => {
-    const ctx = makeCtx();
-    const { value } = await executeOutput(
-      buildCommand,
-      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
-      ctx,
-    );
-
-    const sdl = readFileSync(join(dir, "schema.graphql"), "utf-8");
-    expect(sdl).toContain("type Thing");
-
-    const artifact = JSON.parse(
-      readFileSync(join(dir, "extraction.json"), "utf-8"),
-    ) as { version: number; sourcesHash: string };
-    expect(artifact.version).toBe(1);
-
-    const raw = readFileSync(join(dir, "clean.ttl"), "utf-8");
-    expect(artifact.sourcesHash).toBe(hashSources([raw]));
-    expect(value.artifacts).toEqual({
-      sdl: join(dir, "schema.graphql"),
-      extraction: join(dir, "extraction.json"),
-    });
-  });
-
-  it("writes artifacts to custom --sdl and --extraction paths", async () => {
-    const ctx = makeCtx();
-    await executeOutput(
-      buildCommand,
-      {
-        sources: ["clean.ttl"],
-        prefix: [EX_PREFIX_ENTRY],
-        sdl: "out/api.graphql",
-        extraction: "out/api-extraction.json",
-      },
-      ctx,
-    );
-
-    expect(readFileSync(join(dir, "out", "api.graphql"), "utf-8")).toContain(
-      "type Thing",
-    );
-    expect(
-      JSON.parse(
-        readFileSync(join(dir, "out", "api-extraction.json"), "utf-8"),
-      ),
-    ).toMatchObject({ version: 1 });
-  });
-
-  it("renders plain output with a summary and artifact paths", async () => {
-    const ctx = makeCtx();
-    const { text } = await executeOutput(
-      buildCommand,
-      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
-      ctx,
-    );
-
-    expect(text).toContain("1 source file: 0 errors, 0 warnings, 0 info");
-    expect(text).toContain(`Wrote ${join(dir, "schema.graphql")}`);
-    expect(text).toContain(`Wrote ${join(dir, "extraction.json")}`);
-  });
-
-  it("prints error diagnostics but still writes artifacts", async () => {
-    const ctx = makeCtx();
-    const { text } = await executeOutput(
-      buildCommand,
-      { sources: ["error.ttl"], prefix: [EX_PREFIX_ENTRY] },
-      ctx,
-    );
-
-    expect(text).toContain("M001");
-    expect(text).toContain("1 error");
-    expect(existsSync(join(dir, "schema.graphql"))).toBe(true);
-    expect(existsSync(join(dir, "extraction.json"))).toBe(true);
-  });
-
-  it("renders llm output", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text" as const, verbose: false },
-    });
-    const { text } = await executeOutput(
-      buildCommand,
-      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
-      ctx,
-    );
-
-    expect(text).toContain("## GraphQL Compile");
-    expect(text).toContain("**Summary:**");
-  });
-
-  it("renders json output", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    });
-    const { text } = await executeOutput(
-      buildCommand,
-      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
-      ctx,
-    );
-
-    const parsed = JSON.parse(text) as GraphqlCompileReport;
-    expect(parsed.diagnostics).toEqual([]);
-    expect(parsed.files).toEqual([join(dir, "clean.ttl")]);
-  });
-
-  it("exits non-zero and writes no artifacts when compilation fails", async () => {
-    const ctx = makeCtx();
-    const result = await buildCommand.execute(
-      { sources: ["fatal.ttl"], prefix: [EX_PREFIX_ENTRY] },
-      ctx,
-    );
-
-    expect(result.tag).toBe("exit");
-    if (result.tag !== "exit") throw new Error("Expected exit result");
-    expect(result.code).toBe(1);
-    expect(existsSync(join(dir, "schema.graphql"))).toBe(false);
-    expect(existsSync(join(dir, "extraction.json"))).toBe(false);
-
-    const printed = stdoutSpy.mock.calls.map((call) => call[0]).join("");
-    expect(printed).toContain("C003");
-  });
-
-  it("throws a structured error when explicit sources match nothing", async () => {
-    const ctx = makeCtx();
-
-    await expect(
-      buildCommand.execute({ sources: ["no-such-*.ttl"] }, ctx),
-    ).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      recovery: {
-        message: "No files matched the given paths or glob patterns.",
-      },
-    });
-  });
-});

package/src/domains/graphql/commands/build.ts

@@ -1,117 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createExitResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { serializeExtraction } from "@canonical/ke-graphql";
-import { selectFormatter } from "../../shared/formatters.js";
-import { DEFAULT_EXTRACTION_PATH, DEFAULT_SDL_PATH } from "../constants.js";
-import { reportFormatters } from "../formatters/index.js";
-import { gatherSources, parsePrefixes } from "../helpers/index.js";
-import { compileSchema } from "../operations/index.js";
-import type { GraphqlCompileReport } from "../types.js";
-
-/** Narrow an unknown param to a string array. */
-function readStringArray(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value.filter((item): item is string => typeof item === "string")
-    : [];
-}
-
-/**
- * Builds the `pragma graphql build` command definition.
- *
- * Compiles TTL sources into a GraphQL schema, writes the SDL and the
- * extraction artifact, and prints all compiler diagnostics. Exits
- * non-zero when schema composition fails.
- */
-const buildCommand: CommandDefinition = {
-  path: ["graphql", "build"],
-  description: "Compile TTL sources into GraphQL schema artifacts",
-  parameters: [
-    {
-      name: "sources",
-      description:
-        "TTL files or globs (default: the configured semantic packages)",
-      type: "multiselect",
-      positional: true,
-    },
-    {
-      name: "sdl",
-      description: "Output path for the GraphQL SDL",
-      type: "string",
-      default: DEFAULT_SDL_PATH,
-    },
-    {
-      name: "extraction",
-      description: "Output path for the extraction artifact",
-      type: "string",
-      default: DEFAULT_EXTRACTION_PATH,
-    },
-    {
-      name: "prefix",
-      description: "Ontology prefix as name=namespace (repeatable)",
-      type: "multiselect",
-    },
-  ],
-  meta: {
-    examples: [
-      "pragma graphql build ontology.ttl",
-      'pragma graphql build "data/*.ttl" --sdl out/schema.graphql --extraction out/extraction.json',
-      "pragma graphql build ontology.ttl --prefix ds=https://ds.canonical.com/",
-    ],
-  },
-  async execute(params, ctx): Promise<CommandResult> {
-    const sources = await gatherSources(
-      readStringArray(params.sources),
-      ctx.cwd,
-    );
-    const prefixes = parsePrefixes(readStringArray(params.prefix));
-    const outcome = await compileSchema({ sources, prefixes, cwd: ctx.cwd });
-    const format = selectFormatter(ctx, reportFormatters);
-
-    if (outcome.status === "failed" || !outcome.compiled) {
-      const report: GraphqlCompileReport = {
-        diagnostics: outcome.diagnostics,
-        files: outcome.files,
-        sourcesHash: outcome.sourcesHash,
-      };
-      process.stdout.write(`${format(report)}\n`);
-      return createExitResult(1);
-    }
-
-    const sdlPath = resolve(
-      ctx.cwd,
-      typeof params.sdl === "string" ? params.sdl : DEFAULT_SDL_PATH,
-    );
-    const extractionPath = resolve(
-      ctx.cwd,
-      typeof params.extraction === "string"
-        ? params.extraction
-        : DEFAULT_EXTRACTION_PATH,
-    );
-
-    mkdirSync(dirname(sdlPath), { recursive: true });
-    writeFileSync(sdlPath, outcome.compiled.sdl, "utf-8");
-    mkdirSync(dirname(extractionPath), { recursive: true });
-    writeFileSync(
-      extractionPath,
-      serializeExtraction(outcome.compiled.extraction, outcome.sourcesHash),
-      "utf-8",
-    );
-
-    const report: GraphqlCompileReport = {
-      diagnostics: outcome.diagnostics,
-      files: outcome.files,
-      sourcesHash: outcome.sourcesHash,
-      artifacts: { sdl: sdlPath, extraction: extractionPath },
-    };
-
-    return createOutputResult(report, { plain: format });
-  },
-};
-
-export default buildCommand;