@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/config/parseConfigValues.ts

@@ -0,0 +1,215 @@
+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,4 +1,10 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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";
@@ -6,11 +12,22 @@ 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(() => {
@@ -174,6 +191,64 @@ describe("readConfig", () => {
   });
 });
 
+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;
 
@@ -186,14 +261,14 @@ describe("writeConfig", () => {
   });
 
   it("creates a new config file with tier", () => {
-    writeConfig(dir, { tier: "apps/lxd" });
+    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", () => {
-    writeConfig(dir, { channel: "experimental" });
+    writeConfigLocal(dir, { channel: "experimental" });
     const config = readConfig(dir);
     expect(config.channel).toBe("experimental");
     expect(config.tier).toBeUndefined();
@@ -201,7 +276,7 @@ describe("writeConfig", () => {
 
   it("merges tier into existing config", () => {
     writeFileSync(join(dir, "pragma.config.json"), '{"channel":"prerelease"}');
-    writeConfig(dir, { tier: "global" });
+    writeConfigLocal(dir, { tier: "global" });
     const config = readConfig(dir);
     expect(config.tier).toBe("global");
     expect(config.channel).toBe("prerelease");
@@ -212,7 +287,7 @@ describe("writeConfig", () => {
       join(dir, "pragma.config.json"),
       '{"tier":"apps","channel":"normal"}',
     );
-    writeConfig(dir, { tier: undefined });
+    writeConfigLocal(dir, { tier: undefined });
     const config = readConfig(dir);
     expect(config.tier).toBeUndefined();
     expect(config.channel).toBe("normal");
@@ -223,7 +298,7 @@ describe("writeConfig", () => {
       join(dir, "pragma.config.json"),
       '{"tier":"apps","channel":"experimental"}',
     );
-    writeConfig(dir, { channel: undefined });
+    writeConfigLocal(dir, { channel: undefined });
     const config = readConfig(dir);
     expect(config.tier).toBe("apps");
     // Channel defaults to "normal" when absent from file
@@ -231,7 +306,7 @@ describe("writeConfig", () => {
   });
 
   it("round-trips tier and channel through write then read", () => {
-    writeConfig(dir, { tier: "apps/lxd", channel: "prerelease" });
+    writeConfigLocal(dir, { tier: "apps/lxd", channel: "prerelease" });
     const config = readConfig(dir);
     expect(config.tier).toBe("apps/lxd");
     expect(config.channel).toBe("prerelease");
@@ -239,19 +314,19 @@ describe("writeConfig", () => {
 
   it("writes valid empty JSON when all fields removed", () => {
     writeFileSync(join(dir, "pragma.config.json"), '{"tier":"apps"}');
-    writeConfig(dir, { tier: undefined });
+    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(() => writeConfig(dir, { tier: "apps" })).toThrow();
+    expect(() => writeConfigLocal(dir, { tier: "apps" })).toThrow();
   });
 
   describe("packages field", () => {
     it("writes packages array", () => {
-      writeConfig(dir, {
+      writeConfigLocal(dir, {
         packages: [
           "@canonical/design-system",
           {
@@ -272,7 +347,7 @@ describe("writeConfig", () => {
 
     it("merges packages into existing config without touching tier", () => {
       writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
-      writeConfig(dir, { packages: ["@canonical/design-system"] });
+      writeConfigLocal(dir, { packages: ["@canonical/design-system"] });
       const config = readConfig(dir);
       expect(config.tier).toBe("global");
       expect(config.packages).toEqual(["@canonical/design-system"]);
@@ -283,7 +358,7 @@ describe("writeConfig", () => {
         join(dir, "pragma.config.json"),
         JSON.stringify({ packages: ["@canonical/design-system"] }),
       );
-      writeConfig(dir, { packages: undefined });
+      writeConfigLocal(dir, { packages: undefined });
       const config = readConfig(dir);
       expect(config.packages).toBeUndefined();
     });
@@ -296,9 +371,25 @@ describe("writeConfig", () => {
           source: "git+https://github.com/canonical/anatomy-dsl.git#main",
         },
       ];
-      writeConfig(dir, { packages });
+      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,162 +1,21 @@
-import { readFileSync } from "node:fs";
-import {
-  type Channel,
-  type Framework,
-  VALID_CHANNELS,
-  VALID_FRAMEWORKS,
-} from "../constants.js";
-import {
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../domains/refs/operations/parseRef.js";
-import { PragmaError } from "../error/PragmaError.js";
-import resolveConfigPath from "./resolveConfigPath.js";
+import readConfigLayers from "./readConfigLayers.js";
 import type { PragmaConfig } from "./types.js";
 
 /**
- * Type guard: check whether a value is a recognized channel string.
+ * Read the effective pragma configuration for a directory.
  *
- * @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)
-  );
-}
-
-/**
- * Read pragma config from `pragma.config.json` in the given 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.
  *
- * Returns defaults (no tier, `"normal"` channel) when the file is missing or empty.
+ * @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.
  *
- * @param cwd - Directory containing pragma.config.json (defaults to `process.cwd()`).
- * @returns Parsed configuration.
- * @throws PragmaError with code `CONFIG_ERROR` if JSON is invalid or channel is unrecognized.
- *
- * @note Impure — reads config from filesystem.
+ * @note Impure — reads config files from the filesystem.
  */
 export default function readConfig(cwd: string = process.cwd()): PragmaConfig {
-  const configPath = resolveConfigPath(cwd);
-
-  let raw: string;
-  try {
-    raw = readFileSync(configPath, "utf-8");
-  } catch {
-    return { tier: undefined, channel: "normal" };
-  }
-
-  const trimmed = raw.trim();
-  if (trimmed === "") {
-    return { tier: undefined, channel: "normal" };
-  }
-
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(trimmed) as Record<string, unknown>;
-  } catch {
-    throw PragmaError.configError(`Invalid JSON in ${configPath}.`);
-  }
-
-  const tier = typeof parsed.tier === "string" ? parsed.tier : undefined;
-
-  let channel: Channel = "normal";
-  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);
-
-  return {
-    tier,
-    channel,
-    ...(packages ? { packages } : {}),
-    ...(trace !== undefined ? { trace } : {}),
-    ...(framework !== undefined ? { framework } : {}),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// 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.',
-    );
-  }
-
-  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;
+  return readConfigLayers(cwd).config;
 }