@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/config/defaultConfig.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { VALID_CHANNELS } from "../constants.js";
+import { parsePackageEntry } from "../domains/refs/operations/parseRef.js";
+import { DEFAULT_CONFIG } from "./defaultConfig.js";
+
+describe("DEFAULT_CONFIG", () => {
+  it("declares a valid channel", () => {
+    expect(VALID_CHANNELS).toContain(DEFAULT_CONFIG.channel);
+  });
+
+  it("declares at least one package, all parseable", () => {
+    expect(DEFAULT_CONFIG.packages.length).toBeGreaterThan(0);
+    for (const entry of DEFAULT_CONFIG.packages) {
+      const ref = parsePackageEntry(entry);
+      expect(ref.pkg.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("carries the canonical design-system package by default", () => {
+    const names = DEFAULT_CONFIG.packages.map((entry) =>
+      typeof entry === "string" ? entry : entry.name,
+    );
+    expect(names).toContain("@canonical/design-system");
+  });
+
+  it("does not declare fields the document must not layer", () => {
+    // tier/trace/framework defaults are semantic absences, and packages
+    // must reach the merge via DEFAULT_PACKAGES (see defaultConfig.ts).
+    expect(DEFAULT_CONFIG.tier).toBeUndefined();
+    expect(DEFAULT_CONFIG.trace).toBeUndefined();
+    expect(DEFAULT_CONFIG.framework).toBeUndefined();
+  });
+});

package/src/config/defaultConfig.ts

@@ -0,0 +1,59 @@
+import type { Channel } from "../constants.js";
+import type { RawPackageEntry } from "../domains/refs/operations/parseRef.js";
+import { PragmaError } from "../error/PragmaError.js";
+import defaultsDocument from "./defaults.json" with { type: "json" };
+import parseConfigValues from "./parseConfigValues.js";
+import type { ConfigFileValues } from "./types.js";
+
+/** The built-in defaults with the fields every install relies on present. */
+interface DefaultConfig extends ConfigFileValues {
+  /** Release channel active when no config file sets one. */
+  readonly channel: Channel;
+  /** Semantic packages loaded when no config or global refs declare any. */
+  readonly packages: ReadonlyArray<RawPackageEntry>;
+}
+
+/**
+ * Validate the embedded defaults document into the built-in config layer.
+ *
+ * The document goes through the same parser as user config files, so an
+ * invalid edit to `defaults.json` fails loudly at first import (and in
+ * tests) instead of silently changing behavior.
+ *
+ * @throws PragmaError with code `CONFIG_ERROR` when the document is
+ *         invalid or misses a required default.
+ */
+function parseDefaultsDocument(): DefaultConfig {
+  const values = parseConfigValues(
+    JSON.stringify(defaultsDocument),
+    "built-in defaults (src/config/defaults.json)",
+  );
+  if (values.channel === undefined) {
+    throw PragmaError.configError("Built-in defaults must declare a channel.", {
+      recovery: { message: "Restore `channel` in src/config/defaults.json." },
+    });
+  }
+  if (values.packages === undefined || values.packages.length === 0) {
+    throw PragmaError.configError(
+      "Built-in defaults must declare at least one semantic package.",
+      {
+        recovery: {
+          message: "Restore `packages` in src/config/defaults.json.",
+        },
+      },
+    );
+  }
+  return { ...values, channel: values.channel, packages: values.packages };
+}
+
+/**
+ * The built-in configuration layer, sourced from the embedded declarative
+ * `defaults.json` document rather than hardcoded values.
+ *
+ * `packages` is deliberately NOT surfaced through the layered `pick()` in
+ * `readConfigLayers` — it feeds `DEFAULT_PACKAGES` (and from there the
+ * ref merge), where global `refs.json` entries still merge over it by
+ * package name. Sourcing it as an ordinary config layer would make it
+ * look user-declared and shut global refs out.
+ */
+export const DEFAULT_CONFIG: DefaultConfig = parseDefaultsDocument();

package/src/config/defaults.json

@@ -0,0 +1,17 @@
+{
+  "channel": "normal",
+  "packages": [
+    {
+      "name": "@canonical/design-system",
+      "source": "git+https://github.com/canonical/design-system.git#main"
+    },
+    {
+      "name": "@canonical/anatomy-dsl",
+      "source": "git+https://github.com/canonical/anatomy-dsl.git#main"
+    },
+    {
+      "name": "@canonical/code-standards",
+      "source": "git+https://github.com/canonical/web-code-standards.git#main"
+    }
+  ]
+}

package/src/config/findProjectConfigPath.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 findProjectConfigPath from "./findProjectConfigPath.js";
+
+describe("findProjectConfigPath", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "pragma-find-config-"));
+    mkdirSync(join(root, ".git"));
+    mkdirSync(join(root, "packages/app/src"), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("finds the config in the starting directory", () => {
+    writeFileSync(join(root, "packages/app/pragma.config.json"), "{}");
+    expect(findProjectConfigPath(join(root, "packages/app"))).toBe(
+      join(root, "packages/app/pragma.config.json"),
+    );
+  });
+
+  it("walks up to the nearest config", () => {
+    writeFileSync(join(root, "pragma.config.json"), "{}");
+    expect(findProjectConfigPath(join(root, "packages/app/src"))).toBe(
+      join(root, "pragma.config.json"),
+    );
+  });
+
+  it("prefers the nearest config over a higher one", () => {
+    writeFileSync(join(root, "pragma.config.json"), "{}");
+    writeFileSync(join(root, "packages/app/pragma.config.json"), "{}");
+    expect(findProjectConfigPath(join(root, "packages/app/src"))).toBe(
+      join(root, "packages/app/pragma.config.json"),
+    );
+  });
+
+  it("stops at the repository root (.git) without escaping", () => {
+    // The fixture root has .git and no config; nothing above it may leak in.
+    expect(findProjectConfigPath(join(root, "packages/app/src"))).toBe(
+      undefined,
+    );
+  });
+
+  it("checks the .git directory's own level before stopping", () => {
+    writeFileSync(join(root, "pragma.config.json"), "{}");
+    expect(findProjectConfigPath(root)).toBe(join(root, "pragma.config.json"));
+  });
+});

package/src/config/findProjectConfigPath.ts

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Find the nearest `pragma.config.json` at or above `cwd`.
+ *
+ * Walks up the directory tree so pragma works from anywhere inside a
+ * project. The walk is bounded: it stops after checking the first
+ * directory that contains `.git` (the repository root), after checking
+ * the home directory, and at the filesystem root — a config outside the
+ * repository or home never leaks in.
+ *
+ * @param cwd - Directory to start from.
+ * @returns Absolute path of the nearest config file, or `undefined`.
+ * @note Impure — probes the filesystem while walking up.
+ */
+export default function findProjectConfigPath(cwd: string): string | undefined {
+  const home = homedir();
+  let dir = resolve(cwd);
+
+  while (true) {
+    const candidate = join(dir, "pragma.config.json");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    if (existsSync(join(dir, ".git")) || dir === home) {
+      return undefined;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}

package/src/config/index.ts

@@ -1,6 +1,21 @@
-/** @module Configuration file reading, writing, and path resolution. */
+/** @module Configuration reading, writing, layered resolution, and paths. */
 export { default as configExists } from "./configExists.js";
+export { default as findProjectConfigPath } from "./findProjectConfigPath.js";
+export { default as mergeConfigFileUpdate } from "./mergeConfigFileUpdate.js";
+export { default as parseConfigValues } from "./parseConfigValues.js";
 export { default as readConfig } from "./readConfig.js";
+export { default as readConfigLayers } from "./readConfigLayers.js";
 export { default as resolveConfigPath } from "./resolveConfigPath.js";
-export type { ConfigUpdate, PragmaConfig } from "./types.js";
+export { default as resolveGlobalConfigPath } from "./resolveGlobalConfigPath.js";
+export { default as resolveWriteConfigPath } from "./resolveWriteConfigPath.js";
+export type {
+  ConfigFileValues,
+  ConfigLayer,
+  ConfigLayers,
+  ConfigOrigin,
+  ConfigOrigins,
+  ConfigScope,
+  ConfigUpdate,
+  PragmaConfig,
+} from "./types.js";
 export { default as writeConfig } from "./writeConfig.js";

package/src/config/mergeConfigFileUpdate.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import type { ConfigUpdate } from "./types.js";
+
+/**
+ * Compute a config file's new contents after applying an update.
+ *
+ * Reads the target file itself (not the merged layers — a write must
+ * never copy values from another layer into this file), applies the
+ * update per field (`undefined` with the key present removes the field),
+ * and returns the serialized JSON. Unknown keys already in the file are
+ * preserved verbatim.
+ *
+ * @param configPath - Absolute path of the config file to update.
+ * @param update - Fields to set or remove.
+ * @returns The file's new contents, newline-terminated.
+ * @throws The raw filesystem/parse error when the existing file is
+ *   present but unreadable or not valid JSON — never silently clobbers.
+ * @note Impure — reads the current file contents.
+ */
+export default function mergeConfigFileUpdate(
+  configPath: string,
+  update: ConfigUpdate,
+): string {
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    existing = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err: unknown) {
+    // Only swallow "file not found" — surface parse or permission errors.
+    const isNotFound =
+      err instanceof Error &&
+      "code" in err &&
+      (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (!isNotFound) {
+      throw err;
+    }
+  }
+
+  applyField(existing, update, "tier");
+  applyField(existing, update, "channel");
+  applyField(existing, update, "packages");
+  applyField(existing, update, "trace");
+  applyField(existing, update, "framework");
+
+  return `${JSON.stringify(existing, null, 2)}\n`;
+}
+
+function applyField(
+  existing: Record<string, unknown>,
+  update: ConfigUpdate,
+  field: keyof ConfigUpdate,
+): void {
+  if (update[field] !== undefined) {
+    existing[field] = update[field];
+  } else if (field in update) {
+    delete existing[field];
+  }
+}

package/src/config/parseConfigValues.ts

@@ -0,0 +1,217 @@
+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);
+  const detail = typeof parsed.detail === "string" ? parsed.detail : undefined;
+
+  return {
+    ...(tier !== undefined ? { tier } : {}),
+    ...(channel !== undefined ? { channel } : {}),
+    ...(packages ? { packages } : {}),
+    ...(trace !== undefined ? { trace } : {}),
+    ...(framework !== undefined ? { framework } : {}),
+    ...(stories ? { stories } : {}),
+    ...(prefixes ? { prefixes } : {}),
+    ...(detail !== undefined ? { detail } : {}),
+  };
+}
+
+/**
+ * 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;
+}