@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/packs/graphqlSource.test.ts

@@ -0,0 +1,383 @@
+/**
+ * GraphQL source (PROTECTED): the source-rule zod refinements (§3), the ported
+ * document generator, injection safety, and graphql==sparql PackEntity shape
+ * parity — all against the block fixture graph, compiled through the same kernel
+ * as every pack.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  BLOCK_PREFIXES,
+  BLOCK_TTL,
+} from "../../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { PragmaRuntime, StoreSession } from "../runtime/types.js";
+import { compilePack } from "./compile.js";
+import { buildLookupDocument } from "./graphql/buildLookupDocument.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import { parsePackDefinition } from "./schema.js";
+import type { PackDefinition, PackLookup } from "./types.js";
+import { verbKey } from "./uniqueness.js";
+
+const DS = "https://ds.canonical.com/";
+
+/** A graphql-sourced block pack over the UIBlock interface (nested + scoped). */
+const GBLOCK: PackDefinition = {
+  noun: "gblock",
+  lookup: {
+    source: "graphql",
+    by: "ds:name",
+    types: ["ds:Component", "ds:Pattern", "ds:Subcomponent"],
+    graphqlType: "UIBlock",
+    fields: [
+      { name: "summary", property: "ds:summary" },
+      { name: "tier", property: "ds:tier" },
+    ],
+    sections: [
+      {
+        name: "anatomyDsl",
+        property: "ds:anatomyDsl",
+        kind: "code",
+        level: "detailed",
+      },
+    ],
+    expand: [
+      {
+        name: "modifierFamilies",
+        relation: "ds:hasModifierFamily",
+        level: "detailed",
+        select: [
+          { name: "name", property: "ds:name" },
+          {
+            name: "values",
+            relation: "ds:hasModifier",
+            select: [{ name: "name", property: "ds:name" }],
+          },
+        ],
+      },
+      {
+        name: "subcomponents",
+        relation: "ds:hasSubcomponent",
+        select: [
+          { name: "name", property: "ds:name" },
+          { name: "uri", property: "ds:name", graphqlField: "uri" },
+        ],
+      },
+    ],
+    disclosure: { levels: ["summary", "detailed"], default: "detailed" },
+  },
+};
+
+describe("source rule — zod refinements reject dual/ill-sourced lookups (PROTECTED)", () => {
+  it("accepts a well-formed graphql lookup (round-trips)", () => {
+    expect(
+      parsePackDefinition(JSON.parse(JSON.stringify(GBLOCK)), "t"),
+    ).toEqual(GBLOCK);
+  });
+
+  it("rejects `type` and `types` together (mutually exclusive)", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "x",
+          lookup: {
+            by: "ds:name",
+            type: "ds:Component",
+            types: ["ds:Pattern"],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/mutually exclusive/);
+  });
+
+  it("rejects a graphql lookup with no fragment target", () => {
+    expect(() =>
+      parsePackDefinition(
+        { noun: "x", lookup: { source: "graphql", by: "ds:name" } },
+        "t",
+      ),
+    ).toThrow(/graphqlType/);
+  });
+
+  it("rejects a nested expand on a sparql lookup (single-hop only)", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "x",
+          lookup: {
+            source: "sparql",
+            by: "ds:name",
+            type: "ds:Component",
+            expand: [
+              {
+                name: "f",
+                relation: "ds:hasModifierFamily",
+                select: [
+                  {
+                    name: "v",
+                    relation: "ds:hasModifier",
+                    select: [{ name: "n", property: "ds:name" }],
+                  },
+                ],
+              },
+            ],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/single-hop|graphql/i);
+  });
+
+  it("rejects a graphql field addressed by a property path", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "x",
+          lookup: {
+            source: "graphql",
+            by: "ds:name",
+            type: "ds:Component",
+            graphqlType: "Component",
+            fields: [{ name: "c", property: "ds:a/ds:b" }],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/property path/);
+  });
+});
+
+describe("GraphQL engine — against the compiled fixture schema (PROTECTED)", () => {
+  let rt: PragmaRuntime;
+  let schema: StoreSession["schema"];
+
+  beforeAll(async () => {
+    ({ rt } = await buildFixtureRuntime({
+      ttl: BLOCK_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "detailed",
+    }));
+    schema = (await rt.store.get()).schema;
+  });
+
+  afterAll(async () => {
+    (await rt.store.get()).store.dispose();
+  });
+
+  const lookup = GBLOCK.lookup as PackLookup;
+
+  it("generates one document with derived names, Relay envelopes, subtype scoping", () => {
+    const plan = buildLookupDocument(lookup, schema, "t");
+    expect(plan.source).toContain("query PackLookup($uri: ID!)");
+    expect(plan.source).toContain("... on UIBlock");
+    expect(plan.source).toContain("tier { uri }");
+    expect(plan.source).toMatch(
+      /modifierFamilies\(first: \d+\) \{ edges \{ node \{/,
+    );
+    expect(plan.source).toMatch(/values: modifiers\(first: \d+\)/);
+    expect(plan.source).toMatch(
+      /\.\.\. on Component \{ subcomponents\(first: \d+\) \{ edges \{ node \{ name uri \} \} \} \}/,
+    );
+  });
+
+  it("drops level-gated selections below their level (fetch-gating)", () => {
+    const plan = buildLookupDocument(lookup, schema, "t", "summary");
+    expect(plan.source).not.toContain("anatomyDsl");
+    expect(plan.source).not.toContain("modifierFamilies");
+    expect(plan.source).toContain("summary");
+  });
+
+  it("honors and validates the graphqlField escape hatch", () => {
+    const plan = buildLookupDocument(
+      {
+        source: "graphql",
+        by: "ds:name",
+        graphqlType: "Component",
+        fields: [
+          { name: "blurb", property: "ds:none", graphqlField: "summary" },
+        ],
+      },
+      schema,
+      "t",
+    );
+    expect(plan.source).toContain("blurb: summary");
+    expect(() =>
+      buildLookupDocument(
+        {
+          source: "graphql",
+          by: "ds:name",
+          graphqlType: "Component",
+          fields: [{ name: "x", property: "ds:x", graphqlField: "notAField" }],
+        },
+        schema,
+        "t",
+      ),
+    ).toThrow(/notAField/);
+  });
+
+  it("omits a derived property that maps onto no field (OPTIONAL parity)", () => {
+    const plan = buildLookupDocument(
+      {
+        source: "graphql",
+        by: "ds:name",
+        graphqlType: "Component",
+        fields: [
+          { name: "summary", property: "ds:summary" },
+          { name: "ghost", property: "ds:definitelyNotAProperty" },
+        ],
+      },
+      schema,
+      "t",
+    );
+    expect(plan.source).toContain("summary");
+    expect(plan.source).not.toContain("ghost");
+    expect(plan.projections.map((p) => p.name)).toEqual(["summary"]);
+  });
+
+  it("rejects cardinality mismatches and an unknown fragment", () => {
+    expect(() =>
+      buildLookupDocument(
+        {
+          source: "graphql",
+          by: "ds:name",
+          graphqlType: "Component",
+          fields: [{ name: "f", property: "ds:hasModifierFamily" }],
+        },
+        schema,
+        "t",
+      ),
+    ).toThrow(/expand/);
+    expect(() =>
+      buildLookupDocument(
+        {
+          source: "graphql",
+          by: "ds:name",
+          graphqlType: "Component",
+          expand: [
+            {
+              name: "t",
+              relation: "ds:tier",
+              select: [{ name: "n", property: "ds:name" }],
+            },
+          ],
+        },
+        schema,
+        "t",
+      ),
+    ).toThrow(/singular/);
+    expect(() =>
+      buildLookupDocument(
+        { source: "graphql", by: "ds:name", graphqlType: "Nonesuch" },
+        schema,
+        "t",
+      ),
+    ).toThrow(/Nonesuch/);
+  });
+});
+
+describe("GraphQL lookup end to end + shape parity with SPARQL (PROTECTED)", () => {
+  let rt: PragmaRuntime;
+
+  beforeAll(async () => {
+    ({ rt } = await buildFixtureRuntime({
+      ttl: BLOCK_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "detailed",
+    }));
+  });
+
+  afterAll(async () => {
+    (await rt.store.get()).store.dispose();
+  });
+
+  const lookupVia = (definition: PackDefinition, name: string) => {
+    const verb = compilePack(definition, "t", BLOCK_PREFIXES).find(
+      (v) => verbKey(v.path) === `${definition.noun} lookup`,
+    );
+    if (!verb) throw new Error("no lookup verb");
+    return verb.run({ name: [name] }, rt) as Promise<LookupOutput>;
+  };
+
+  it("resolves the nested inverse-union and subtype-scoped identity fields", async () => {
+    const out = await lookupVia(GBLOCK, "Button");
+    expect(out.errors).toEqual([]);
+    const entity = out.results.at(0) as Record<string, unknown>;
+    expect(entity.uri).toBe(`${DS}button`);
+    expect(entity.summary).toBe(
+      "Primary action trigger with optional icon and label.",
+    );
+    expect(entity.tier).toBe(`${DS}global`);
+    const families = entity.modifierFamilies as {
+      name: string;
+      values: string[];
+    }[];
+    expect(families.map((f) => f.name).sort()).toEqual([
+      "density",
+      "importance",
+    ]);
+    const importance = families.find((f) => f.name === "importance");
+    expect(importance?.values.sort()).toEqual(["primary", "secondary"]);
+    expect(entity.subcomponents).toEqual([
+      { name: "Button Icon", uri: `${DS}button.icon` },
+    ]);
+  });
+
+  it("matches names case-insensitively via the SPARQL resolve", async () => {
+    const out = await lookupVia(GBLOCK, "bUTTOn");
+    expect((out.results.at(0) as Record<string, unknown>).name).toBe("Button");
+  });
+
+  it("produces a PackEntity shape-identical to the SPARQL path (single-hop)", async () => {
+    const commonExpand = {
+      name: "properties",
+      relation: "ds:hasProperty",
+      select: [{ name: "name", property: "ds:name" }],
+    };
+    const graphqlPack: PackDefinition = {
+      noun: "gc",
+      lookup: {
+        source: "graphql",
+        by: "ds:name",
+        type: "ds:Component",
+        graphqlType: "Component",
+        fields: [
+          { name: "summary", property: "ds:summary" },
+          { name: "tier", property: "ds:tier" },
+        ],
+        expand: [commonExpand],
+      },
+    };
+    const sparqlPack: PackDefinition = {
+      noun: "sc",
+      lookup: {
+        source: "sparql",
+        by: "ds:name",
+        type: "ds:Component",
+        fields: [
+          { name: "summary", property: "ds:summary" },
+          { name: "tier", property: "ds:tier" },
+        ],
+        expand: [commonExpand],
+      },
+    };
+    const viaGraphql = (await lookupVia(graphqlPack, "Button")).results.at(0);
+    const viaSparql = (await lookupVia(sparqlPack, "Button")).results.at(0);
+    expect(viaGraphql).toEqual(viaSparql);
+    expect(viaGraphql).toEqual({
+      uri: `${DS}button`,
+      name: "Button",
+      summary: "Primary action trigger with optional icon and label.",
+      tier: `${DS}global`,
+      properties: [{ name: "disabled" }],
+    });
+  });
+
+  it("escapes an injection-shaped name in the resolve (no crash, clean miss)", async () => {
+    // The `"` and `#` are escaped into the SPARQL literal, so the query stays
+    // valid and simply matches nothing — a clean ENTITY_NOT_FOUND, not a crash.
+    await expect(lookupVia(GBLOCK, 'Button" } INJECT #')).rejects.toThrow(
+      /not found/i,
+    );
+  });
+});

package/src/kernel/packs/iri.ts

@@ -0,0 +1,78 @@
+/**
+ * IRI utilities for pack lookups addressed by prefixed name or absolute IRI.
+ *
+ * `resolveUri` expands a prefixed name through the store's merged prefix map (a
+ * registered prefix always wins; a foreign absolute IRI passes through);
+ * `isEmbeddableIri` is the stricter `scheme://…` shape a resolved IRI must match
+ * before it can be interpolated into a generated `<iri>` query token.
+ */
+
+import { PragmaError } from "../error/PragmaError.js";
+
+/** Characters not allowed inside a SPARQL `<IRI>`. */
+const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
+
+/** A general absolute IRI: `scheme://…` (http, https, …) or a `urn:` opaque IRI. */
+const ABSOLUTE_IRI_PATTERN = /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/|urn:)\S/i;
+
+/** The embeddable-IRI shape: an authority-bearing `scheme://…` with no IRI-breakers. */
+const EMBEDDABLE_IRI_PATTERN = /^[A-Za-z][\w+.-]*:\/\/[^<>"\s]+$/;
+
+/** Whether a resolved IRI is safe to embed as a `<iri>` query token. */
+export function isEmbeddableIri(value: string): boolean {
+  return EMBEDDABLE_IRI_PATTERN.test(value);
+}
+
+/**
+ * Resolve a prefixed or absolute URI to its full form.
+ *
+ * @param uri - A full or prefixed URI string.
+ * @param prefixes - The store's merged prefix→namespace map.
+ * @returns The fully expanded URI.
+ * @throws PragmaError INVALID_INPUT when the format is invalid or the prefix is unknown.
+ */
+export function resolveUri(
+  uri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  const colonIdx = uri.indexOf(":");
+  if (colonIdx === -1) {
+    throw PragmaError.invalidInput("uri", uri, {
+      recovery: {
+        message:
+          'Use a prefixed URI (e.g. "ds:global.component.button") or a full URI.',
+      },
+    });
+  }
+
+  const prefix = uri.slice(0, colonIdx);
+  const namespace = prefixes[prefix];
+  if (namespace !== undefined) {
+    const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
+    assertSafeIri(resolved);
+    return resolved;
+  }
+
+  if (ABSOLUTE_IRI_PATTERN.test(uri)) {
+    assertSafeIri(uri);
+    return uri;
+  }
+
+  throw PragmaError.invalidInput("prefix", prefix, {
+    validOptions: Object.keys(prefixes),
+    recovery: {
+      message: "List known ontology prefixes.",
+      cli: "pragma ontology list",
+      mcp: { tool: "ontology_list" },
+    },
+  });
+}
+
+/** @throws PragmaError INVALID_INPUT when the URI contains IRI-breaking characters. */
+function assertSafeIri(uri: string): void {
+  if (UNSAFE_IRI_PATTERN.test(uri)) {
+    throw PragmaError.invalidInput("uri", uri, {
+      recovery: { message: "URI contains characters not allowed in IRIs." },
+    });
+  }
+}

package/src/kernel/packs/renderPack.ts

@@ -0,0 +1,196 @@
+/**
+ * Project a pack definition onto PR1 render option bags and the three-mode
+ * {@link Formatters} each compiled verb carries.
+ *
+ * List rows, looked-up entities, and sample exemplars all render through the
+ * shared generic renderers with a baked prefix map (display compaction only —
+ * the fetch layer already resolved full IRIs). The formatters are pure and
+ * zod-free, built once at compile time; the run body decides WHAT data reaches
+ * them (disclosure gates the fetch), never HOW it is laid out.
+ */
+
+import type {
+  ColumnDef,
+  LookupField,
+  RenderListOptions,
+  RenderLookupOptions,
+  SectionDef,
+} from "../render/contracts.js";
+import {
+  renderListLlm,
+  renderListPlain,
+  renderLookupLlm,
+  renderLookupPlain,
+} from "../render/renderers.js";
+import type { Formatters } from "../spec/types.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import type {
+  PackChildRow,
+  PackEntity,
+  PackList,
+  PackLookup,
+  PackRow,
+} from "./types.js";
+
+/** Sample output: the drawn exemplars, the population size, and agent follow-ups. */
+export interface SampleOutput {
+  readonly samples: PackEntity[];
+  readonly totalCount: number;
+  readonly nextSteps: string[];
+}
+
+/** Presentation facts shared by every formatter a pack noun compiles. */
+export interface RenderMeta {
+  readonly heading: string;
+  /** The noun, used to phrase the empty-state message. */
+  readonly noun: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+/**
+ * The default empty-state hint when a pack authors no `emptyRecovery`: an empty
+ * list on a BUILT store (a cold store would have failed with STORE_UNAVAILABLE
+ * first) means "nothing matched", so point at both possible fixes.
+ */
+const DEFAULT_EMPTY_HINT =
+  "If you haven't built the store yet, run `pragma sources update`; otherwise broaden your filter or channel.";
+
+/** Build the list formatters for a list-shaped verb (list or an extra verb). */
+export function listFormatters(
+  shape: PackList,
+  meta: RenderMeta,
+): Formatters<PackRow[]> {
+  const columns: ColumnDef<PackRow>[] = shape.columns.map((column) => ({
+    key: column.field,
+    label: column.label ?? column.field,
+  }));
+  // Zero results is a calm success, not an error (see runBodies.makeListRun):
+  // render a non-blank message, exit 0, JSON stays []. A pack's authored
+  // `emptyRecovery` becomes the hint; otherwise the generic build/broaden hint.
+  const emptyHint = shape.emptyRecovery
+    ? `${shape.emptyRecovery.message}${
+        shape.emptyRecovery.cli ? ` Run \`${shape.emptyRecovery.cli}\`.` : ""
+      }`
+    : DEFAULT_EMPTY_HINT;
+  const options: RenderListOptions<PackRow> = {
+    heading: meta.heading,
+    columns,
+    prefixes: meta.prefixes,
+    emptyMessage: `No ${meta.noun} entries found.`,
+    emptyHint,
+  };
+  return {
+    plain: (rows) => renderListPlain(rows, options),
+    llm: (rows) => renderListLlm(rows, options),
+    json: (rows) => JSON.stringify(rows, null, 2),
+  };
+}
+
+/** Build the shared per-entity render options for a lookup (reused by sample). */
+export function lookupOptions(
+  lookup: PackLookup,
+  prefixes: Readonly<Record<string, string>>,
+): RenderLookupOptions<PackEntity> {
+  const fields: LookupField<PackEntity>[] = (lookup.fields ?? []).map(
+    (field) => ({
+      label: field.label ?? field.name,
+      value: (entity) => entity[field.name],
+    }),
+  );
+  const flatSections: SectionDef<PackEntity>[] = (lookup.sections ?? []).map(
+    (section) => ({
+      key: section.name,
+      heading: section.label ?? section.name,
+      kind: section.kind ?? "field",
+    }),
+  );
+  const expandSections: SectionDef<PackEntity>[] = (lookup.expand ?? []).map(
+    (expand) => ({
+      key: expand.name,
+      heading: expand.heading ?? expand.name,
+      kind: expand.kind ?? "list",
+      ...(expand.showWhenEmpty ? { showWhenEmpty: true } : {}),
+    }),
+  );
+  return {
+    title: (entity) => scalar(entity.name) ?? scalar(entity.uri) ?? "(unnamed)",
+    fields,
+    sections: [...flatSections, ...expandSections],
+    prefixes,
+  };
+}
+
+/** Build the lookup formatters (renders every resolved entity, then any errors). */
+export function lookupFormatters(
+  lookup: PackLookup,
+  prefixes: Readonly<Record<string, string>>,
+): Formatters<LookupOutput> {
+  const options = lookupOptions(lookup, prefixes);
+  return {
+    plain: (output) =>
+      renderOutput(output, (entity) => renderLookupPlain(entity, options)),
+    llm: (output) =>
+      renderOutput(output, (entity) => renderLookupLlm(entity, options), "llm"),
+    json: (output) => JSON.stringify(output, null, 2),
+  };
+}
+
+/** Build the sample formatters (renders each exemplar, then the follow-ups). */
+export function sampleFormatters(
+  lookup: PackLookup,
+  noun: string,
+  prefixes: Readonly<Record<string, string>>,
+): Formatters<SampleOutput> {
+  const options = lookupOptions(lookup, prefixes);
+  return {
+    plain: (data) => {
+      const body = data.samples
+        .map((entity) => renderLookupPlain(entity, options))
+        .join("\n\n");
+      const steps = data.nextSteps.map((step) => `  - ${step}`).join("\n");
+      return `${noun} sample (${data.samples.length} of ${data.totalCount})\n\n${body}${
+        steps ? `\n\nNext steps:\n${steps}` : ""
+      }`.trimEnd();
+    },
+    llm: (data) => {
+      const body = data.samples
+        .map((entity) => renderLookupLlm(entity, options))
+        .join("\n\n");
+      const steps = data.nextSteps.map((step) => `- ${step}`).join("\n");
+      return `## ${capitalize(noun)} sample (${data.samples.length} of ${data.totalCount})\n\n${body}${
+        steps ? `\n\n### Next steps\n${steps}` : ""
+      }`.trimEnd();
+    },
+    json: (data) => JSON.stringify(data, null, 2),
+  };
+}
+
+/** Render each result entity, appending a compact note for any error entries. */
+function renderOutput(
+  output: LookupOutput,
+  render: (entity: PackEntity) => string,
+  mode: "plain" | "llm" = "plain",
+): string {
+  const bodies = output.results.map(render);
+  if (output.errors.length > 0) {
+    const bullet = mode === "llm" ? "- " : "  ";
+    const lines = output.errors.map(
+      (error) => `${bullet}${error.query}: ${error.message}`,
+    );
+    bodies.push(
+      `${mode === "llm" ? "### Not found" : "Not found:"}\n${lines.join("\n")}`,
+    );
+  }
+  return bodies.join("\n\n").trimEnd();
+}
+
+/** Return a value only when it is a scalar string (expands hold arrays). */
+function scalar(
+  value: string | readonly PackChildRow[] | undefined,
+): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}