@canonical/pragma-cli 0.29.0 → 0.31.0

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

package/src/config/readConfigLayers.test.ts

@@ -0,0 +1,109 @@
+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

@@ -0,0 +1,118 @@
+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/resolveGlobalConfigPath.ts

@@ -0,0 +1,13 @@
+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");
+}

package/src/config/resolveWriteConfigPath.test.ts

@@ -0,0 +1,53 @@
+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 resolveWriteConfigPath from "./resolveWriteConfigPath.js";
+
+describe("resolveWriteConfigPath", () => {
+  let xdgDir: string;
+  let projectDir: string;
+  let originalXdg: string | undefined;
+
+  beforeEach(() => {
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-write-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
+    projectDir = mkdtempSync(join(tmpdir(), "pragma-write-project-"));
+    mkdirSync(join(projectDir, ".git"));
+  });
+
+  afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
+    rmSync(xdgDir, { recursive: true, force: true });
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it("targets the nearest existing project file", () => {
+    writeFileSync(join(projectDir, "pragma.config.json"), "{}");
+    const sub = join(projectDir, "packages/app");
+    mkdirSync(sub, { recursive: true });
+    expect(resolveWriteConfigPath(sub)).toBe(
+      join(projectDir, "pragma.config.json"),
+    );
+  });
+
+  it("falls back to the global file when no project file exists", () => {
+    expect(resolveWriteConfigPath(projectDir)).toBe(
+      join(xdgDir, "pragma/config.json"),
+    );
+  });
+
+  it("honors an explicit local scope even without an existing file", () => {
+    expect(resolveWriteConfigPath(projectDir, "local")).toBe(
+      join(projectDir, "pragma.config.json"),
+    );
+  });
+
+  it("honors an explicit global scope over an existing project file", () => {
+    writeFileSync(join(projectDir, "pragma.config.json"), "{}");
+    expect(resolveWriteConfigPath(projectDir, "global")).toBe(
+      join(xdgDir, "pragma/config.json"),
+    );
+  });
+});