@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/config/readConfig.test.ts

@@ -1,395 +0,0 @@
-import {
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { PragmaError } from "../error/PragmaError.js";
-import readConfig from "./readConfig.js";
-import writeConfig from "./writeConfig.js";
-
-/** Write to `<dir>/pragma.config.json` — these tests pin file mechanics. */
-function writeConfigLocal(
-  dir: string,
-  update: Parameters<typeof writeConfig>[1],
-): string {
-  return writeConfig(dir, update, "local");
-}
-
-describe("readConfig", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "pragma-config-"));
-    // Bound the project-config walk at this fixture root so a stray
-    // pragma.config.json in an ancestor directory can never leak in.
-    mkdirSync(join(dir, ".git"));
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("returns defaults when no config file exists", () => {
-    const config = readConfig(dir);
-    expect(config).toEqual({ tier: undefined, channel: "normal" });
-  });
-
-  it("parses tier and channel", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"tier":"apps/lxd","channel":"experimental"}',
-    );
-    const config = readConfig(dir);
-    expect(config.tier).toBe("apps/lxd");
-    expect(config.channel).toBe("experimental");
-  });
-
-  it("parses tier only, defaults channel to normal", () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
-    const config = readConfig(dir);
-    expect(config.tier).toBe("global");
-    expect(config.channel).toBe("normal");
-  });
-
-  it("parses channel only, tier is undefined", () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"prerelease"}');
-    const config = readConfig(dir);
-    expect(config.tier).toBeUndefined();
-    expect(config.channel).toBe("prerelease");
-  });
-
-  it("handles empty file", () => {
-    writeFileSync(join(dir, "pragma.config.json"), "");
-    const config = readConfig(dir);
-    expect(config).toEqual({ tier: undefined, channel: "normal" });
-  });
-
-  it("throws PragmaError on invalid channel", () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"aggressive"}');
-    expect(() => readConfig(dir)).toThrow(PragmaError);
-    try {
-      readConfig(dir);
-    } catch (e) {
-      expect(e).toBeInstanceOf(PragmaError);
-      expect((e as PragmaError).code).toBe("CONFIG_ERROR");
-      expect((e as PragmaError).validOptions).toEqual([
-        "normal",
-        "experimental",
-        "prerelease",
-      ]);
-    }
-  });
-
-  it("ignores non-string tier", () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"tier":42}');
-    const config = readConfig(dir);
-    expect(config.tier).toBeUndefined();
-  });
-
-  describe("packages field", () => {
-    it("parses string-only packages array", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({
-          packages: ["@canonical/design-system", "@canonical/code-standards"],
-        }),
-      );
-      const config = readConfig(dir);
-      expect(config.packages).toEqual([
-        "@canonical/design-system",
-        "@canonical/code-standards",
-      ]);
-    });
-
-    it("parses mixed string and object packages", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({
-          packages: [
-            "@canonical/design-system",
-            {
-              name: "@canonical/code-standards",
-              source: "file:///home/user/code/code-standards",
-            },
-          ],
-        }),
-      );
-      const config = readConfig(dir);
-      expect(config.packages).toEqual([
-        "@canonical/design-system",
-        {
-          name: "@canonical/code-standards",
-          source: "file:///home/user/code/code-standards",
-        },
-      ]);
-    });
-
-    it("parses object without source as npm", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({
-          packages: [{ name: "@canonical/design-system" }],
-        }),
-      );
-      const config = readConfig(dir);
-      expect(config.packages).toEqual([{ name: "@canonical/design-system" }]);
-    });
-
-    it("returns no packages field when absent", () => {
-      writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
-      const config = readConfig(dir);
-      expect(config.packages).toBeUndefined();
-    });
-
-    it("throws on non-array packages", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        '{"packages":"not-an-array"}',
-      );
-      expect(() => readConfig(dir)).toThrow(PragmaError);
-    });
-
-    it("throws on object entry with empty name", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({ packages: [{ name: "" }] }),
-      );
-      expect(() => readConfig(dir)).toThrow(PragmaError);
-    });
-
-    it("throws on invalid source scheme", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({
-          packages: [
-            { name: "@canonical/ds", source: "https://example.com/foo.tar.gz" },
-          ],
-        }),
-      );
-      expect(() => readConfig(dir)).toThrow(PragmaError);
-    });
-
-    it("throws on git source without ref", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({
-          packages: [
-            {
-              name: "@canonical/ds",
-              source: "git+https://github.com/canonical/ds.git",
-            },
-          ],
-        }),
-      );
-      expect(() => readConfig(dir)).toThrow(PragmaError);
-    });
-  });
-});
-
-describe("readConfig — stories and prefixes fields", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "pragma-config-stories-"));
-    mkdirSync(join(dir, ".git"));
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("parses a valid stories array and prefixes map", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      JSON.stringify({
-        prefixes: { ex: "http://example.org/" },
-        stories: [
-          {
-            noun: "recipe",
-            list: {
-              query: "SELECT ?uri WHERE { ?uri a ex:Recipe }",
-              columns: [{ field: "uri" }],
-            },
-          },
-        ],
-      }),
-    );
-    const config = readConfig(dir);
-    expect(config.prefixes).toEqual({ ex: "http://example.org/" });
-    expect(config.stories?.at(0)?.noun).toBe("recipe");
-  });
-
-  it("throws on a non-array stories field", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"stories": {"noun": "x"}}',
-    );
-    expect(() => readConfig(dir)).toThrow(/stories/);
-  });
-
-  it("throws on an invalid story definition", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"stories": [{"noun": "Bad Noun"}]}',
-    );
-    expect(() => readConfig(dir)).toThrow(PragmaError);
-  });
-
-  it("throws on a prefixes value that is not an IRI", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"prefixes": {"ex": "not-an-iri"}}',
-    );
-    expect(() => readConfig(dir)).toThrow(/prefix/);
-  });
-});
-
-describe("writeConfig", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "pragma-config-write-"));
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("creates a new config file with tier", () => {
-    writeConfigLocal(dir, { tier: "apps/lxd" });
-    const config = readConfig(dir);
-    expect(config.tier).toBe("apps/lxd");
-    expect(config.channel).toBe("normal");
-  });
-
-  it("creates a new config file with channel", () => {
-    writeConfigLocal(dir, { channel: "experimental" });
-    const config = readConfig(dir);
-    expect(config.channel).toBe("experimental");
-    expect(config.tier).toBeUndefined();
-  });
-
-  it("merges tier into existing config", () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"prerelease"}');
-    writeConfigLocal(dir, { tier: "global" });
-    const config = readConfig(dir);
-    expect(config.tier).toBe("global");
-    expect(config.channel).toBe("prerelease");
-  });
-
-  it("removes tier when set to undefined", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"tier":"apps","channel":"normal"}',
-    );
-    writeConfigLocal(dir, { tier: undefined });
-    const config = readConfig(dir);
-    expect(config.tier).toBeUndefined();
-    expect(config.channel).toBe("normal");
-  });
-
-  it("removes channel when set to undefined", () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"tier":"apps","channel":"experimental"}',
-    );
-    writeConfigLocal(dir, { channel: undefined });
-    const config = readConfig(dir);
-    expect(config.tier).toBe("apps");
-    // Channel defaults to "normal" when absent from file
-    expect(config.channel).toBe("normal");
-  });
-
-  it("round-trips tier and channel through write then read", () => {
-    writeConfigLocal(dir, { tier: "apps/lxd", channel: "prerelease" });
-    const config = readConfig(dir);
-    expect(config.tier).toBe("apps/lxd");
-    expect(config.channel).toBe("prerelease");
-  });
-
-  it("writes valid empty JSON when all fields removed", () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"tier":"apps"}');
-    writeConfigLocal(dir, { tier: undefined });
-    const raw = readFileSync(join(dir, "pragma.config.json"), "utf-8");
-    expect(raw).toBe("{}\n");
-  });
-
-  it("throws on unparseable existing config instead of silently overwriting", () => {
-    writeFileSync(join(dir, "pragma.config.json"), "{invalid json");
-    expect(() => writeConfigLocal(dir, { tier: "apps" })).toThrow();
-  });
-
-  describe("packages field", () => {
-    it("writes packages array", () => {
-      writeConfigLocal(dir, {
-        packages: [
-          "@canonical/design-system",
-          {
-            name: "@canonical/code-standards",
-            source: "file:///home/user/code/code-standards",
-          },
-        ],
-      });
-      const config = readConfig(dir);
-      expect(config.packages).toEqual([
-        "@canonical/design-system",
-        {
-          name: "@canonical/code-standards",
-          source: "file:///home/user/code/code-standards",
-        },
-      ]);
-    });
-
-    it("merges packages into existing config without touching tier", () => {
-      writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
-      writeConfigLocal(dir, { packages: ["@canonical/design-system"] });
-      const config = readConfig(dir);
-      expect(config.tier).toBe("global");
-      expect(config.packages).toEqual(["@canonical/design-system"]);
-    });
-
-    it("removes packages when set to undefined", () => {
-      writeFileSync(
-        join(dir, "pragma.config.json"),
-        JSON.stringify({ packages: ["@canonical/design-system"] }),
-      );
-      writeConfigLocal(dir, { packages: undefined });
-      const config = readConfig(dir);
-      expect(config.packages).toBeUndefined();
-    });
-
-    it("round-trips packages through write then read", () => {
-      const packages = [
-        "@canonical/design-system",
-        {
-          name: "@canonical/anatomy-dsl",
-          source: "git+https://github.com/canonical/anatomy-dsl.git#main",
-        },
-      ];
-      writeConfigLocal(dir, { packages });
-      const config = readConfig(dir);
-      expect(config.packages).toEqual(packages);
-    });
-  });
-});
-
-describe("readConfig — empty packages normalization", () => {
-  it("treats an explicitly empty packages list as not configured", () => {
-    const dir = mkdtempSync(join(tmpdir(), "pragma-empty-pkgs-"));
-    mkdirSync(join(dir, ".git"), { recursive: true });
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      JSON.stringify({ channel: "normal", packages: [] }),
-    );
-    const config = readConfig(dir);
-    // The field is dropped at parse time so provenance matches the ref
-    // resolution behavior (empty list falls back to defaults/global refs).
-    expect(config.packages).toBeUndefined();
-    rmSync(dir, { recursive: true, force: true });
-  });
-});

package/src/config/readConfig.ts

@@ -1,21 +0,0 @@
-import readConfigLayers from "./readConfigLayers.js";
-import type { PragmaConfig } from "./types.js";
-
-/**
- * Read the effective pragma configuration for a directory.
- *
- * Layered resolution: built-in defaults, then the global XDG file
- * (`~/.config/pragma/config.json`), then the nearest project
- * `pragma.config.json` at or above `cwd` — each field won by the most
- * specific layer that sets it. Returns defaults (no tier, `"normal"`
- * channel) when no layer configures anything.
- *
- * @param cwd - Directory the project layer is resolved from (defaults to `process.cwd()`).
- * @returns The effective merged configuration.
- * @throws PragmaError with code `CONFIG_ERROR` if a layer file has invalid JSON or values.
- *
- * @note Impure — reads config files from the filesystem.
- */
-export default function readConfig(cwd: string = process.cwd()): PragmaConfig {
-  return readConfigLayers(cwd).config;
-}

package/src/config/readConfigLayers.test.ts

@@ -1,109 +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 { PragmaError } from "../error/PragmaError.js";
-import readConfigLayers from "./readConfigLayers.js";
-
-describe("readConfigLayers", () => {
-  let xdgDir: string;
-  let projectDir: string;
-  let originalXdg: string | undefined;
-
-  beforeEach(() => {
-    originalXdg = process.env.XDG_CONFIG_HOME;
-    xdgDir = mkdtempSync(join(tmpdir(), "pragma-layers-xdg-"));
-    process.env.XDG_CONFIG_HOME = xdgDir;
-    projectDir = mkdtempSync(join(tmpdir(), "pragma-layers-project-"));
-    mkdirSync(join(projectDir, ".git"));
-  });
-
-  afterEach(() => {
-    process.env.XDG_CONFIG_HOME = originalXdg;
-    rmSync(xdgDir, { recursive: true, force: true });
-    rmSync(projectDir, { recursive: true, force: true });
-  });
-
-  function writeGlobal(content: string): void {
-    mkdirSync(join(xdgDir, "pragma"), { recursive: true });
-    writeFileSync(join(xdgDir, "pragma/config.json"), content);
-  }
-
-  function writeProject(content: string): void {
-    writeFileSync(join(projectDir, "pragma.config.json"), content);
-  }
-
-  it("returns defaults with default origins when no layer exists", () => {
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config).toEqual({ tier: undefined, channel: "normal" });
-    expect(layers.origins).toEqual({
-      tier: "default",
-      channel: "default",
-      packages: "default",
-      trace: "default",
-      framework: "default",
-      stories: "default",
-      prefixes: "default",
-      detail: "default",
-    });
-    expect(layers.global.exists).toBe(false);
-    expect(layers.project.exists).toBe(false);
-    expect(layers.project.path).toBe(join(projectDir, "pragma.config.json"));
-  });
-
-  it("reads the global layer when no project file exists", () => {
-    writeGlobal('{"channel":"experimental","tier":"global"}');
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config.channel).toBe("experimental");
-    expect(layers.config.tier).toBe("global");
-    expect(layers.origins.channel).toBe("global");
-    expect(layers.origins.tier).toBe("global");
-    expect(layers.global.exists).toBe(true);
-  });
-
-  it("merges per field — project wins only the fields it sets", () => {
-    writeGlobal('{"channel":"experimental","trace":true}');
-    writeProject('{"tier":"apps/lxd"}');
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config).toEqual({
-      tier: "apps/lxd",
-      channel: "experimental",
-      trace: true,
-    });
-    expect(layers.origins).toEqual({
-      tier: "project",
-      channel: "global",
-      packages: "default",
-      trace: "global",
-      framework: "default",
-      stories: "default",
-      prefixes: "default",
-      detail: "default",
-    });
-  });
-
-  it("lets the project override a global field wholesale", () => {
-    writeGlobal('{"packages":["@canonical/a"],"channel":"experimental"}');
-    writeProject('{"packages":["@canonical/b"],"channel":"normal"}');
-    const layers = readConfigLayers(projectDir);
-    expect(layers.config.packages).toEqual(["@canonical/b"]);
-    expect(layers.config.channel).toBe("normal");
-    expect(layers.origins.packages).toBe("project");
-    expect(layers.origins.channel).toBe("project");
-  });
-
-  it("finds the project layer from a subdirectory", () => {
-    writeProject('{"tier":"apps/lxd"}');
-    const sub = join(projectDir, "packages/app");
-    mkdirSync(sub, { recursive: true });
-    const layers = readConfigLayers(sub);
-    expect(layers.config.tier).toBe("apps/lxd");
-    expect(layers.project.path).toBe(join(projectDir, "pragma.config.json"));
-    expect(layers.project.exists).toBe(true);
-  });
-
-  it("throws on invalid JSON in the global layer", () => {
-    writeGlobal("{not json");
-    expect(() => readConfigLayers(projectDir)).toThrow(PragmaError);
-  });
-});

package/src/config/readConfigLayers.ts

@@ -1,118 +0,0 @@
-import { readFileSync } from "node:fs";
-import { DEFAULT_CONFIG } from "./defaultConfig.js";
-import findProjectConfigPath from "./findProjectConfigPath.js";
-import parseConfigValues from "./parseConfigValues.js";
-import resolveConfigPath from "./resolveConfigPath.js";
-import resolveGlobalConfigPath from "./resolveGlobalConfigPath.js";
-import type {
-  ConfigFileValues,
-  ConfigLayers,
-  ConfigOrigin,
-  PragmaConfig,
-} from "./types.js";
-
-/**
- * Fields the built-in defaults document contributes to the layer merge.
- *
- * `packages` is deliberately absent: it reaches the ref merge through
- * `DEFAULT_PACKAGES` instead, so global `refs.json` entries keep merging
- * over the default packages by name. Surfacing it here would make the
- * defaults look user-declared and replace the merged set wholesale.
- */
-const DEFAULT_LAYER: ConfigFileValues = {
-  channel: DEFAULT_CONFIG.channel,
-};
-
-/**
- * Resolve the layered configuration with per-field provenance.
- *
- * Layer order, least to most specific: built-in defaults, the global XDG
- * file (`~/.config/pragma/config.json`), and the nearest project
- * `pragma.config.json` up the tree. Merging is per field — a field set by
- * a more specific layer wins wholesale (`packages` replaces as a whole,
- * preserving the established project-pins-exactly semantics).
- *
- * @param cwd - Directory the project layer is resolved from.
- * @returns The effective config, per-field origins, and both layers.
- * @throws PragmaError with code `CONFIG_ERROR` when either file is invalid.
- * @note Impure — reads config files from the filesystem.
- */
-export default function readConfigLayers(
-  cwd: string = process.cwd(),
-): ConfigLayers {
-  const globalPath = resolveGlobalConfigPath();
-  const projectPath = findProjectConfigPath(cwd) ?? resolveConfigPath(cwd);
-
-  const globalFile = readConfigFile(globalPath);
-  const projectFile = readConfigFile(projectPath);
-
-  const pick = <K extends keyof ConfigFileValues>(
-    field: K,
-  ): { value: ConfigFileValues[K] | undefined; origin: ConfigOrigin } => {
-    if (field in projectFile.values) {
-      return { value: projectFile.values[field], origin: "project" };
-    }
-    if (field in globalFile.values) {
-      return { value: globalFile.values[field], origin: "global" };
-    }
-    if (field in DEFAULT_LAYER) {
-      return { value: DEFAULT_LAYER[field], origin: "default" };
-    }
-    return { value: undefined, origin: "default" };
-  };
-
-  const tier = pick("tier");
-  const channel = pick("channel");
-  const packages = pick("packages");
-  const trace = pick("trace");
-  const framework = pick("framework");
-  const stories = pick("stories");
-  const prefixes = pick("prefixes");
-  const detail = pick("detail");
-
-  const config: PragmaConfig = {
-    tier: tier.value,
-    channel: channel.value ?? DEFAULT_CONFIG.channel,
-    ...(packages.value ? { packages: packages.value } : {}),
-    ...(trace.value !== undefined ? { trace: trace.value } : {}),
-    ...(framework.value !== undefined ? { framework: framework.value } : {}),
-    ...(stories.value ? { stories: stories.value } : {}),
-    ...(prefixes.value ? { prefixes: prefixes.value } : {}),
-    ...(detail.value !== undefined ? { detail: detail.value } : {}),
-  };
-
-  return {
-    config,
-    origins: {
-      tier: tier.origin,
-      channel: channel.origin,
-      packages: packages.origin,
-      trace: trace.origin,
-      framework: framework.origin,
-      stories: stories.origin,
-      prefixes: prefixes.origin,
-      detail: detail.origin,
-    },
-    global: { path: globalPath, exists: globalFile.exists },
-    project: { path: projectPath, exists: projectFile.exists },
-  };
-}
-
-/**
- * Read and parse one config file layer.
- *
- * A missing or unreadable file contributes no values — the layer simply
- * does not participate in the merge.
- */
-function readConfigFile(path: string): {
-  values: ConfigFileValues;
-  exists: boolean;
-} {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf-8");
-  } catch {
-    return { values: {}, exists: false };
-  }
-  return { values: parseConfigValues(raw, path), exists: true };
-}

package/src/config/resolveConfigPath.test.ts

@@ -1,20 +0,0 @@
-import { resolve } from "node:path";
-import { describe, expect, it } from "vitest";
-import resolveConfigPath from "./resolveConfigPath.js";
-
-describe("resolveConfigPath", () => {
-  it("appends pragma.config.json to the given directory", () => {
-    expect(resolveConfigPath("/home/user/project")).toBe(
-      resolve("/home/user/project", "pragma.config.json"),
-    );
-  });
-
-  it("resolves relative paths against cwd", () => {
-    const result = resolveConfigPath(".");
-    expect(result).toBe(resolve(process.cwd(), "pragma.config.json"));
-  });
-
-  it("handles nested directories", () => {
-    expect(resolveConfigPath("/a/b/c")).toBe("/a/b/c/pragma.config.json");
-  });
-});

package/src/config/resolveConfigPath.ts

@@ -1,11 +0,0 @@
-import { resolve } from "node:path";
-
-/**
- * Resolve the absolute path to pragma.config.json for a given cwd.
- *
- * @param cwd - Directory to resolve from.
- * @returns Absolute file path to the configuration file.
- */
-export default function resolveConfigPath(cwd: string): string {
-  return resolve(cwd, "pragma.config.json");
-}

package/src/config/resolveGlobalConfigPath.ts

@@ -1,13 +0,0 @@
-import { join } from "node:path";
-import { globalConfigDir } from "../domains/refs/operations/paths.js";
-
-/**
- * Resolve the absolute path of the global config file.
- *
- * Lives next to `refs.json` in the pragma XDG config directory:
- * `$XDG_CONFIG_HOME/pragma/config.json`, defaulting to
- * `~/.config/pragma/config.json`.
- */
-export default function resolveGlobalConfigPath(): string {
-  return join(globalConfigDir(), "config.json");
-}