@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/packs/resolveEntity.ts

@@ -0,0 +1,232 @@
+/**
+ * Look up one or more pack entities by name, prefixed name, absolute IRI, or
+ * glob, via the fetch strategy the pack declares.
+ *
+ * The name→URI resolve is ALWAYS generated SPARQL (an escaped literal or a
+ * validated `<iri>` BIND) regardless of `source`; from the resolved IRI, values
+ * are fetched either through more generated SELECTs (`sparql`) or one generated
+ * GraphQL document (`graphql`). One poisoned query never discards the batch —
+ * per-query failures are collected as structured error entries.
+ *
+ * Reached only behind a dynamic import from the lookup run body, so its imports
+ * (including the GraphQL path) stay off the storeless fast path.
+ */
+
+import { PragmaError } from "../error/PragmaError.js";
+import { suggestNames } from "../project/cli/suggestNames.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import { activeExpands } from "./disclosure.js";
+import { expandGlob, isGlobPattern } from "./glob.js";
+import { fetchGraphqlLookup } from "./graphql/fetchGraphqlLookup.js";
+import { isEmbeddableIri, resolveUri } from "./iri.js";
+import {
+  buildExpandQuery,
+  buildLookupByIriQuery,
+  buildLookupNamesQuery,
+  buildLookupQuery,
+  buildNameResolveQuery,
+} from "./sparql/buildLookupQuery.js";
+import { runSelect } from "./sparql/runSelect.js";
+import type { PackChildRow, PackEntity, PackLookup } from "./types.js";
+
+/** A structured per-query lookup failure (never rejects the whole batch). */
+export interface LookupError {
+  readonly query: string;
+  readonly code: string;
+  readonly message: string;
+  readonly suggestions?: readonly string[];
+}
+
+/** The result of a (possibly multi-name) lookup. */
+export interface LookupOutput {
+  readonly results: PackEntity[];
+  readonly errors: LookupError[];
+}
+
+/** What the resolver needs from the runtime: the store + the query facade. */
+type LookupRuntime = Pick<PragmaRuntime, "store" | "query">;
+
+/**
+ * Resolve a batch of lookup queries, collecting per-query failures.
+ *
+ * @throws PragmaError INVALID_INPUT when the batch is empty.
+ */
+export async function resolveLookup(
+  rt: LookupRuntime,
+  lookup: PackLookup,
+  noun: string,
+  queries: readonly string[],
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+  level: string | undefined,
+): Promise<LookupOutput> {
+  if (queries.length === 0) {
+    throw PragmaError.invalidInput("names", "(empty)", {
+      recovery: {
+        message: `List available ${noun} entries.`,
+        cli: `pragma ${noun} list`,
+        mcp: { tool: `${noun}_list` },
+      },
+    });
+  }
+
+  const expanded = await expandQueries(rt, lookup, noun, source, queries);
+  const results: PackEntity[] = [];
+  const errors: LookupError[] = [...expanded.globErrors];
+  const settled = await Promise.allSettled(
+    expanded.names.map((query) =>
+      lookupOne(rt, lookup, noun, query, source, prefixes, level),
+    ),
+  );
+  for (const [index, outcome] of settled.entries()) {
+    const query = expanded.names[index];
+    if (query === undefined) continue;
+    if (outcome.status === "fulfilled") {
+      results.push(outcome.value);
+      continue;
+    }
+    const error = outcome.reason;
+    if (error instanceof PragmaError) {
+      errors.push({
+        query,
+        code: error.code,
+        message: error.message,
+        ...(error.suggestions.length > 0
+          ? { suggestions: error.suggestions }
+          : {}),
+      });
+    } else {
+      errors.push({
+        query,
+        code: "INTERNAL_ERROR",
+        message: `Internal error: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  }
+  return { results, errors };
+}
+
+/** Expand glob queries against the entity name list; literals pass through. */
+async function expandQueries(
+  rt: LookupRuntime,
+  lookup: PackLookup,
+  noun: string,
+  source: string,
+  queries: readonly string[],
+): Promise<{ names: string[]; globErrors: LookupError[] }> {
+  if (!queries.some(isGlobPattern))
+    return { names: [...queries], globErrors: [] };
+  const allNames = await listEntityNames(rt, lookup, source);
+  const names: string[] = [];
+  const globErrors: LookupError[] = [];
+  for (const query of queries) {
+    if (!isGlobPattern(query)) {
+      names.push(query);
+      continue;
+    }
+    const matches = expandGlob(query, allNames);
+    if (matches.length === 0) {
+      globErrors.push({
+        query,
+        code: "EMPTY_RESULTS",
+        message: `No ${noun} entries matching "${query}".`,
+      });
+    } else {
+      names.push(...matches);
+    }
+  }
+  return { names, globErrors };
+}
+
+/** Look up one entity, dispatching to the pack's declared fetch source. */
+async function lookupOne(
+  rt: LookupRuntime,
+  lookup: PackLookup,
+  noun: string,
+  query: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+  level: string | undefined,
+): Promise<PackEntity> {
+  const graphqlSourced = lookup.source === "graphql";
+  const rows = await runSelect(
+    rt,
+    graphqlSourced
+      ? buildNameResolveQuery(lookup, query)
+      : buildEntityQuery(lookup, query, prefixes, level),
+    source,
+  );
+  const base = rows.at(0);
+  if (!base?.uri) {
+    const candidates = await listEntityNames(rt, lookup, source);
+    throw PragmaError.notFound(noun, query, {
+      suggestions: suggestNames(query, candidates),
+      recovery: {
+        message: `List available ${noun} entries.`,
+        cli: `pragma ${noun} list`,
+        mcp: { tool: `${noun}_list` },
+      },
+    });
+  }
+
+  if (graphqlSourced) {
+    return fetchGraphqlLookup(
+      rt,
+      lookup,
+      base.uri,
+      base.name ?? query,
+      source,
+      prefixes,
+      level,
+    );
+  }
+
+  const entity: PackEntity = { ...base };
+  for (const expand of activeExpands(lookup, level)) {
+    entity[expand.name] = (await runSelect(
+      rt,
+      buildExpandQuery(expand, base.uri),
+      source,
+    )) as readonly PackChildRow[];
+  }
+  return entity;
+}
+
+/** Build the base entity SELECT for the SPARQL path (name or IRI form). */
+function buildEntityQuery(
+  lookup: PackLookup,
+  query: string,
+  prefixes: Readonly<Record<string, string>>,
+  level: string | undefined,
+): string {
+  if (!looksLikeIri(query)) return buildLookupQuery(lookup, query, level);
+  const resolved = resolveUri(query, prefixes);
+  if (!isEmbeddableIri(resolved)) {
+    throw PragmaError.invalidInput("name", query, {
+      recovery: {
+        message:
+          "Use an absolute IRI (https://…), a prefixed name (ds:thing), or a plain entity name.",
+      },
+    });
+  }
+  return buildLookupByIriQuery(lookup, resolved, level);
+}
+
+/** Whether a lookup query addresses an entity by IRI or prefixed name. */
+function looksLikeIri(query: string): boolean {
+  return (
+    query.startsWith("http://") ||
+    query.startsWith("https://") ||
+    query.includes(":")
+  );
+}
+
+/** List every entity name the lookup can address (miss suggestions + sample/glob). */
+export async function listEntityNames(
+  rt: LookupRuntime,
+  lookup: PackLookup,
+  source: string,
+): Promise<string[]> {
+  const rows = await runSelect(rt, buildLookupNamesQuery(lookup), source);
+  return rows.map((row) => row.name ?? "").filter((name) => name !== "");
+}

package/src/kernel/packs/runBodies.ts

@@ -0,0 +1,157 @@
+/**
+ * The shared run bodies a compiled pack verb closes over.
+ *
+ * Each factory returns a `VerbSpec.run` closure. Reads are plain async: the list
+ * body runs the pack's SELECT then applies post-query filters/search; the lookup
+ * body resolves names → IRIs and fetches per the declared source, gated by the
+ * resolved disclosure level; the sample body draws N random entities at the
+ * highest level. All store access is through the runtime facade (lazy), so these
+ * factories carry no heavy static import.
+ */
+
+import { PragmaError } from "../error/PragmaError.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import { resolvePackDetail } from "./disclosure.js";
+import type { SampleOutput } from "./renderPack.js";
+import {
+  type LookupOutput,
+  listEntityNames,
+  resolveLookup,
+} from "./resolveEntity.js";
+import { parseSampleCount, pickRandom } from "./sample.js";
+import { applyPackFilters } from "./sparql/applyFilters.js";
+import { applyPackSearch } from "./sparql/applySearch.js";
+import { runSelect } from "./sparql/runSelect.js";
+import type { PackList, PackLookup, PackRow } from "./types.js";
+
+/** The highest canonical level — sample fetches everything for shape discovery. */
+const HIGHEST_LEVEL = "detailed";
+
+/** Facts a list-shaped run body needs beyond its `shape`. */
+export interface ListRunMeta {
+  readonly source: string;
+}
+
+/**
+ * Build the run body for a list-shaped verb (`list` or an extra verb).
+ *
+ * Zero rows is a plain empty list — a SUCCESS, not an error. It returns `[]`
+ * (JSON stays `[]`, exit 0); the formatter turns the emptiness into a non-blank
+ * message (a pack's `emptyRecovery` becomes that message's hint). Routing zero
+ * results through EMPTY_RESULTS would map to exit 1 and break the uniform
+ * `ok:true` list contract, so the run body never throws on emptiness.
+ */
+export function makeListRun(
+  shape: PackList,
+  meta: ListRunMeta,
+): (params: Record<string, unknown>, rt: PragmaRuntime) => Promise<PackRow[]> {
+  return async (params, rt) =>
+    applyPackSearch(
+      applyPackFilters(
+        await runSelect(rt, shape.query, meta.source),
+        shape.filters,
+        params,
+      ),
+      shape.search,
+      params,
+    );
+}
+
+/** Build the run body for a lookup verb (variadic names → resolved entities). */
+export function makeLookupRun(
+  lookup: PackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): (
+  params: Record<string, unknown>,
+  rt: PragmaRuntime,
+) => Promise<LookupOutput> {
+  return async (params, rt) => {
+    const names = readNames(params);
+    const level = await resolvePackDetail(rt, lookup.disclosure);
+    const output = await resolveLookup(
+      rt,
+      lookup,
+      noun,
+      names,
+      source,
+      prefixes,
+      level,
+    );
+    // A total miss (single or all-miss) exits non-zero; a partial batch renders
+    // the results it found and notes the misses.
+    if (output.results.length === 0 && output.errors.length > 0) {
+      const first = output.errors[0];
+      if (first) {
+        throw new PragmaError({
+          code: first.code as PragmaError["code"],
+          message: first.message,
+          suggestions: first.suggestions ? [...first.suggestions] : undefined,
+          recovery: {
+            message: `List available ${noun} entries.`,
+            cli: `pragma ${noun} list`,
+            mcp: { tool: `${noun}_list` },
+          },
+        });
+      }
+    }
+    return output;
+  };
+}
+
+/** Build the run body for a sample verb (N random entities at the highest level). */
+export function makeSampleRun(
+  lookup: PackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+  defaultCount: number,
+): (
+  params: Record<string, unknown>,
+  rt: PragmaRuntime,
+) => Promise<SampleOutput> {
+  return async (params, rt) => {
+    const count = parseSampleCount(params.count ?? defaultCount);
+    const names = await listEntityNames(rt, lookup, source);
+    // An empty population is a clean EMPTY_RESULTS (nothing to sample), not the
+    // "(empty)" INVALID_INPUT resolveLookup would raise on a zero-length batch.
+    if (names.length === 0) {
+      throw PragmaError.emptyResults(noun, {
+        message: `No ${noun} entries to sample.`,
+        recovery: {
+          message: `List available ${noun} entries.`,
+          cli: `pragma ${noun} list`,
+          mcp: { tool: `${noun}_list` },
+        },
+      });
+    }
+    const selected = pickRandom(names, count);
+    const output = await resolveLookup(
+      rt,
+      lookup,
+      noun,
+      selected,
+      source,
+      prefixes,
+      HIGHEST_LEVEL,
+    );
+    return {
+      samples: output.results,
+      totalCount: names.length,
+      nextSteps: [
+        `These are ${output.results.length} of ${names.length} total ${noun} entries.`,
+        `Use ${noun}_lookup to inspect specific entries by name.`,
+        `Use ${noun}_list to browse all entries.`,
+      ],
+    };
+  };
+}
+
+/** Read the variadic `name` positional as a string array. */
+function readNames(params: Record<string, unknown>): string[] {
+  const raw = params.name;
+  if (Array.isArray(raw))
+    return raw.filter((n): n is string => typeof n === "string");
+  return typeof raw === "string" ? [raw] : [];
+}

package/src/kernel/packs/sample.ts

@@ -0,0 +1,60 @@
+/**
+ * Sample-count parsing and uniform random selection for the `sample` verb.
+ *
+ * Ported from the v1 shared helpers: a missing count falls back to the default,
+ * a non-integer is rejected as invalid input, and a valid integer is clamped to
+ * the supported 1–5 range. Selection is a Fisher-Yates partial shuffle.
+ */
+
+import { PragmaError } from "../error/PragmaError.js";
+import type { PackLookup } from "./types.js";
+
+/** Smallest number of samples the `sample` verb returns. */
+export const MIN_SAMPLE_COUNT = 1;
+/** Largest number of samples the `sample` verb returns. */
+export const MAX_SAMPLE_COUNT = 5;
+/** Number of samples returned when the count is omitted. */
+export const DEFAULT_SAMPLE_COUNT = 2;
+
+/** The default sample count a lookup declares, or the built-in default. */
+export function sampleDefaultCount(lookup: PackLookup): number {
+  const sample = lookup.sample;
+  if (sample && sample !== true && typeof sample.count === "number") {
+    return sample.count;
+  }
+  return DEFAULT_SAMPLE_COUNT;
+}
+
+/**
+ * Resolve the raw `count` arg into a clamped sample count.
+ *
+ * @throws PragmaError INVALID_INPUT when `raw` is present but not an integer.
+ */
+export function parseSampleCount(raw: unknown): number {
+  if (raw === undefined || raw === null || raw === "") {
+    return DEFAULT_SAMPLE_COUNT;
+  }
+  const text = String(raw).trim();
+  if (!/^-?\d+$/.test(text)) {
+    throw PragmaError.invalidInput("count", String(raw), {
+      recovery: {
+        message: `Provide an integer between ${MIN_SAMPLE_COUNT} and ${MAX_SAMPLE_COUNT}.`,
+      },
+    });
+  }
+  return Math.max(MIN_SAMPLE_COUNT, Math.min(MAX_SAMPLE_COUNT, Number(text)));
+}
+
+/** Pick `count` random items without replacement (Fisher-Yates partial shuffle). */
+export function pickRandom<T>(arr: readonly T[], count: number): T[] {
+  const n = Math.min(count, arr.length);
+  if (n === 0) return [];
+  const copy = [...arr];
+  for (let i = 0; i < n; i++) {
+    const j = i + Math.floor(Math.random() * (copy.length - i));
+    const tmp = copy[i] as T;
+    copy[i] = copy[j] as T;
+    copy[j] = tmp;
+  }
+  return copy.slice(0, n);
+}