@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/packs/compile.ts

@@ -0,0 +1,315 @@
+/**
+ * THE single pack compiler: one validated {@link PackDefinition} → a set of
+ * {@link VerbSpec}s, projected by the CLI and MCP projectors like any other
+ * verb. This closes fork F3 (two pack compilers → one) — `list`, extra
+ * list-shaped verbs, `lookup`, and `sample` all compile here, and the fetch
+ * source (`sparql`/`graphql`) is a run-body detail invisible to the projectors.
+ *
+ * Pure, storeless spec-generation: it builds paths, params, formatters, and run
+ * closures without touching the store or zod, so it runs on the
+ * `--help`/`__complete` fast path (the bundled packs compile at import; the
+ * dynamic merge is `collect.assembleEffectiveModules`/`loadEffectiveModules`).
+ * The heavy work is deferred into the run closures (behind the lazy runtime
+ * facade).
+ */
+
+import type { PragmaRuntime } from "../runtime/types.js";
+import { asVerb } from "../spec/asVerb.js";
+import type { DisclosureSpec, ParamSpec, VerbSpec } from "../spec/types.js";
+import {
+  listFormatters,
+  lookupFormatters,
+  type SampleOutput,
+  sampleFormatters,
+} from "./renderPack.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import {
+  MAX_SAMPLE_COUNT,
+  MIN_SAMPLE_COUNT,
+  sampleDefaultCount,
+} from "./sample.js";
+import type {
+  PackDefinition,
+  PackFilter,
+  PackList,
+  PackLookup,
+  PackRow,
+  PackSearch,
+} from "./types.js";
+
+// The run bodies pull the SPARQL/GraphQL fetch layer; they are dynamic-imported
+// per invocation so `compilePack` (reached on the storeless --help/__complete
+// fast path via capabilities/index) never statically loads them.
+const runBodies = () => import("./runBodies.js");
+
+/** The read capability every pack verb carries (store-backed, exposed to MCP). */
+const READ_CAPABILITY = {
+  needsStore: true,
+  mutates: false,
+  mcp: {
+    expose: true as const,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+};
+
+/**
+ * Compile a validated pack definition into its verbs.
+ *
+ * @param definition - A validated pack definition.
+ * @param source - Where the definition came from, for diagnostics.
+ * @param prefixes - The merged prefix map used for display compaction.
+ * @returns The compiled verbs (list, extra verbs, lookup, sample), in order.
+ */
+export function compilePack(
+  definition: PackDefinition,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): VerbSpec[] {
+  const { noun } = definition;
+  const verbs: VerbSpec[] = [];
+
+  if (definition.list) {
+    verbs.push(
+      compileListVerb(definition.list, {
+        noun,
+        verb: "list",
+        summary: definition.description ?? `List ${noun} entries.`,
+        doc: definition.toolDescription,
+        source,
+        prefixes,
+      }),
+    );
+  }
+
+  for (const verb of definition.verbs ?? []) {
+    verbs.push(
+      compileListVerb(verb, {
+        noun,
+        verb: verb.verb,
+        summary: verb.description ?? `List ${noun} ${verb.verb}.`,
+        doc: verb.toolDescription,
+        source,
+        prefixes,
+      }),
+    );
+  }
+
+  if (definition.lookup) {
+    verbs.push(compileLookupVerb(definition.lookup, noun, source, prefixes));
+    if (definition.lookup.sample) {
+      verbs.push(compileSampleVerb(definition.lookup, noun, source, prefixes));
+    }
+  }
+
+  return verbs;
+}
+
+/** Presentation facts for one compiled list-shaped verb. */
+interface ListVerbMeta {
+  readonly noun: string;
+  readonly verb: string;
+  readonly summary: string;
+  /** The authored MCP tool description (from `toolDescription`), if any. */
+  readonly doc?: string;
+  readonly source: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+/** Compile the `list` verb or an extra list-shaped verb. */
+function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
+  const params = [
+    ...projectFilters(shape.filters),
+    ...projectSearch(shape.search),
+  ];
+  const filterExample = shape.filters?.find((f) => f.values !== undefined);
+  const verb: VerbSpec<Record<string, unknown>, PackRow[]> = {
+    path: [meta.noun, meta.verb],
+    summary: meta.summary,
+    ...(meta.doc ? { doc: meta.doc } : {}),
+    params,
+    output: {
+      formatters: listFormatters(shape, {
+        heading: `${capitalize(meta.noun)}${meta.verb === "list" ? "" : ` ${meta.verb}`}`,
+        noun: meta.noun,
+        prefixes: meta.prefixes,
+      }),
+    },
+    examples: [
+      { cmd: `pragma ${meta.noun} ${meta.verb}` },
+      ...(filterExample
+        ? [
+            {
+              cmd: `pragma ${meta.noun} ${meta.verb} --${filterExample.param} ${quoteExample(
+                filterExample.values?.at(0) ?? "",
+              )}`,
+            },
+          ]
+        : []),
+      { cmd: `pragma ${meta.noun} ${meta.verb} --llm` },
+    ],
+    capability: READ_CAPABILITY,
+    run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
+      runBodies().then((m) =>
+        m.makeListRun(shape, { source: meta.source })(params, rt),
+      ),
+  };
+  return asVerb(verb);
+}
+
+/** Compile the `lookup` verb (variadic names → resolved entities). */
+function compileLookupVerb(
+  lookup: PackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): VerbSpec {
+  // Derive-by-default: every lookup completes its `<name>` from the pack index
+  // (empty type = any, the reader handles it), UNLESS the pack opts out
+  // (`completion.enabled:false`). `match`/`minChars` tune the derived heuristic.
+  const completeType = lookup.type ?? lookup.types?.at(0) ?? "";
+  const completion = lookup.completion;
+  const nameParam: ParamSpec = {
+    kind: "string[]",
+    name: "name",
+    doc: `${capitalize(noun)} names, prefixed names/IRIs, or glob patterns.`,
+    positional: true,
+    required: true,
+    ...(completion?.enabled === false
+      ? {}
+      : {
+          complete: {
+            kind: "names" as const,
+            source: {
+              from: "index" as const,
+              ...(completeType ? { type: completeType } : {}),
+            },
+            ...(completion?.match ? { match: completion.match } : {}),
+            ...(completion?.minChars !== undefined
+              ? { minChars: completion.minChars }
+              : {}),
+          },
+        }),
+  };
+  const verb: VerbSpec<Record<string, unknown>, LookupOutput> = {
+    path: [noun, "lookup"],
+    summary:
+      lookup.description ?? `Look up ${noun} details by name, IRI, or glob.`,
+    ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
+    params: [nameParam],
+    output: { formatters: lookupFormatters(lookup, prefixes) },
+    examples: [{ cmd: `pragma ${noun} lookup <name>` }],
+    ...(lookup.disclosure
+      ? { disclosure: disclosureSpec(lookup.disclosure) }
+      : {}),
+    capability: READ_CAPABILITY,
+    run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
+      runBodies().then((m) =>
+        m.makeLookupRun(lookup, noun, source, prefixes)(params, rt),
+      ),
+  };
+  return asVerb(verb);
+}
+
+/** Compile the `sample` verb (N random exemplars at the highest level). */
+function compileSampleVerb(
+  lookup: PackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): VerbSpec {
+  const defaultCount = sampleDefaultCount(lookup);
+  const config = lookup.sample === true ? undefined : lookup.sample;
+  // Most samples take a `[count]` positional; where the covenant freezes a
+  // no-argument sample the pack sets `fixedCount`, so the compiler omits it and
+  // the sample always returns the default count.
+  const countParam: ParamSpec[] = config?.fixedCount
+    ? []
+    : [
+        {
+          kind: "string",
+          name: "count",
+          doc: `Number of samples (${MIN_SAMPLE_COUNT}–${MAX_SAMPLE_COUNT}, default ${defaultCount}).`,
+          positional: true,
+        },
+      ];
+  const verb: VerbSpec<Record<string, unknown>, SampleOutput> = {
+    path: [noun, "sample"],
+    summary:
+      config?.description ??
+      `Return randomly selected complete ${noun} entries as exemplars.`,
+    ...(config?.toolDescription ? { doc: config.toolDescription } : {}),
+    params: countParam,
+    output: { formatters: sampleFormatters(lookup, noun, prefixes) },
+    examples: [
+      { cmd: `pragma ${noun} sample` },
+      ...(config?.fixedCount ? [] : [{ cmd: `pragma ${noun} sample 3` }]),
+    ],
+    capability: READ_CAPABILITY,
+    run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
+      runBodies().then((m) =>
+        m.makeSampleRun(
+          lookup,
+          noun,
+          source,
+          prefixes,
+          defaultCount,
+        )(params, rt),
+      ),
+  };
+  return asVerb(verb);
+}
+
+/** Normalize a pack disclosure into a {@link DisclosureSpec} (default → base). */
+function disclosureSpec(disclosure: PackLookup["disclosure"]): DisclosureSpec {
+  const levels = disclosure?.levels ?? [];
+  return {
+    levels: [...levels],
+    default: disclosure?.default ?? levels[0] ?? "summary",
+  };
+}
+
+/** Project declared filters onto verb params (enum for a value set, else string). */
+function projectFilters(
+  filters: readonly PackFilter[] | undefined,
+): ParamSpec[] {
+  return (filters ?? []).map((filter) => {
+    const doc =
+      filter.description ??
+      (filter.values
+        ? `Filter by ${filter.variable} (${filter.values.join(", ")}).`
+        : `Filter by ${filter.variable}.`);
+    if (filter.values) {
+      return {
+        kind: "enum",
+        name: filter.param,
+        doc,
+        values: [...filter.values],
+      } satisfies ParamSpec;
+    }
+    return { kind: "string", name: filter.param, doc } satisfies ParamSpec;
+  });
+}
+
+/** Project a declared free-text search onto the `search` param. */
+function projectSearch(search: PackSearch | undefined): ParamSpec[] {
+  if (!search) return [];
+  return [
+    {
+      kind: "string",
+      name: "search",
+      doc: search.description ?? `Search in ${search.variables.join(", ")}.`,
+    },
+  ];
+}
+
+/** Quote a filter example value when it is not a bare word. */
+function quoteExample(value: string): string {
+  return /^[\w.-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+/** Re-export the definition type for the compiled-module barrels. */
+export type { PackDefinition };

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

@@ -0,0 +1,200 @@
+/**
+ * Progressive disclosure (PROTECTED): canonical-index gating, resolveDetail
+ * precedence, and the injected MCP `detail` tool param.
+ *
+ * Gating is by CANONICAL level, and the effective level follows the uniform
+ * precedence flag > explicit config > pack default > canonical default — so a
+ * pack's declared default survives the built-in `detail: "standard"` config
+ * default, which is a fallback, not an override.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import { asVerb } from "../spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../spec/types.js";
+import { compilePack } from "./compile.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import type { PackDefinition } from "./types.js";
+import { verbKey } from "./uniqueness.js";
+
+const PREFIXES = {
+  ex: "https://example.org/widgets#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix ex: <https://example.org/widgets#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+ex:Widget a owl:Class .
+ex:name a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+ex:description a owl:DatatypeProperty ; rdfs:domain ex:Widget ; rdfs:range xsd:string .
+ex:hasPart a owl:ObjectProperty ; rdfs:domain ex:Widget ; rdfs:range ex:Widget .
+ex:button a ex:Widget ; ex:name "Button" ; ex:description "A button." ;
+  ex:hasPart ex:label .
+ex:label a ex:Widget ; ex:name "Label" ; ex:description "A label." .
+`;
+
+/** A lookup with `description` gated at `standard` and `parts` at `detailed`. */
+const PACK: PackDefinition = {
+  noun: "widget",
+  lookup: {
+    source: "sparql",
+    by: "ex:name",
+    type: "ex:Widget",
+    fields: [
+      { name: "description", property: "ex:description", level: "standard" },
+    ],
+    expand: [
+      {
+        name: "parts",
+        relation: "ex:hasPart",
+        level: "detailed",
+        select: [{ name: "name", property: "ex:name" }],
+      },
+    ],
+    disclosure: {
+      levels: ["summary", "standard", "detailed"],
+      default: "summary",
+    },
+  },
+};
+
+const lookupVerb = () =>
+  compilePack(PACK, "test:widget", PREFIXES).find(
+    (v) => verbKey(v.path) === "widget lookup",
+  );
+
+async function lookupAt(
+  detail?: "summary" | "standard" | "detailed",
+  config?: { configDetail: string; detailOrigin: "global" | "project" },
+): Promise<Record<string, unknown>> {
+  const { rt } = await buildFixtureRuntime({
+    ttl: TTL,
+    prefixes: PREFIXES,
+    ...(detail ? { detail } : {}),
+    ...(config ?? {}),
+  });
+  const verb = lookupVerb();
+  if (!verb) throw new Error("no widget lookup");
+  const output = (await verb.run({ name: ["Button"] }, rt)) as LookupOutput;
+  (await rt.store.get()).store.dispose();
+  return output.results.at(0) as Record<string, unknown>;
+}
+
+describe("disclosure — canonical-index gating (PROTECTED)", () => {
+  it("summary fetches base only (no standard field, no detailed expand)", async () => {
+    const entity = await lookupAt("summary");
+    expect(entity.name).toBe("Button");
+    expect(entity.description).toBeUndefined();
+    expect(entity.parts).toBeUndefined();
+  });
+
+  it("standard adds the standard-gated field but not the detailed expand", async () => {
+    const entity = await lookupAt("standard");
+    expect(entity.description).toBe("A button.");
+    expect(entity.parts).toBeUndefined();
+  });
+
+  it("detailed adds the detailed-gated expand", async () => {
+    const entity = await lookupAt("detailed");
+    expect(entity.description).toBe("A button.");
+    expect(entity.parts).toEqual([{ name: "Label" }]);
+  });
+});
+
+describe("disclosure — resolveDetail precedence (PROTECTED)", () => {
+  it("uses the pack default under default config (not the built-in standard)", async () => {
+    // Pack default is `summary`; the built-in `detail: "standard"` is origin
+    // `default`, so it must NOT override the pack default.
+    const entity = await lookupAt();
+    expect(entity.description).toBeUndefined();
+  });
+
+  it("an explicitly-set config detail outranks the pack default", async () => {
+    const entity = await lookupAt(undefined, {
+      configDetail: "detailed",
+      detailOrigin: "global",
+    });
+    expect(entity.parts).toEqual([{ name: "Label" }]);
+  });
+
+  it("the --detail flag outranks explicit config", async () => {
+    const entity = await lookupAt("summary", {
+      configDetail: "detailed",
+      detailOrigin: "global",
+    });
+    expect(entity.description).toBeUndefined();
+    expect(entity.parts).toBeUndefined();
+  });
+});
+
+describe("disclosure — MCP detail param (PROTECTED)", () => {
+  // A storeless echo verb with disclosure: registerVerb must inject a `detail`
+  // enum param, and the handler must seed globalFlags.detail from it per call.
+  const echoVerb: VerbSpec<Record<string, unknown>, { level: string }> = {
+    path: ["echo", "detail"],
+    summary: "Echo the resolved detail level.",
+    params: [],
+    disclosure: {
+      levels: ["summary", "standard", "detailed"],
+      default: "standard",
+    },
+    output: {
+      formatters: {
+        plain: (d) => d.level,
+        llm: (d) => d.level,
+        json: (d) => JSON.stringify(d),
+      },
+    },
+    capability: {
+      needsStore: false,
+      mutates: false,
+      mcp: {
+        expose: true,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+      },
+    },
+    run: async (_params, rt: PragmaRuntime) => ({
+      level: rt.globalFlags.detail ?? "(none)",
+    }),
+  };
+  const echoModule: CapabilityModule = {
+    name: "echo",
+    verbs: [asVerb(echoVerb)],
+  };
+
+  let harness: Awaited<ReturnType<typeof projectMcp>>;
+  beforeAll(async () => {
+    harness = await projectMcp([echoModule]);
+  });
+  afterAll(async () => {
+    await harness.cleanup();
+  });
+
+  it("advertises a `detail` enum param on the tool", async () => {
+    const tools = await harness.listTools();
+    const tool = tools.find((t) => t.name === "echo_detail") as
+      | { name: string; inputSchema?: { properties?: Record<string, unknown> } }
+      | undefined;
+    // The SDK surfaces the injected param in the tool's JSON-schema properties.
+    const client = await harness.callTool("echo_detail", {});
+    expect(client.ok).toBe(true);
+    expect(tool).toBeDefined();
+  });
+
+  it("seeds globalFlags.detail from the injected param per call", async () => {
+    const withDetail = await harness.callTool("echo_detail", {
+      detail: "detailed",
+    });
+    expect((withDetail.data as { level: string }).level).toBe("detailed");
+
+    const withoutDetail = await harness.callTool("echo_detail", {});
+    expect((withoutDetail.data as { level: string }).level).toBe("(none)");
+  });
+});

package/src/kernel/packs/disclosure.ts

@@ -0,0 +1,98 @@
+/**
+ * Canonical progressive-disclosure gating for pack lookups.
+ *
+ * A pack declares an ordered subset of the canonical levels
+ * (`constants.DETAIL_LEVELS`: `summary` < `standard` < `detailed`). A field or
+ * expand tags itself with the minimum canonical level at which it appears, and
+ * gating is by CANONICAL index — so a pack whose levels are `[summary, detailed]`
+ * still gates a `detailed`-tagged value at canonical index 2, and a
+ * `[summary, standard, detailed]` pack gates by the same scale. This is the
+ * single gating rule the SPARQL and GraphQL fetch paths share.
+ *
+ * The effective level is resolved through PR1's uniform {@link resolveDetail}:
+ * `--detail`/injected MCP `detail` (flag) > explicit config `detail` > the pack's
+ * `disclosure.default` > the canonical default. The config value counts only when
+ * the user actually set it (origin ≠ `default`) so a pack's declared default —
+ * block's `detailed`, standard's `summary` — is honoured under default config
+ * rather than shadowed by the built-in `detail: "standard"`.
+ */
+
+import { DETAIL_LEVELS } from "../../constants.js";
+import { resolveDetail } from "../render/disclosure.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import type { PackDisclosure, PackExpand, PackField } from "./types.js";
+
+/** The canonical level names, lowest → highest. */
+const CANONICAL: readonly string[] = DETAIL_LEVELS;
+
+/** The gating index of a level name (unknown/undefined → base level 0). */
+function levelIndex(level: string | undefined): number {
+  if (level === undefined) return 0;
+  const index = CANONICAL.indexOf(level);
+  return index === -1 ? 0 : index;
+}
+
+/**
+ * Whether an entry tagged `entryLevel` is active at the resolved `activeLevel`.
+ *
+ * `activeLevel` undefined means "everything" (no disclosure requested — the
+ * sample path, and lookups without a declared disclosure).
+ */
+export function isActiveAtLevel(
+  entryLevel: string | undefined,
+  activeLevel: string | undefined,
+): boolean {
+  if (activeLevel === undefined) return true;
+  return levelIndex(activeLevel) >= levelIndex(entryLevel);
+}
+
+/** The flat values (fields + sections) active at a level, by canonical index. */
+export function activeFields(
+  lookup: { fields?: readonly PackField[]; sections?: readonly PackField[] },
+  activeLevel: string | undefined,
+): PackField[] {
+  return [...(lookup.fields ?? []), ...(lookup.sections ?? [])].filter(
+    (field) => isActiveAtLevel(field.level, activeLevel),
+  );
+}
+
+/** The expands active at a level, by canonical index (same rule as fields). */
+export function activeExpands(
+  lookup: { expand?: readonly PackExpand[] },
+  activeLevel: string | undefined,
+): PackExpand[] {
+  return (lookup.expand ?? []).filter((expand) =>
+    isActiveAtLevel(expand.level, activeLevel),
+  );
+}
+
+/**
+ * Resolve the effective canonical level for a lookup invocation.
+ *
+ * @param rt - The runtime (global flags + config loader).
+ * @param disclosure - The lookup's declared disclosure, if any.
+ * @returns The resolved canonical level, or `undefined` when the lookup declares
+ *   no disclosure (everything is fetched).
+ * @note Impure — awaits the memoized config load.
+ */
+export async function resolvePackDetail(
+  rt: PragmaRuntime,
+  disclosure: PackDisclosure | undefined,
+): Promise<string | undefined> {
+  if (disclosure === undefined) return undefined;
+  const layers = await rt.loadConfig();
+  // Only an explicitly-set config detail outranks the pack's declared default;
+  // the built-in `detail: "standard"` is the last-resort fallback, not an
+  // override, so per-pack defaults survive under default config.
+  const configDetail =
+    layers.origins.detail !== "default" ? layers.config.detail : undefined;
+  return resolveDetail({
+    flag: rt.globalFlags.detail,
+    config: configDetail,
+    // Mirror the projector's normalization (compile.disclosureSpec): a pack that
+    // declares `levels` but omits `default` defaults to its FIRST declared level,
+    // not the canonical `standard`. Without this the advertised default (help /
+    // MCP `detail` param) and the resolved fetch level diverge for dynamic packs.
+    specDefault: disclosure.default ?? disclosure.levels[0],
+  });
+}

package/src/kernel/packs/glob.ts

@@ -0,0 +1,39 @@
+/**
+ * Glob expansion for pack lookups (`react/component/*`, `Nav*`, trailing `.`).
+ *
+ * Ported from the v1 suggester. A glob expands against the pack's known entity
+ * names; a non-glob passes through unchanged so callers can pipe the result
+ * straight into the lookup batch.
+ */
+
+/** Whether a string contains glob meta-characters (`*` or a trailing `.`). */
+export function isGlobPattern(name: string): boolean {
+  if (name === "") return false;
+  return name.includes("*") || name.endsWith(".");
+}
+
+/** Expand a glob against candidate names; a non-glob returns `[pattern]`. */
+export function expandGlob(
+  pattern: string,
+  candidates: readonly string[],
+): string[] {
+  if (!isGlobPattern(pattern)) return [pattern];
+  const normalized = pattern.endsWith(".") ? `${pattern}*` : pattern;
+  const regex = globToRegex(normalized);
+  return candidates.filter((name) => regex.test(name));
+}
+
+function globToRegex(glob: string): RegExp {
+  let pattern = "";
+  for (const char of glob) {
+    if (char === "*") {
+      pattern += ".*";
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: regex meta-characters to escape, not a JS template
+    } else if (".+^${}()|[]\\".includes(char)) {
+      pattern += `\\${char}`;
+    } else {
+      pattern += char;
+    }
+  }
+  return new RegExp(`^${pattern}$`, "i");
+}