@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/shared/loaders/readPackageDir.ts

@@ -1,185 +0,0 @@
-/**
- * Read semantic content from a package directory on disk.
- *
- * Shared by LocalLoader and GitLoader. Given a directory path, reads
- * package.json for version, globs TTL files from definitions/ and data/,
- * and scans skills/ for subdirectories.
- *
- * @note Impure — reads filesystem.
- */
-
-import {
-  existsSync,
-  globSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-} from "node:fs";
-import { join } from "node:path";
-import type {
-  GraphContent,
-  SkillEntry,
-  StoryFileEntry,
-} from "../semanticPackage.js";
-
-// ---------------------------------------------------------------------------
-// TTL discovery convention
-// ---------------------------------------------------------------------------
-
-const TTL_DIRS: readonly { dir: string; glob: string }[] = [
-  { dir: "definitions", glob: "definitions/**/*.ttl" },
-  { dir: "data", glob: "data/**/*.ttl" },
-];
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export interface PackageDirContents {
-  readonly version: string;
-  readonly graphs: GraphContent[];
-  readonly prefixes?: Readonly<Record<string, string>>;
-  readonly skills: SkillEntry[];
-  readonly stories: StoryFileEntry[];
-}
-
-/**
- * Read semantic package content from a directory.
- *
- * @param dir - Absolute path to the package root directory.
- * @returns Package version, TTL graph content, declared prefixes, and skills.
- */
-export default function readPackageDir(dir: string): PackageDirContents {
-  const manifest = readManifest(dir);
-  const prefixes = parsePrefixesField(manifest);
-  return {
-    version: typeof manifest.version === "string" ? manifest.version : "0.0.0",
-    graphs: readGraphs(dir),
-    ...(prefixes ? { prefixes } : {}),
-    skills: readSkills(dir),
-    stories: readStories(dir),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** A package.json shape with the fields this loader reads. */
-interface PackageManifest {
-  readonly version?: unknown;
-  readonly pragma?: unknown;
-}
-
-/** Read and parse `package.json`, returning an empty object on failure. */
-function readManifest(dir: string): PackageManifest {
-  try {
-    return JSON.parse(
-      readFileSync(join(dir, "package.json"), "utf-8"),
-    ) as PackageManifest;
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Extract package-declared prefixes from a parsed manifest.
- *
- * Convention: a package declares its namespaces under
- * `pragma.prefixes` in `package.json`, e.g.
- * `{ "pragma": { "prefixes": { "ds": "https://ds.canonical.com/" } } }`.
- * Chosen over a separate file because the manifest is already read for the
- * version, keeping the convention zero-extra-file and discoverable. Only
- * string→string entries are kept; malformed shapes are ignored so one bad
- * field cannot break boot.
- *
- * @returns The declared prefix map, or `undefined` when none is present.
- */
-function parsePrefixesField(
-  manifest: PackageManifest,
-): Readonly<Record<string, string>> | undefined {
-  const pragma = manifest.pragma;
-  if (typeof pragma !== "object" || pragma === null) return undefined;
-  const raw = (pragma as { prefixes?: unknown }).prefixes;
-  if (typeof raw !== "object" || raw === null) return undefined;
-
-  const prefixes: Record<string, string> = {};
-  for (const [name, namespace] of Object.entries(raw)) {
-    if (typeof namespace === "string") prefixes[name] = namespace;
-  }
-  return Object.keys(prefixes).length > 0 ? prefixes : undefined;
-}
-
-function readGraphs(dir: string): GraphContent[] {
-  const graphs: GraphContent[] = [];
-
-  for (const entry of TTL_DIRS) {
-    if (!existsSync(join(dir, entry.dir))) continue;
-
-    const files = globSync(entry.glob, { cwd: dir });
-    for (const file of files) {
-      const absPath = join(dir, file);
-      try {
-        const content = readFileSync(absPath, "utf-8");
-        graphs.push({ path: absPath, content, format: "turtle" });
-      } catch {
-        // Unreadable file — skip silently
-      }
-    }
-  }
-
-  return graphs;
-}
-
-function readStories(dir: string): StoryFileEntry[] {
-  const storiesDir = join(dir, "stories");
-  if (!existsSync(storiesDir)) return [];
-
-  const stories: StoryFileEntry[] = [];
-  try {
-    // Sorted: readdir order is filesystem-dependent, and story collision
-    // resolution must be deterministic across platforms.
-    for (const entry of [...readdirSync(storiesDir)].sort()) {
-      if (!entry.endsWith(".json")) continue;
-      const entryPath = join(storiesDir, entry);
-      try {
-        stories.push({
-          path: entryPath,
-          definition: JSON.parse(readFileSync(entryPath, "utf-8")),
-        });
-      } catch {
-        process.stderr.write(
-          `Warning: invalid JSON in story file ${entryPath}\n`,
-        );
-      }
-    }
-  } catch {
-    // readdir failed — no stories
-  }
-
-  return stories;
-}
-
-function readSkills(dir: string): SkillEntry[] {
-  const skillsDir = join(dir, "skills");
-  if (!existsSync(skillsDir)) return [];
-
-  const skills: SkillEntry[] = [];
-  try {
-    const entries = readdirSync(skillsDir);
-    for (const entry of entries) {
-      const entryPath = join(skillsDir, entry);
-      try {
-        if (statSync(entryPath).isDirectory()) {
-          skills.push({ dir: entryPath, folderName: entry });
-        }
-      } catch {
-        // stat failed — skip
-      }
-    }
-  } catch {
-    // readdir failed — no skills
-  }
-
-  return skills;
-}

package/src/domains/shared/loaders/storyAssetsPlugin.test.ts

@@ -1,84 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { BunPlugin } from "bun";
-import { afterEach, describe, expect, it } from "vitest";
-import createStoryAssetsPlugin, {
-  STORY_ASSET_PATH_PATTERN,
-} from "./storyAssetsPlugin.js";
-
-interface OnLoadRegistration {
-  readonly filter: RegExp;
-  readonly callback: (args: { path: string }) => unknown;
-}
-
-/** Run the plugin's setup against a stub builder and capture its onLoad. */
-function captureOnLoadRegistration(): OnLoadRegistration {
-  let captured: OnLoadRegistration | undefined;
-  const builder = {
-    onLoad(
-      constraints: { filter: RegExp },
-      callback: OnLoadRegistration["callback"],
-    ): void {
-      captured = { filter: constraints.filter, callback };
-    },
-  };
-
-  createStoryAssetsPlugin().setup(
-    builder as unknown as Parameters<BunPlugin["setup"]>[0],
-  );
-
-  if (!captured) throw new Error("plugin did not register an onLoad handler");
-  return captured;
-}
-
-describe("STORY_ASSET_PATH_PATTERN", () => {
-  it("matches JSON directly inside a stories directory", () => {
-    expect(
-      STORY_ASSET_PATH_PATTERN.test(
-        "/repo/node_modules/@canonical/design-system/stories/color.json",
-      ),
-    ).toBe(true);
-  });
-
-  it("rejects manifests, nested files, near-miss directories, and non-JSON", () => {
-    const nonStories = [
-      "/repo/node_modules/@canonical/design-system/package.json",
-      "/repo/node_modules/@canonical/design-system/stories/nested/color.json",
-      "/repo/node_modules/@canonical/design-system/histories/color.json",
-      "/repo/node_modules/@canonical/design-system/stories/color.jsonc",
-      "/repo/node_modules/@canonical/design-system/stories/color.ttl",
-    ];
-    for (const path of nonStories) {
-      expect(STORY_ASSET_PATH_PATTERN.test(path), path).toBe(false);
-    }
-  });
-});
-
-describe("createStoryAssetsPlugin", () => {
-  let tmpDir: string | undefined;
-
-  afterEach(() => {
-    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
-    tmpDir = undefined;
-  });
-
-  it("registers its load hook under the story path filter", () => {
-    const { filter } = captureOnLoadRegistration();
-    expect(filter).toBe(STORY_ASSET_PATH_PATTERN);
-  });
-
-  it("loads story JSON contents under the file loader", () => {
-    tmpDir = mkdtempSync(join(tmpdir(), "pragma-story-assets-"));
-    const storyPath = join(tmpDir, "color.json");
-    const content = JSON.stringify({ noun: "color" });
-    writeFileSync(storyPath, content);
-
-    const { callback } = captureOnLoadRegistration();
-
-    expect(callback({ path: storyPath })).toEqual({
-      contents: content,
-      loader: "file",
-    });
-  });
-});

package/src/domains/shared/loaders/storyAssetsPlugin.ts

@@ -1,46 +0,0 @@
-/**
- * Build-time bundler plugin: embed story-pack JSON as file assets.
- *
- * Bun compiles `.json` build inputs into JSON modules, which never
- * surface in `Bun.embeddedFiles`. Story-pack files must instead be
- * embedded as file assets — like TTL graphs — so the bundled loader can
- * serve them inside the compiled binary. This plugin scopes the `file`
- * loader to story paths only, leaving every other JSON input (e.g.
- * `package.json` imported for the CLI version) compiled as a module.
- *
- * Contract with the bundled loader: story files are the only `.json`
- * content embedded as file assets, so every `.json` blob in
- * `Bun.embeddedFiles` that is not named like a package manifest is a
- * story definition. Consequence: no module in the bundle may import a
- * `stories/*.json` file as a JSON module — the plugin would rewrite
- * such an import into a file-path string.
- *
- * Consumed by `scripts/build.ts` only; never bundled into the binary.
- */
-
-import { readFileSync } from "node:fs";
-import type { BunPlugin } from "bun";
-
-/**
- * Matches story-pack files: a `.json` directly inside a `stories/`
- * directory — the same non-recursive scope the local loader scans.
- */
-export const STORY_ASSET_PATH_PATTERN = /[\\/]stories[\\/][^\\/]+\.json$/;
-
-/**
- * Create the bundler plugin that embeds `stories/*.json` as file assets.
- *
- * @returns A `Bun.build` plugin for the compiled-binary build.
- * @note Impure — the registered load callback reads the filesystem.
- */
-export default function createStoryAssetsPlugin(): BunPlugin {
-  return {
-    name: "story-assets",
-    setup(build) {
-      build.onLoad({ filter: STORY_ASSET_PATH_PATTERN }, (args) => ({
-        contents: readFileSync(args.path, "utf-8"),
-        loader: "file",
-      }));
-    },
-  };
-}

package/src/domains/shared/lookupMany.test.ts

@@ -1,135 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import lookupMany, { lookupToolMeta } from "./lookupMany.js";
-
-describe("lookupMany", () => {
-  it("returns all results when every query resolves", async () => {
-    const result = await lookupMany(["a", "b"], async (q) => q.toUpperCase());
-
-    expect(result.results).toEqual(["A", "B"]);
-    expect(result.errors).toEqual([]);
-    expect(result.meta).toEqual({ internalErrorCount: 0 });
-  });
-
-  it("collects PragmaError failures as structured error entries", async () => {
-    const result = await lookupMany(["Button", "Buton"], async (q) => {
-      if (q === "Buton") {
-        throw PragmaError.notFound("block", q, { suggestions: ["Button"] });
-      }
-      return q;
-    });
-
-    expect(result.results).toEqual(["Button"]);
-    expect(result.errors).toEqual([
-      {
-        query: "Buton",
-        code: "ENTITY_NOT_FOUND",
-        message: 'block "Buton" not found.',
-        suggestions: ["Button"],
-      },
-    ]);
-    expect(result.meta).toEqual({ internalErrorCount: 0 });
-  });
-
-  it("keeps N-1 results when one query throws a non-PragmaError", async () => {
-    const result = await lookupMany(
-      ["a", "poisoned", "c"],
-      async (q): Promise<string> => {
-        if (q === "poisoned") {
-          throw new TypeError("cannot read properties of undefined");
-        }
-        return q.toUpperCase();
-      },
-    );
-
-    expect(result.results).toEqual(["A", "C"]);
-    expect(result.errors).toEqual([
-      {
-        query: "poisoned",
-        code: "INTERNAL_ERROR",
-        message: "Internal error: cannot read properties of undefined",
-      },
-    ]);
-    expect(result.meta).toEqual({ internalErrorCount: 1 });
-  });
-
-  it("stringifies non-Error rejection values", async () => {
-    const result = await lookupMany(["a"], async () => {
-      throw "string failure";
-    });
-
-    expect(result.results).toEqual([]);
-    expect(result.errors).toEqual([
-      {
-        query: "a",
-        code: "INTERNAL_ERROR",
-        message: "Internal error: string failure",
-      },
-    ]);
-    expect(result.meta).toEqual({ internalErrorCount: 1 });
-  });
-
-  it("counts each internal error and mixes with PragmaError entries", async () => {
-    const result = await lookupMany(
-      ["ok", "missing", "boom-1", "boom-2"],
-      async (q): Promise<string> => {
-        if (q === "missing") throw PragmaError.notFound("token", q);
-        if (q.startsWith("boom")) throw new Error(q);
-        return q;
-      },
-    );
-
-    expect(result.results).toEqual(["ok"]);
-    expect(result.errors).toHaveLength(3);
-    expect(result.errors.map((e) => e.code)).toEqual([
-      "ENTITY_NOT_FOUND",
-      "INTERNAL_ERROR",
-      "INTERNAL_ERROR",
-    ]);
-    expect(result.meta).toEqual({ internalErrorCount: 2 });
-  });
-
-  it("reclassifies a rejected SPARQL value as INVALID_INPUT, not internal", async () => {
-    const result = await lookupMany(["}; DROP"], async (q) => {
-      throw new Error(
-        `Potentially dangerous SPARQL value rejected: ${JSON.stringify(q)}`,
-      );
-    });
-
-    expect(result.results).toEqual([]);
-    expect(result.errors).toHaveLength(1);
-    expect(result.errors.at(0)?.code).toBe("INVALID_INPUT");
-    expect(result.errors.at(0)?.message).not.toContain("Internal error");
-    // A rejected value is user input, so it is not counted as an internal fault.
-    expect(result.meta).toEqual({ internalErrorCount: 0 });
-  });
-});
-
-describe("lookupToolMeta", () => {
-  it("reports count and omits internalErrorCount when zero", async () => {
-    const result = await lookupMany(["a", "b"], async (q) => q);
-
-    expect(lookupToolMeta(result)).toEqual({ count: 2 });
-  });
-
-  it("includes internalErrorCount when at least one query failed unexpectedly", async () => {
-    const result = await lookupMany(
-      ["a", "boom"],
-      async (q): Promise<string> => {
-        if (q === "boom") throw new Error("boom");
-        return q;
-      },
-    );
-
-    expect(lookupToolMeta(result)).toEqual({
-      count: 1,
-      internalErrorCount: 1,
-    });
-  });
-
-  it("tolerates hand-built results without meta", () => {
-    expect(lookupToolMeta({ results: ["x"], errors: [] })).toEqual({
-      count: 1,
-    });
-  });
-});

package/src/domains/shared/lookupMany.ts

@@ -1,101 +0,0 @@
-import { PragmaError } from "#error";
-import type { LookupResult } from "./contracts.js";
-
-/**
- * Marker in the ke SPARQL guard's rejection message. A rejected value is user
- * input, not an internal fault, so it is reclassified as INVALID_INPUT rather
- * than mislabelled as an internal error.
- */
-const SPARQL_REJECTION_MARKER = "Potentially dangerous SPARQL value rejected";
-
-/**
- * Resolve multiple lookup queries and collect structured per-query failures.
- *
- * Used by MCP lookup tools so a single call can return multiple results
- * without failing the entire request when one query is missing.
- *
- * The collection loop never rejects: a `PragmaError` becomes an error entry
- * with its own code, and any other thrown value becomes an `INTERNAL_ERROR`
- * entry — so one poisoned query cannot discard the other queries' results.
- * `meta.internalErrorCount` reports how many entries are internal errors.
- */
-export default async function lookupMany<TResult>(
-  queries: readonly string[],
-  lookup: (query: string) => Promise<TResult>,
-): Promise<LookupResult<TResult>> {
-  const errors: Array<{
-    query: string;
-    code: string;
-    message: string;
-    suggestions?: readonly string[];
-  }> = [];
-  const settled = await Promise.allSettled(
-    queries.map((query) => lookup(query)),
-  );
-  const results: TResult[] = [];
-  let internalErrorCount = 0;
-
-  for (const [index, outcome] of settled.entries()) {
-    const query = queries[index];
-    if (!query) {
-      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 {
-      const reason = error instanceof Error ? error.message : String(error);
-      if (reason.includes(SPARQL_REJECTION_MARKER)) {
-        // A rejected value is invalid user input, not an internal fault.
-        errors.push({
-          query,
-          code: "INVALID_INPUT",
-          message: `Invalid lookup value "${query}": rejected as unsafe.`,
-        });
-      } else {
-        internalErrorCount += 1;
-        errors.push({
-          query,
-          code: "INTERNAL_ERROR",
-          message: `Internal error: ${reason}`,
-        });
-      }
-    }
-  }
-
-  return { results, errors, meta: { internalErrorCount } };
-}
-
-/**
- * Build MCP envelope metadata for a lookup result.
- *
- * Always reports `count`; includes `internalErrorCount` only when at least
- * one query failed unexpectedly, so healthy responses stay unchanged.
- *
- * @param result - A lookup result, typically produced via {@link lookupMany}.
- * @returns Meta object for the `{ ok, data, meta }` tool envelope.
- */
-export function lookupToolMeta<TResult>(result: LookupResult<TResult>): {
-  count: number;
-  internalErrorCount?: number;
-} {
-  const internalErrorCount = result.meta?.internalErrorCount ?? 0;
-  return {
-    count: result.results.length,
-    ...(internalErrorCount > 0 && { internalErrorCount }),
-  };
-}

package/src/domains/shared/mergeAndParseRefs.test.ts

@@ -1,89 +0,0 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import type { RawPackageEntry } from "../refs/operations/parseRef.js";
-import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
-import { DEFAULT_PACKAGES } from "./packages.js";
-
-const DEFAULT_NAMES = DEFAULT_PACKAGES.map((entry) =>
-  typeof entry === "string" ? entry : entry.name,
-);
-
-function writeGlobalRefs(
-  xdgDir: string,
-  packages: ReadonlyArray<RawPackageEntry>,
-): void {
-  const dir = join(xdgDir, "pragma");
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "refs.json"), JSON.stringify({ packages }));
-}
-
-describe("mergeAndParseRefs", () => {
-  let tmpDir: string;
-  const origEnv = { ...process.env };
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "pragma-merge-refs-"));
-    // Point XDG_CONFIG_HOME to our temp dir so readGlobalRefs() resolves there
-    process.env.XDG_CONFIG_HOME = tmpDir;
-  });
-
-  afterEach(() => {
-    process.env = { ...origEnv };
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("returns parsed defaults when config and global refs are absent", () => {
-    const refs = mergeAndParseRefs(undefined);
-    expect(refs.map((ref) => ref.pkg)).toEqual(DEFAULT_NAMES);
-    expect(refs.every((ref) => ref.kind === "git")).toBe(true);
-  });
-
-  it("treats an explicitly empty config list as not configured", () => {
-    expect(mergeAndParseRefs([])).toEqual(mergeAndParseRefs(undefined));
-  });
-
-  it("falls back to global refs when the config list is empty", () => {
-    writeGlobalRefs(tmpDir, [
-      { name: "@canonical/design-system", source: "file:///tmp/ds" },
-    ]);
-
-    const refs = mergeAndParseRefs([]);
-
-    expect(refs.map((ref) => ref.pkg)).toEqual(DEFAULT_NAMES);
-    expect(refs.at(0)).toEqual({
-      kind: "file",
-      pkg: "@canonical/design-system",
-      path: "/tmp/ds",
-    });
-  });
-
-  it("merges global refs over defaults by package name", () => {
-    writeGlobalRefs(tmpDir, [
-      { name: "@canonical/design-system", source: "file:///tmp/ds" },
-      "@acme/extra",
-    ]);
-
-    const refs = mergeAndParseRefs(undefined);
-
-    expect(refs.map((ref) => ref.pkg)).toEqual([
-      ...DEFAULT_NAMES,
-      "@acme/extra",
-    ]);
-    expect(refs.at(0)?.kind).toBe("file");
-    expect(refs.at(-1)).toEqual({ kind: "npm", pkg: "@acme/extra" });
-  });
-
-  it("replaces defaults and global refs with a non-empty config list", () => {
-    writeGlobalRefs(tmpDir, ["@acme/global-only"]);
-
-    const refs = mergeAndParseRefs([
-      { name: "@acme/only", source: "file:///tmp/only" },
-    ]);
-
-    expect(refs).toEqual([
-      { kind: "file", pkg: "@acme/only", path: "/tmp/only" },
-    ]);
-  });
-});

package/src/domains/shared/mergeAndParseRefs.ts

@@ -1,44 +0,0 @@
-import {
-  type PackageRef,
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../refs/operations/parseRef.js";
-import readGlobalRefs from "../refs/operations/readGlobalRefs.js";
-import { DEFAULT_PACKAGES } from "./packages.js";
-
-/**
- * Merge config packages, global refs, and the built-in defaults into a
- * final parsed `PackageRef` array.
- *
- * Priority: config `packages` > global `refs.json` > hardcoded defaults.
- * A non-empty config list is a full replacement — only the listed packages
- * resolve. An empty or absent list means "not configured": global refs are
- * merged over the defaults by package name, so a global entry for
- * "@canonical/foo" overrides the default entry for the same package.
- *
- * Kept free of store imports so config-only consumers (e.g.
- * `resolveConfiguredGraphs`) can merge refs without loading the ke/WASM
- * runtime.
- *
- * @note Impure — reads global refs from `~/.config/pragma/refs.json`.
- *
- * @param configPackages - The `packages` field from `pragma.config.json`.
- * @returns Parsed refs ready for the loader chain.
- * @throws PragmaError with code CONFIG_ERROR when an entry is malformed.
- */
-export function mergeAndParseRefs(
-  configPackages?: ReadonlyArray<RawPackageEntry>,
-): PackageRef[] {
-  // A non-empty config list replaces the package set entirely.
-  if (configPackages && configPackages.length > 0) {
-    return configPackages.map((entry) => parsePackageEntry(entry));
-  }
-
-  // Empty or absent → merge global refs over the defaults, keyed by name.
-  const merged = new Map<string, RawPackageEntry>();
-  for (const entry of [...DEFAULT_PACKAGES, ...readGlobalRefs()]) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-  return [...merged.values()].map((entry) => parsePackageEntry(entry));
-}