@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/config/parseConfigValues.ts

@@ -1,215 +0,0 @@
-import {
-  type Channel,
-  type Framework,
-  VALID_CHANNELS,
-  VALID_FRAMEWORKS,
-} from "../constants.js";
-import {
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../domains/refs/operations/parseRef.js";
-import type { StoryPackDefinition } from "../domains/shared/stories/pack/types.js";
-import validateStoryPackDefinition from "../domains/shared/stories/pack/validateStoryPackDefinition.js";
-import { PragmaError } from "../error/PragmaError.js";
-import type { ConfigFileValues } from "./types.js";
-
-/**
- * Type guard: check whether a value is a recognized channel string.
- *
- * @param value - Candidate value.
- * @returns `true` if value is a valid Channel.
- */
-function isValidChannel(value: unknown): value is Channel {
-  return typeof value === "string" && VALID_CHANNELS.includes(value as Channel);
-}
-
-/**
- * Type guard: check whether a value is a recognized framework string.
- *
- * @param value - Candidate value.
- * @returns `true` if value is a valid Framework.
- */
-function isValidFramework(value: unknown): value is Framework {
-  return (
-    typeof value === "string" && VALID_FRAMEWORKS.includes(value as Framework)
-  );
-}
-
-/**
- * Parse and validate one config file's raw contents.
- *
- * Returns only the fields the file actually sets — presence drives layer
- * merging in `readConfigLayers`. An empty or whitespace-only file sets
- * nothing.
- *
- * @param raw - The file's raw text.
- * @param sourcePath - Absolute path, used in error messages.
- * @returns The values this file declares.
- * @throws PragmaError with code `CONFIG_ERROR` on invalid JSON or values.
- */
-export default function parseConfigValues(
-  raw: string,
-  sourcePath: string,
-): ConfigFileValues {
-  const trimmed = raw.trim();
-  if (trimmed === "") {
-    return {};
-  }
-
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(trimmed) as Record<string, unknown>;
-  } catch {
-    throw PragmaError.configError(`Invalid JSON in ${sourcePath}.`);
-  }
-
-  const tier = typeof parsed.tier === "string" ? parsed.tier : undefined;
-
-  let channel: Channel | undefined;
-  if (parsed.channel !== undefined) {
-    if (!isValidChannel(parsed.channel)) {
-      throw PragmaError.configError(
-        `Invalid channel "${String(parsed.channel)}".`,
-        { validOptions: [...VALID_CHANNELS] },
-      );
-    }
-    channel = parsed.channel;
-  }
-
-  const trace = typeof parsed.trace === "boolean" ? parsed.trace : undefined;
-
-  let framework: Framework | undefined;
-  if (parsed.framework !== undefined) {
-    if (!isValidFramework(parsed.framework)) {
-      throw PragmaError.configError(
-        `Invalid framework "${String(parsed.framework)}".`,
-        { validOptions: [...VALID_FRAMEWORKS] },
-      );
-    }
-    framework = parsed.framework;
-  }
-
-  const packages = parsePackagesField(parsed.packages);
-  const stories = parseStoriesField(parsed.stories, sourcePath);
-  const prefixes = parsePrefixesField(parsed.prefixes);
-
-  return {
-    ...(tier !== undefined ? { tier } : {}),
-    ...(channel !== undefined ? { channel } : {}),
-    ...(packages ? { packages } : {}),
-    ...(trace !== undefined ? { trace } : {}),
-    ...(framework !== undefined ? { framework } : {}),
-    ...(stories ? { stories } : {}),
-    ...(prefixes ? { prefixes } : {}),
-  };
-}
-
-/**
- * Validate and parse the experimental `stories` config field.
- *
- * @returns The validated definitions, or `undefined` when absent.
- * @throws PragmaError if the field is present but malformed.
- */
-function parseStoriesField(
-  raw: unknown,
-  sourcePath: string,
-): ReadonlyArray<StoryPackDefinition> | undefined {
-  if (raw === undefined || raw === null) return undefined;
-  if (!Array.isArray(raw)) {
-    throw PragmaError.configError(
-      '"stories" must be an array of story-pack definitions.',
-    );
-  }
-  return raw.map((entry, index) =>
-    validateStoryPackDefinition(entry, `${sourcePath} (stories[${index}])`),
-  );
-}
-
-/**
- * Validate and parse the `prefixes` config field.
- *
- * @returns The prefix map, or `undefined` when absent.
- * @throws PragmaError if the field is present but malformed.
- */
-function parsePrefixesField(
-  raw: unknown,
-): Readonly<Record<string, string>> | undefined {
-  if (raw === undefined || raw === null) return undefined;
-  if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw PragmaError.configError(
-      '"prefixes" must be an object mapping prefix to namespace IRI.',
-    );
-  }
-  const entries = Object.entries(raw as Record<string, unknown>);
-  for (const [prefix, namespace] of entries) {
-    if (typeof namespace !== "string" || !namespace.includes("://")) {
-      throw PragmaError.configError(
-        `Invalid namespace for prefix "${prefix}": expected an absolute IRI.`,
-      );
-    }
-  }
-  return Object.fromEntries(entries) as Record<string, string>;
-}
-
-// ---------------------------------------------------------------------------
-// Packages field parsing
-// ---------------------------------------------------------------------------
-
-/**
- * Validate and parse the `packages` config field.
- *
- * @returns The validated array, or `undefined` when the field is absent.
- * @throws PragmaError if the field is present but malformed.
- */
-function parsePackagesField(
-  raw: unknown,
-): ReadonlyArray<RawPackageEntry> | undefined {
-  if (raw === undefined || raw === null) return undefined;
-
-  if (!Array.isArray(raw)) {
-    throw PragmaError.configError(
-      '"packages" must be an array of strings or { name, source? } objects.',
-    );
-  }
-
-  // An explicitly empty list means "not configured": ref resolution falls
-  // back to global refs/defaults for an empty list (see mergeAndParseRefs),
-  // so dropping the field here keeps provenance in config show/doctor/info
-  // consistent with the behavior instead of reporting a project/global
-  // origin that resolution then ignores.
-  if (raw.length === 0) return undefined;
-
-  const entries: RawPackageEntry[] = [];
-  for (const item of raw) {
-    if (typeof item === "string") {
-      entries.push(item);
-      continue;
-    }
-    if (typeof item === "object" && item !== null && !Array.isArray(item)) {
-      const obj = item as Record<string, unknown>;
-      if (typeof obj.name !== "string" || obj.name.length === 0) {
-        throw PragmaError.configError(
-          'Each object in "packages" must have a non-empty "name" string.',
-        );
-      }
-      const entry: { name: string; source?: string } = { name: obj.name };
-      if (obj.source !== undefined) {
-        if (typeof obj.source !== "string") {
-          throw PragmaError.configError(
-            `Invalid source for "${obj.name}": expected a string.`,
-          );
-        }
-        entry.source = obj.source;
-      }
-      // Validate format eagerly — fail fast on bad config
-      parsePackageEntry(entry);
-      entries.push(entry);
-      continue;
-    }
-    throw PragmaError.configError(
-      'Each entry in "packages" must be a string or { name, source? } object.',
-    );
-  }
-
-  return entries;
-}

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;
-}