@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -1,248 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { PackageRef } from "../../refs/operations/parseRef.js";
-import createBundledLoader, {
-  resetBundledLoaderCache,
-} from "./bundledLoader.js";
-
-const ref: PackageRef = { kind: "npm", pkg: "@canonical/design-system" };
-
-/** Minimal stand-in for a Bun embedded-file blob. */
-interface FakeBlob {
-  readonly name: string;
-  text(): Promise<string>;
-}
-
-const blob = (name: string, content: string): FakeBlob => ({
-  name,
-  text: async () => content,
-});
-
-const corruptBlob = (name: string): FakeBlob => ({
-  name,
-  text: async () => {
-    throw new Error("embedded blob unreadable");
-  },
-});
-
-const TTL = "@prefix ds: <https://example.test/ds#> .";
-
-function stubEmbeddedFiles(blobs: readonly FakeBlob[]): void {
-  (globalThis as { Bun?: unknown }).Bun = { embeddedFiles: blobs };
-}
-
-const hadBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
-const originalBun = (globalThis as { Bun?: unknown }).Bun;
-
-let stderrSpy: ReturnType<typeof vi.spyOn>;
-
-beforeEach(() => {
-  resetBundledLoaderCache();
-  stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-});
-
-afterEach(() => {
-  resetBundledLoaderCache();
-  if (hadBun) {
-    (globalThis as { Bun?: unknown }).Bun = originalBun;
-  } else {
-    delete (globalThis as { Bun?: unknown }).Bun;
-  }
-  stderrSpy.mockRestore();
-});
-
-const stderrText = (): string =>
-  stderrSpy.mock.calls.map((call) => String(call[0])).join("");
-
-describe("createBundledLoader", () => {
-  it("returns undefined outside a compiled Bun binary", async () => {
-    if (!hadBun) {
-      delete (globalThis as { Bun?: unknown }).Bun;
-      const resolved = await createBundledLoader().resolve(ref);
-      expect(resolved).toBeUndefined();
-    }
-  });
-
-  it("bundles all embedded TTL and reads the manifest version", async () => {
-    stubEmbeddedFiles([
-      blob("button-a1b2c3d4.ttl", TTL),
-      blob("package-a1b2c3d4.json", JSON.stringify({ version: "1.2.3" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved).toBeDefined();
-    expect(resolved?.source).toBe("bundled");
-    expect(resolved?.version).toBe("1.2.3");
-    expect(resolved?.graphs).toEqual([
-      {
-        path: "(bundled)/button-a1b2c3d4.ttl",
-        content: TTL,
-        format: "turtle",
-      },
-    ]);
-  });
-
-  it("accepts a plain package.json basename", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("package.json", JSON.stringify({ version: "2.0.0" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-    expect(resolved?.version).toBe("2.0.0");
-  });
-
-  it("warns and skips a corrupt TTL blob instead of silently dropping it", async () => {
-    stubEmbeddedFiles([
-      blob("good-a1b2c3d4.ttl", TTL),
-      corruptBlob("bad-a1b2c3d4.ttl"),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.graphs).toHaveLength(1);
-    expect(stderrText()).toContain("bad-a1b2c3d4.ttl");
-    expect(stderrText()).toContain("embedded blob unreadable");
-  });
-
-  it("serves embedded story JSON as story-file entries", async () => {
-    stubEmbeddedFiles([
-      blob("button-a1b2c3d4.ttl", TTL),
-      blob("package-a1b2c3d4.json", JSON.stringify({ version: "1.2.3" })),
-      blob("colors-fyskc7pf.json", JSON.stringify({ noun: "color" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.stories).toEqual([
-      {
-        path: "(bundled)/colors-fyskc7pf.json",
-        definition: { noun: "color" },
-      },
-    ]);
-    expect(resolved?.version).toBe("1.2.3");
-  });
-
-  it("does not serve package manifests as stories", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("package.json", JSON.stringify({ version: "2.0.0" })),
-      blob("package-deadbeef.json", JSON.stringify({ version: "3.0.0" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.stories).toEqual([]);
-  });
-
-  it("warns and skips a story blob with invalid JSON instead of crashing", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("good-a1b2c3d4.json", JSON.stringify({ noun: "color" })),
-      blob("broken-a1b2c3d4.json", "{ not json"),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.stories).toHaveLength(1);
-    expect(resolved?.stories.at(0)?.definition).toEqual({ noun: "color" });
-    expect(stderrText()).toContain("broken-a1b2c3d4.json");
-  });
-
-  it("warns and skips an unreadable story blob", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      corruptBlob("story-a1b2c3d4.json"),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.stories).toEqual([]);
-    expect(stderrText()).toContain("story-a1b2c3d4.json");
-    expect(stderrText()).toContain("embedded blob unreadable");
-  });
-
-  it("resolves a stories-only bundle with no TTL graphs", async () => {
-    stubEmbeddedFiles([
-      blob("colors-fyskc7pf.json", JSON.stringify({ noun: "color" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved).toBeDefined();
-    expect(resolved?.graphs).toEqual([]);
-    expect(resolved?.stories).toHaveLength(1);
-  });
-
-  it("returns undefined when no TTL or story content is embedded", async () => {
-    stubEmbeddedFiles([
-      blob("template-a1b2c3d4.ejs", "<%= name %>"),
-      blob("skill-a1b2c3d4.md", "# Skill"),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved).toBeUndefined();
-  });
-
-  it("warns on a corrupt package manifest and falls back to 0.0.0", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("package-deadbeef.json", "{ not json"),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.version).toBe("0.0.0");
-    expect(stderrText()).toContain("package-deadbeef.json");
-  });
-
-  it("rejects JSON blobs whose basename is not a package manifest", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("mypackage.json", JSON.stringify({ version: "9.9.9" })),
-      blob("package-lock.json", JSON.stringify({ version: "8.8.8" })),
-      blob("packages.json", JSON.stringify({ version: "7.7.7" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-    expect(resolved?.version).toBe("0.0.0");
-  });
-
-  it("warns on an invalid semver version and keeps looking", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("package-aaaaaaaa.json", JSON.stringify({ version: "not-semver" })),
-      blob("package-bbbbbbbb.json", JSON.stringify({ version: "3.4.5" })),
-    ]);
-
-    const resolved = await createBundledLoader().resolve(ref);
-
-    expect(resolved?.version).toBe("3.4.5");
-    expect(stderrText()).toContain('invalid semver "not-semver"');
-  });
-
-  it("caches the resolved package until the cache is reset", async () => {
-    stubEmbeddedFiles([
-      blob("button.ttl", TTL),
-      blob("package.json", JSON.stringify({ version: "1.0.0" })),
-    ]);
-
-    const first = await createBundledLoader().resolve(ref);
-    expect(first?.version).toBe("1.0.0");
-
-    // New fixture without reset — cached result still returned.
-    stubEmbeddedFiles([
-      blob("other.ttl", TTL),
-      blob("package.json", JSON.stringify({ version: "5.0.0" })),
-    ]);
-    const second = await createBundledLoader().resolve(ref);
-    expect(second).toBe(first);
-
-    // After reset the loader re-reads the embedded files.
-    resetBundledLoaderCache();
-    const third = await createBundledLoader().resolve(ref);
-    expect(third?.version).toBe("5.0.0");
-    expect(third).not.toBe(first);
-  });
-});

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

@@ -1,254 +0,0 @@
-/**
- * Bundled package loader for compiled binaries.
- *
- * Resolves semantic content from `Bun.embeddedFiles` — the TTL graphs
- * and story-pack JSON embedded into the compiled binary via the build
- * command. Skills are not embedded; this loader reports `skills: []`.
- *
- * Blob names are hashed by bun (e.g. `button-a1b2c3d4.ttl`), losing
- * directory and package association. The loader therefore returns a
- * single SemanticPackage containing ALL embedded TTL and story content,
- * and the same cached package is returned for every ref this loader
- * resolves.
- * Note that repeated loads are NOT fully deduplicated by the store:
- * Oxigraph applies set semantics to ground triples, but blank nodes are
- * re-minted on every parse, so content loaded both here and by a
- * higher-precedence loader can produce duplicated blank-node subgraphs.
- * The orchestrator's first-loader-wins precedence (local > git >
- * bundled) is what keeps individual packages from double-loading.
- *
- * @note Impure — reads embedded blobs.
- */
-
-import { basename } from "node:path";
-import type { PackageRef } from "../../refs/operations/parseRef.js";
-import type {
-  GraphContent,
-  PackageLoader,
-  SemanticPackage,
-  StoryFileEntry,
-} from "../semanticPackage.js";
-
-// ---------------------------------------------------------------------------
-// State
-// ---------------------------------------------------------------------------
-
-/** Cached result — embedded content is immutable, no need to re-read. */
-let cached: SemanticPackage | undefined;
-
-/**
- * Reset the module-level cache. Test-only: lets suites exercise the loader
- * against different `Bun.embeddedFiles` fixtures without module isolation.
- */
-export function resetBundledLoaderCache(): void {
-  cached = undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-/**
- * Embedded package manifest basename: exactly `package.json`, or
- * `package-<hash>.json` where `<hash>` is bun's content hash suffix.
- */
-const PACKAGE_MANIFEST_PATTERN = /^package(?:-[0-9a-f]{6,64})?\.json$/i;
-
-/**
- * Semver 2.0.0 validation (semver.org's suggested pattern).
- */
-const SEMVER_PATTERN =
-  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
-
-/**
- * Whether a blob name is an embedded package manifest — strict basename
- * match, so unrelated JSON blobs (e.g. `mypackage.json`) are not misread.
- */
-function isPackageManifest(name: string): boolean {
-  return PACKAGE_MANIFEST_PATTERN.test(basename(name));
-}
-
-/**
- * Emit a loader warning on stderr (safe for both CLI and MCP stdio use).
- */
-function warn(message: string): void {
-  process.stderr.write(`Warning: bundled loader: ${message}\n`);
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export default function createBundledLoader(): PackageLoader {
-  return {
-    name: "bundled",
-    async resolve(_ref: PackageRef): Promise<SemanticPackage | undefined> {
-      if (cached) return cached;
-
-      if (typeof globalThis.Bun === "undefined") return undefined;
-      // Bun.embeddedFiles blobs have a .name property at runtime
-      const blobs = (globalThis.Bun as { embeddedFiles?: readonly Blob[] })
-        .embeddedFiles as ReadonlyArray<Blob & { name: string }> | undefined;
-      if (!blobs?.length) return undefined;
-
-      const graphs = await readEmbeddedGraphs(blobs);
-      const stories = await readEmbeddedStories(blobs);
-      if (graphs.length === 0 && stories.length === 0) return undefined;
-
-      const version = await readEmbeddedVersion(blobs);
-      const prefixes = await readEmbeddedPrefixes(blobs);
-
-      cached = {
-        name: "(bundled)",
-        version,
-        source: "bundled",
-        graphs,
-        ...(prefixes ? { prefixes } : {}),
-        skills: [],
-        stories,
-      };
-
-      return cached;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Graph reading
-// ---------------------------------------------------------------------------
-
-async function readEmbeddedGraphs(
-  blobs: ReadonlyArray<Blob & { name: string }>,
-): Promise<GraphContent[]> {
-  const graphs: GraphContent[] = [];
-
-  for (const blob of blobs) {
-    if (!blob.name.endsWith(".ttl")) continue;
-
-    try {
-      const content = await blob.text();
-      graphs.push({
-        path: `(bundled)/${blob.name}`,
-        content,
-        format: "turtle",
-      });
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      warn(`skipping unreadable embedded graph "${blob.name}": ${reason}`);
-    }
-  }
-
-  return graphs;
-}
-
-// ---------------------------------------------------------------------------
-// Story reading
-// ---------------------------------------------------------------------------
-
-/**
- * Read story-pack definitions from embedded `.json` blobs.
- *
- * The build's story-assets plugin makes `stories/*.json` the only JSON
- * embedded as file assets (see storyAssetsPlugin.ts), so every `.json`
- * blob not named like a package manifest is a story file. Mirrors the
- * local loader: a blob that cannot be read or parsed warns on stderr
- * and is skipped — one bad file cannot break boot. Definitions are
- * shape-validated later by the story-pack compiler.
- */
-async function readEmbeddedStories(
-  blobs: ReadonlyArray<Blob & { name: string }>,
-): Promise<StoryFileEntry[]> {
-  const stories: StoryFileEntry[] = [];
-
-  for (const blob of blobs) {
-    if (!blob.name.endsWith(".json") || isPackageManifest(blob.name)) continue;
-
-    try {
-      stories.push({
-        path: `(bundled)/${blob.name}`,
-        definition: JSON.parse(await blob.text()),
-      });
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      warn(`skipping invalid embedded story "${blob.name}": ${reason}`);
-    }
-  }
-
-  return stories;
-}
-
-// ---------------------------------------------------------------------------
-// Version reading
-// ---------------------------------------------------------------------------
-
-/**
- * Aggregate `pragma.prefixes` declared across embedded package manifests.
- *
- * The bundled loader collapses every embedded package into one aggregate
- * SemanticPackage, so their prefix declarations are merged here (later
- * manifests win on key collisions). Only string→string entries are kept;
- * malformed shapes are ignored so one bad manifest cannot break boot.
- *
- * @returns The merged prefix map, or `undefined` when none is declared.
- */
-async function readEmbeddedPrefixes(
-  blobs: ReadonlyArray<Blob & { name: string }>,
-): Promise<Readonly<Record<string, string>> | undefined> {
-  const prefixes: Record<string, string> = {};
-
-  for (const blob of blobs) {
-    if (!isPackageManifest(blob.name)) continue;
-
-    try {
-      const parsed = JSON.parse(await blob.text()) as { pragma?: unknown };
-      const pragma = parsed.pragma;
-      if (typeof pragma !== "object" || pragma === null) continue;
-      const raw = (pragma as { prefixes?: unknown }).prefixes;
-      if (typeof raw !== "object" || raw === null) continue;
-      for (const [name, namespace] of Object.entries(raw)) {
-        if (typeof namespace !== "string") continue;
-        // These collapse into one aggregate package, so a cross-manifest
-        // collision would never reach resolvePrefixes' warning — surface it
-        // here, naming the manifest, instead of silently last-winning.
-        if (name in prefixes && prefixes[name] !== namespace) {
-          warn(
-            `embedded manifest "${blob.name}" overrides prefix "${name}" ` +
-              `(was <${prefixes[name]}>, now <${namespace}>)`,
-          );
-        }
-        prefixes[name] = namespace;
-      }
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      warn(`skipping prefixes in embedded manifest "${blob.name}": ${reason}`);
-    }
-  }
-
-  return Object.keys(prefixes).length > 0 ? prefixes : undefined;
-}
-
-async function readEmbeddedVersion(
-  blobs: ReadonlyArray<Blob & { name: string }>,
-): Promise<string> {
-  for (const blob of blobs) {
-    if (!isPackageManifest(blob.name)) continue;
-
-    try {
-      const text = await blob.text();
-      const parsed = JSON.parse(text) as { version?: unknown };
-      if (typeof parsed.version !== "string") continue;
-      if (!SEMVER_PATTERN.test(parsed.version)) {
-        warn(
-          `ignoring invalid semver "${parsed.version}" in embedded manifest "${blob.name}"`,
-        );
-        continue;
-      }
-      return parsed.version;
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      warn(`skipping corrupt embedded manifest "${blob.name}": ${reason}`);
-    }
-  }
-
-  return "0.0.0";
-}

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

@@ -1,30 +0,0 @@
-/**
- * Git cache package loader.
- *
- * Resolves semantic packages from the git ref cache at
- * `~/.cache/pragma/refs/<pkg>/<ref>/`, populated by `pragma update-refs`.
- *
- * Only handles `git` kind refs. File and npm refs are skipped.
- *
- * @note Impure — reads filesystem.
- */
-
-import { existsSync } from "node:fs";
-import type { PackageRef } from "../../refs/operations/parseRef.js";
-import { gitCacheDir } from "../../refs/operations/paths.js";
-import type { PackageLoader, SemanticPackage } from "../semanticPackage.js";
-import readPackageDir from "./readPackageDir.js";
-
-export default function createGitLoader(): PackageLoader {
-  return {
-    name: "git",
-    resolve(ref: PackageRef): SemanticPackage | undefined {
-      if (ref.kind !== "git") return undefined;
-
-      const dir = gitCacheDir(ref.pkg, ref.ref);
-      if (!existsSync(dir)) return undefined;
-
-      return { name: ref.pkg, source: "git", ...readPackageDir(dir) };
-    },
-  };
-}

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

@@ -1,9 +0,0 @@
-/** @module Semantic package loaders — local, git, and bundled resolution. */
-
-export {
-  default as createBundledLoader,
-  resetBundledLoaderCache,
-} from "./bundledLoader.js";
-export { default as createGitLoader } from "./gitLoader.js";
-export { default as createLocalLoader } from "./localLoader.js";
-export { default as readPackageDir } from "./readPackageDir.js";

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

@@ -1,71 +0,0 @@
-/**
- * Local package loader.
- *
- * Resolves semantic packages from the local filesystem:
- * - `file://` refs → direct path check
- * - All ref kinds → upward `node_modules` walk from this module's location
- *
- * The node_modules walk avoids `require.resolve('pkg/package.json')` which
- * breaks for packages with strict `exports` fields (e.g. @canonical/anatomy-dsl).
- *
- * @note Impure — reads filesystem.
- */
-
-import { existsSync, realpathSync } from "node:fs";
-import { dirname, join } from "node:path";
-import type { PackageRef } from "../../refs/operations/parseRef.js";
-import type { PackageLoader, SemanticPackage } from "../semanticPackage.js";
-import readPackageDir from "./readPackageDir.js";
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export default function createLocalLoader(): PackageLoader {
-  return {
-    name: "local",
-    resolve(ref: PackageRef): SemanticPackage | undefined {
-      // file:// refs → direct path check first
-      if (ref.kind === "file") {
-        if (!existsSync(ref.path)) return undefined;
-        return { name: ref.pkg, source: "local", ...readPackageDir(ref.path) };
-      }
-
-      // All ref kinds → try node_modules walk
-      const dir = findPackageDir(ref.pkg);
-      if (!dir) return undefined;
-
-      return { name: ref.pkg, source: "local", ...readPackageDir(dir) };
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// node_modules walk
-// ---------------------------------------------------------------------------
-
-/**
- * Find a package directory by walking up from this module's location.
- *
- * Checks each ancestor's `node_modules/<pkg>` directory. Handles both
- * scoped (`@scope/name`) and unscoped packages. Follows symlinks via
- * `realpathSync` so hoisted workspace layouts resolve correctly.
- */
-function findPackageDir(pkg: string): string | undefined {
-  const segments = pkg.split("/");
-  let current = import.meta.dirname;
-
-  while (current !== dirname(current)) {
-    const candidate = join(current, "node_modules", ...segments);
-    if (existsSync(candidate)) {
-      try {
-        return realpathSync(candidate);
-      } catch {
-        return candidate;
-      }
-    }
-    current = dirname(current);
-  }
-
-  return undefined;
-}

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

@@ -1,58 +0,0 @@
-import { 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 readPackageDir from "./readPackageDir.js";
-
-let dir: string;
-
-beforeEach(() => {
-  dir = mkdtempSync(join(tmpdir(), "pragma-readpkg-"));
-});
-
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true });
-});
-
-/** Write a package.json into the temp package root. */
-function writeManifest(manifest: unknown): void {
-  writeFileSync(join(dir, "package.json"), JSON.stringify(manifest), "utf-8");
-}
-
-describe("readPackageDir — prefixes", () => {
-  it("reads package-declared prefixes from package.json pragma.prefixes", () => {
-    writeManifest({
-      version: "1.2.3",
-      pragma: { prefixes: { ds: "https://ds.canonical.com/" } },
-    });
-    const { version, prefixes } = readPackageDir(dir);
-    expect(version).toBe("1.2.3");
-    expect(prefixes).toEqual({ ds: "https://ds.canonical.com/" });
-  });
-
-  it("omits prefixes when the package declares none", () => {
-    writeManifest({ version: "1.0.0" });
-    expect(readPackageDir(dir).prefixes).toBeUndefined();
-  });
-
-  it("ignores a malformed pragma.prefixes field", () => {
-    writeManifest({ version: "1.0.0", pragma: { prefixes: "not-an-object" } });
-    expect(readPackageDir(dir).prefixes).toBeUndefined();
-  });
-
-  it("keeps only string-valued prefix entries", () => {
-    writeManifest({
-      version: "1.0.0",
-      pragma: { prefixes: { ds: "https://ds.canonical.com/", bad: 42 } },
-    });
-    expect(readPackageDir(dir).prefixes).toEqual({
-      ds: "https://ds.canonical.com/",
-    });
-  });
-
-  it("returns a default version and no prefixes when package.json is absent", () => {
-    const contents = readPackageDir(dir);
-    expect(contents.version).toBe("0.0.0");
-    expect(contents.prefixes).toBeUndefined();
-  });
-});