@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/completion/rank.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { filterPrefix, MAX_CANDIDATES, rankCandidates } from "./rank.js";
+
+describe("rankCandidates (PROTECTED)", () => {
+  it("ranks exact > prefix > substring, case-insensitively", () => {
+    const candidates = ["abutton", "button-group", "Button", "chip"];
+    expect(rankCandidates(candidates, "button")).toEqual([
+      "Button",
+      "button-group",
+      "abutton",
+    ]);
+  });
+
+  it("breaks ties lexicographically within a strength band", () => {
+    expect(rankCandidates(["chip", "card", "candy"], "c")).toEqual([
+      "candy",
+      "card",
+      "chip",
+    ]);
+  });
+
+  it("dedupes candidates", () => {
+    expect(rankCandidates(["a", "a", "ab"], "a")).toEqual(["a", "ab"]);
+  });
+
+  it("lists the full set, sorted, for an empty partial", () => {
+    expect(rankCandidates(["b", "a", "c"], "")).toEqual(["a", "b", "c"]);
+  });
+
+  it("returns nothing when nothing matches", () => {
+    expect(rankCandidates(["alpha", "beta"], "zzz")).toEqual([]);
+  });
+
+  it("caps at MAX_CANDIDATES by default and honours a custom limit", () => {
+    const many = Array.from(
+      { length: 80 },
+      (_, i) => `name-${String(i).padStart(2, "0")}`,
+    );
+    expect(rankCandidates(many, "name").length).toBe(MAX_CANDIDATES);
+    expect(rankCandidates(many, "name", 3)).toEqual([
+      "name-00",
+      "name-01",
+      "name-02",
+    ]);
+  });
+
+  it("match=prefix rejects substring-only matches", () => {
+    const candidates = ["abutton", "button-group", "Button"];
+    // substring (default) keeps abutton; prefix drops it.
+    expect(rankCandidates(candidates, "button")).toContain("abutton");
+    expect(
+      rankCandidates(candidates, "button", MAX_CANDIDATES, "prefix"),
+    ).toEqual(["Button", "button-group"]);
+  });
+
+  it("match=fuzzy accepts an in-order subsequence, ranked lowest", () => {
+    const candidates = ["button", "bacon", "chip"];
+    // "bn" is a subsequence of button/bacon but a substring of neither.
+    expect(
+      rankCandidates(candidates, "bn", MAX_CANDIDATES, "substring"),
+    ).toEqual([]);
+    expect(
+      rankCandidates(candidates, "bn", MAX_CANDIDATES, "fuzzy").sort(),
+    ).toEqual(["bacon", "button"]);
+    // A prefix match still outranks a fuzzy subsequence.
+    expect(
+      rankCandidates(["breadcrumb", "button"], "bu", MAX_CANDIDATES, "fuzzy"),
+    ).toEqual(["button", "breadcrumb"]);
+  });
+
+  it("caseSensitive matches without folding case", () => {
+    const candidates = ["Button", "button-group"];
+    expect(
+      rankCandidates(candidates, "Bu", MAX_CANDIDATES, "substring", true),
+    ).toEqual(["Button"]);
+    expect(
+      rankCandidates(candidates, "bu", MAX_CANDIDATES, "substring", true),
+    ).toEqual(["button-group"]);
+  });
+});
+
+describe("filterPrefix (PROTECTED)", () => {
+  it("filters by case-sensitive prefix (agrees with compgen)", () => {
+    expect(filterPrefix(["config", "Config", "create"], "co")).toEqual([
+      "config",
+    ]);
+    expect(filterPrefix(["config", "Config"], "Co")).toEqual(["Config"]);
+  });
+
+  it("sorts and dedupes the matches", () => {
+    expect(filterPrefix(["beta", "alpha", "alpha"], "")).toEqual([
+      "alpha",
+      "beta",
+    ]);
+  });
+
+  it("returns nothing when nothing matches", () => {
+    expect(filterPrefix(["alpha"], "b")).toEqual([]);
+  });
+});

package/src/kernel/completion/rank.ts

@@ -0,0 +1,118 @@
+/**
+ * Candidate ranking and filtering for the completion tiers.
+ *
+ * Two disciplines, deliberately different:
+ * - {@link filterPrefix} for STRUCTURAL sets (nouns, verbs, flag names):
+ *   case-sensitive `startsWith` + lexicographic sort, agreeing with what the
+ *   static scripts' `compgen -W` would produce for the same table.
+ * - {@link rankCandidates} for VALUE sets (enum values, entity names):
+ *   case-insensitive exact > prefix > substring, deduped, tie-broken
+ *   lexicographically, capped — ported from the v1 `rankUriCompletions`.
+ */
+
+import type { CompletionMatch } from "../spec/types.js";
+
+/** Maximum candidates a ranked (value-tier) resolution returns. */
+export const MAX_CANDIDATES = 50;
+
+/** Match strength of a partial against one candidate, higher is better. */
+const NO_MATCH = 0;
+const FUZZY_MATCH = 1;
+const SUBSTRING_MATCH = 2;
+const PREFIX_MATCH = 3;
+const EXACT_MATCH = 4;
+
+/** Whether every char of `needle` appears in `hay`, in order (subsequence). */
+function isSubsequence(needle: string, hay: string): boolean {
+  if (needle === "") return true;
+  let i = 0;
+  for (const ch of hay) {
+    if (ch === needle[i] && ++i === needle.length) return true;
+  }
+  return false;
+}
+
+/**
+ * Score a folded candidate against a folded partial under a match strategy.
+ * `prefix` accepts only exact/prefix; `substring` (default) adds substring;
+ * `fuzzy` additionally accepts an in-order subsequence, ranked lowest.
+ */
+function score(
+  candidate: string,
+  partial: string,
+  match: CompletionMatch,
+): number {
+  if (candidate === partial) return EXACT_MATCH;
+  if (candidate.startsWith(partial)) return PREFIX_MATCH;
+  if (match === "prefix") return NO_MATCH;
+  if (candidate.includes(partial)) return SUBSTRING_MATCH;
+  if (match === "fuzzy" && isSubsequence(partial, candidate))
+    return FUZZY_MATCH;
+  return NO_MATCH;
+}
+
+/**
+ * Rank value candidates for a partial word.
+ *
+ * Exact > prefix > substring > fuzzy; ties broken by the candidate text for
+ * determinism; duplicates dropped; capped at `limit`. Case-insensitive by
+ * default (canonical casing is preserved in the emitted candidate — `bu` →
+ * `Button`). An empty partial matches everything (as a prefix), so it lists the
+ * full set sorted.
+ *
+ * @param candidates - The candidate values.
+ * @param partial - The partial word being completed.
+ * @param limit - Maximum candidates to return.
+ * @param match - Match strategy (default `"substring"`).
+ * @param caseSensitive - Match case-sensitively (default `false`).
+ * @returns Ranked, deduped, capped candidates (original casing preserved).
+ */
+export function rankCandidates(
+  candidates: readonly string[],
+  partial: string,
+  limit: number = MAX_CANDIDATES,
+  match: CompletionMatch = "substring",
+  caseSensitive: boolean = false,
+): string[] {
+  const fold = (value: string): string =>
+    caseSensitive ? value : value.toLowerCase();
+  const needle = fold(partial);
+
+  const scored: { candidate: string; strength: number }[] = [];
+  for (const candidate of candidates) {
+    const strength = score(fold(candidate), needle, match);
+    if (strength > NO_MATCH) scored.push({ candidate, strength });
+  }
+
+  scored.sort((a, b) =>
+    b.strength !== a.strength
+      ? b.strength - a.strength
+      : a.candidate.localeCompare(b.candidate),
+  );
+
+  const seen = new Set<string>();
+  const ranked: string[] = [];
+  for (const { candidate } of scored) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    ranked.push(candidate);
+    if (ranked.length >= limit) break;
+  }
+  return ranked;
+}
+
+/**
+ * Filter a structural set by a case-sensitive prefix.
+ *
+ * @param candidates - The structural candidates (nouns, verbs, flag names).
+ * @param partial - The partial word being completed.
+ * @returns The matches, deduped and sorted lexicographically.
+ */
+export function filterPrefix(
+  candidates: readonly string[],
+  partial: string,
+): string[] {
+  return [...new Set(candidates)]
+    .filter((candidate) => candidate.startsWith(partial))
+    .sort((a, b) => a.localeCompare(b));
+}

package/src/kernel/completion/resolve.test.ts

@@ -0,0 +1,204 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  completionFixture,
+  fixtureNameEnv,
+} from "../../testing/fixtures/completionFixture.js";
+import { buildCompletionModel } from "./model.js";
+import { parseWords } from "./parse.js";
+import { resolveRequest } from "./resolve.js";
+import type {
+  CompletionEnv,
+  CompletionRequest,
+  CompletionSource,
+} from "./types.js";
+
+const model = buildCompletionModel([completionFixture]);
+const env: CompletionEnv = fixtureNameEnv;
+const emptyEnv: CompletionEnv = { names: () => [] };
+
+/** A flag-value request with the given source and partial. */
+function valueRequest(
+  source: CompletionSource,
+  partial: string,
+): CompletionRequest {
+  return { context: { kind: "flag-value", flag: "--x", source }, partial };
+}
+
+/** Parse + resolve in one step against the fixture model. */
+async function complete(
+  words: readonly string[],
+  environment: CompletionEnv = env,
+): Promise<string[]> {
+  return resolveRequest(parseWords(words, model), model, environment);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+});
+
+describe("resolveRequest — structural contexts (PROTECTED)", () => {
+  it("resolves nouns by case-sensitive prefix", async () => {
+    await expect(complete(["blo"])).resolves.toEqual(["block"]);
+    await expect(complete([""])).resolves.toEqual([
+      "block",
+      "mcp",
+      "standard",
+      "status",
+    ]);
+    await expect(complete(["BLO"])).resolves.toEqual([]);
+  });
+
+  it("resolves verbs of the scanned noun", async () => {
+    await expect(complete(["block", ""])).resolves.toEqual([
+      "diff",
+      "get",
+      "list",
+      "remove",
+    ]);
+    await expect(complete(["block", "ge"])).resolves.toEqual(["get"]);
+  });
+
+  it("resolves flag names, deduped and sorted by prefix filter", async () => {
+    await expect(complete(["block", "get", "--v"])).resolves.toEqual([
+      "--verbose",
+      "--view",
+    ]);
+  });
+});
+
+describe("resolveRequest — source table (PROTECTED)", () => {
+  it("values: ranks the enum values", async () => {
+    await expect(
+      resolveRequest(
+        valueRequest({ kind: "values", values: ["anatomy", "full"] }, "a"),
+        model,
+        env,
+      ),
+    ).resolves.toEqual(["anatomy"]);
+    await expect(complete(["block", "get", "--view", ""])).resolves.toEqual([
+      "anatomy",
+      "full",
+      "summary",
+    ]);
+  });
+
+  it("names: ranks names from the source (exact > prefix > substring)", async () => {
+    await expect(complete(["block", "get", "button"])).resolves.toEqual([
+      "button",
+      "button-group",
+    ]);
+    await expect(complete(["block", "get", "tool"])).resolves.toEqual([
+      "tooltip",
+    ]);
+  });
+
+  it("names: emits canonical casing and honors the source's match", async () => {
+    const namesSource = (
+      over: Partial<Extract<CompletionSource, { kind: "names" }>> = {},
+    ): CompletionSource => ({
+      kind: "names",
+      ref: { from: "index" },
+      match: "substring",
+      caseSensitive: false,
+      ...over,
+    });
+    const canonEnv: CompletionEnv = { names: () => ["Button", "abutton"] };
+    // Case-insensitive match, canonical casing preserved (`bu` → `Button`).
+    await expect(
+      resolveRequest(valueRequest(namesSource(), "bu"), model, canonEnv),
+    ).resolves.toEqual(["Button", "abutton"]);
+    // A prefix-match source drops the substring-only candidate.
+    await expect(
+      resolveRequest(
+        valueRequest(namesSource({ match: "prefix" }), "bu"),
+        model,
+        canonEnv,
+      ),
+    ).resolves.toEqual(["Button"]);
+  });
+
+  it("names: supports async sources", async () => {
+    const asyncEnv: CompletionEnv = {
+      names: async () => ["alpha", "beta"],
+    };
+    await expect(complete(["block", "get", "al"], asyncEnv)).resolves.toEqual([
+      "alpha",
+    ]);
+  });
+
+  it("names: the empty source (the default) yields zero candidates", async () => {
+    await expect(complete(["block", "get", ""], emptyEnv)).resolves.toEqual([]);
+  });
+
+  it("names: a throwing source degrades to zero candidates", async () => {
+    const hostileEnv: CompletionEnv = {
+      names: () => {
+        throw new Error("boom");
+      },
+    };
+    await expect(complete(["block", "get", ""], hostileEnv)).resolves.toEqual(
+      [],
+    );
+  });
+
+  it("files: resolves to nothing (native shell completion owns it)", async () => {
+    await expect(complete(["block", "get", "--out", ""])).resolves.toEqual([]);
+  });
+
+  it("none: resolves to nothing", async () => {
+    await expect(complete(["block", "get", "--note", ""])).resolves.toEqual([]);
+    await expect(complete(["block", "remove", ""])).resolves.toEqual([]);
+  });
+
+  it("reserved/unknown source kinds resolve to nothing with a reason", async () => {
+    vi.stubEnv("PRAGMA_COMPLETE_DEBUG", "1");
+    const write = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const reserved = { kind: "query" } as unknown as CompletionSource;
+    await expect(
+      resolveRequest(valueRequest(reserved, ""), model, env),
+    ).resolves.toEqual([]);
+    expect(write).toHaveBeenCalledWith(
+      expect.stringContaining('reserved completion kind "query"'),
+    );
+  });
+
+  it("caps ranked candidates at 50", async () => {
+    const bigEnv: CompletionEnv = {
+      names: () =>
+        Array.from(
+          { length: 80 },
+          (_, i) => `name-${String(i).padStart(2, "0")}`,
+        ),
+    };
+    const matches = await complete(["block", "get", "name"], bigEnv);
+    expect(matches.length).toBe(50);
+  });
+
+  it("returns nothing when nothing matches", async () => {
+    await expect(complete(["block", "get", "--view", "zzz"])).resolves.toEqual(
+      [],
+    );
+  });
+});
+
+describe("resolveRequest — nothing contexts (PROTECTED)", () => {
+  it("resolves nothing for unknown nouns/verbs and exhausted positionals", async () => {
+    await expect(complete(["bogus", ""])).resolves.toEqual([]);
+    await expect(complete(["block", "zap", ""])).resolves.toEqual([]);
+    await expect(complete(["block", "get", "button", ""])).resolves.toEqual([]);
+  });
+
+  it("logs the nothing reason on the debug channel", async () => {
+    vi.stubEnv("PRAGMA_COMPLETE_DEBUG", "1");
+    const write = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    await complete(["bogus", ""]);
+    expect(write).toHaveBeenCalledWith(
+      expect.stringContaining("nothing: unknown noun"),
+    );
+  });
+});

package/src/kernel/completion/resolve.ts

@@ -0,0 +1,133 @@
+/**
+ * Resolve a classified completion request into candidates.
+ *
+ * Structural contexts (noun, verb, flag-name) filter their model-derived
+ * tables with the case-sensitive {@link filterPrefix} — the same offers the
+ * static scripts inline. Value contexts (flag-value, positional) go through
+ * the source table: enum values and entity names are ranked case-insensitively
+ * and capped; `files` returns nothing (the static scripts complete files
+ * natively — the resolver never lists the filesystem); `none` and unknown
+ * (reserved) kinds return nothing.
+ *
+ * Injection safety, runtime gate: every value-tier candidate must match the
+ * same {@link SAFE_TOKEN_RE} allowlist the emit-time gate enforces — hostile
+ * names from an index file are dropped before they can reach a shell buffer.
+ * Structural candidates were already asserted safe when the model was built.
+ */
+
+import { findNoun, SAFE_TOKEN_RE } from "./model.js";
+import { filterPrefix, MAX_CANDIDATES, rankCandidates } from "./rank.js";
+import type {
+  CompletionEnv,
+  CompletionModel,
+  CompletionRequest,
+  CompletionSource,
+} from "./types.js";
+
+/**
+ * Write a completion debug line to stderr when `PRAGMA_COMPLETE_DEBUG=1`.
+ * Silent otherwise — stdout is reserved for candidates, and stderr must not
+ * leak into shell buffers during normal completion.
+ *
+ * @param message - The debug message (prefixed with `[complete]`).
+ * @note Impure — reads the environment, writes stderr.
+ */
+export function completionDebug(message: string): void {
+  if (process.env.PRAGMA_COMPLETE_DEBUG === "1") {
+    process.stderr.write(`[complete] ${message}\n`);
+  }
+}
+
+/** Drop candidates that fail the shell-safety allowlist (with a debug note). */
+function sanitize(candidates: readonly string[]): readonly string[] {
+  const safe = candidates.filter((candidate) => SAFE_TOKEN_RE.test(candidate));
+  if (safe.length !== candidates.length) {
+    completionDebug(
+      `dropped ${candidates.length - safe.length} unsafe candidate(s)`,
+    );
+  }
+  return safe;
+}
+
+/** Resolve a value-tier source into ranked, sanitized candidates. */
+async function resolveSource(
+  source: CompletionSource,
+  partial: string,
+  env: CompletionEnv,
+): Promise<string[]> {
+  switch (source.kind) {
+    case "values":
+      return rankCandidates(sanitize(source.values), partial);
+    case "names": {
+      let names: readonly string[];
+      try {
+        names = await env.names(source.ref);
+      } catch (error) {
+        // The seam contract is never-throw; degrade anyway, never break TAB.
+        completionDebug(
+          `name source read failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return [];
+      }
+      return rankCandidates(
+        sanitize(names),
+        partial,
+        MAX_CANDIDATES,
+        source.match,
+        source.caseSensitive,
+      );
+    }
+    case "files":
+      // Consumer rule: files are completed natively by the shell scripts
+      // (compgen -f / _files / fish -rF); the resolver offers nothing.
+      return [];
+    case "none":
+      return [];
+    default: {
+      // Reserved kinds ({kind:"query"} and future ones) are not in the union;
+      // if one arrives at runtime it resolves to nothing, with a reason.
+      const kind = (source as { kind: string }).kind;
+      completionDebug(`nothing: reserved completion kind "${kind}"`);
+      return [];
+    }
+  }
+}
+
+/**
+ * Resolve a parsed completion request against the model and environment.
+ *
+ * @param request - The classified context plus partial from `parseWords`.
+ * @param model - The completion model.
+ * @param env - The completion environment (the entity seam).
+ * @returns Matching candidates, ranked/filtered per tier; `[]` when there is
+ *   nothing to offer.
+ */
+export async function resolveRequest(
+  request: CompletionRequest,
+  model: CompletionModel,
+  env: CompletionEnv,
+): Promise<string[]> {
+  const { context, partial } = request;
+  switch (context.kind) {
+    case "noun":
+      return filterPrefix(
+        model.nouns.map((entry) => entry.noun),
+        partial,
+      );
+    case "verb": {
+      const noun = findNoun(model, context.noun);
+      return filterPrefix(
+        (noun?.verbs ?? []).map((verb) => verb.label),
+        partial,
+      );
+    }
+    case "flag-name":
+      return filterPrefix(context.flags, partial);
+    case "flag-value":
+    case "positional":
+      return resolveSource(context.source, partial, env);
+    case "nothing":
+      completionDebug(`nothing: ${context.reason}`);
+      return [];
+  }
+}