@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/shared/namespaces.ts

@@ -1,26 +0,0 @@
-/**
- * Namespace helpers for SPARQL queries.
- *
- * Derived from {@link PREFIX_MAP} via {@link createNamespace} for use
- * in the `sparql` tagged template.
- */
-
-import { createNamespace } from "@canonical/ke";
-import { PREFIX_MAP, TRANSITIONAL_DS_PREFIX_MAP } from "./prefixes.js";
-
-/**
- * Design system namespace — classes, properties, and instances (e.g., `ds:Component`).
- * @remarks transitional — sourced from the bundled DS fallback until the
- * design-system package declares its own prefixes (remove in P4).
- */
-export const ds = createNamespace(TRANSITIONAL_DS_PREFIX_MAP.ds);
-/**
- * Component specification namespace — component-level metadata (e.g., `cs:anatomy`).
- * @remarks transitional — sourced from the bundled DS fallback until the
- * code-standards package declares its own prefixes (remove in P4).
- */
-export const cs = createNamespace(TRANSITIONAL_DS_PREFIX_MAP.cs);
-/** RDF Schema namespace — core vocabulary (e.g., `rdfs:label`, `rdfs:subClassOf`). */
-export const rdfs = createNamespace(PREFIX_MAP.rdfs);
-/** OWL namespace — ontology constructs (e.g., `owl:Class`, `owl:ObjectProperty`). */
-export const owl = createNamespace(PREFIX_MAP.owl);

package/src/domains/shared/packages.ts

@@ -1,20 +0,0 @@
-/**
- * Default semantic graph package registry.
- *
- * Sourced from the declarative built-in defaults document
- * (`src/config/defaults.json`) — pragma core carries no hardcoded
- * knowledge of specific design-system packages. These form the base
- * package set whenever a config layer does not declare a non-empty
- * `packages` list; global `refs.json` entries then merge over them by
- * package name, and a non-empty config list replaces them entirely
- * (see `mergeAndParseRefs`).
- *
- * Resolution is handled by the loader chain in `loaders/`.
- */
-
-import { DEFAULT_CONFIG } from "../../config/defaultConfig.js";
-import type { RawPackageEntry } from "../refs/operations/parseRef.js";
-
-/** Default semantic graph packages loaded when no config overrides are present. */
-export const DEFAULT_PACKAGES: readonly RawPackageEntry[] =
-  DEFAULT_CONFIG.packages;

package/src/domains/shared/parseSampleCount.test.ts

@@ -1,47 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "../../error/index.js";
-import parseSampleCount, {
-  DEFAULT_SAMPLE_COUNT,
-  MAX_SAMPLE_COUNT,
-  MIN_SAMPLE_COUNT,
-} from "./parseSampleCount.js";
-
-describe("parseSampleCount", () => {
-  it("returns the default for undefined/null/empty input", () => {
-    expect(parseSampleCount(undefined)).toBe(DEFAULT_SAMPLE_COUNT);
-    expect(parseSampleCount(null)).toBe(DEFAULT_SAMPLE_COUNT);
-    expect(parseSampleCount("")).toBe(DEFAULT_SAMPLE_COUNT);
-  });
-
-  it("accepts an in-range integer verbatim", () => {
-    expect(parseSampleCount("3")).toBe(3);
-    expect(parseSampleCount(4)).toBe(4);
-  });
-
-  it("clamps below the minimum and above the maximum", () => {
-    expect(parseSampleCount("0")).toBe(MIN_SAMPLE_COUNT);
-    expect(parseSampleCount("-3")).toBe(MIN_SAMPLE_COUNT);
-    expect(parseSampleCount("99")).toBe(MAX_SAMPLE_COUNT);
-  });
-
-  it("tolerates surrounding whitespace", () => {
-    expect(parseSampleCount(" 3 ")).toBe(3);
-  });
-
-  it.each([
-    "abc",
-    "3.5",
-    "0x5",
-    "1e1",
-    "3,4",
-    "NaN",
-    "Infinity",
-  ])("throws INVALID_INPUT for the non-integer value %j", (value) => {
-    expect(() => parseSampleCount(value)).toThrowError(PragmaError);
-    try {
-      parseSampleCount(value);
-    } catch (error) {
-      expect((error as PragmaError).code).toBe("INVALID_INPUT");
-    }
-  });
-});

package/src/domains/shared/parseSampleCount.ts

@@ -1,45 +0,0 @@
-/**
- * Parse and validate the `--count` argument shared by every `sample` command.
- *
- * A missing count falls back to the default. A non-numeric or non-integer
- * value is rejected as invalid input (so the command exits non-zero) rather
- * than silently coercing to `NaN` and returning zero samples. A valid integer
- * is clamped to the supported 1–5 range.
- */
-
-import { PragmaError } from "#error";
-
-/** Smallest number of samples a `sample` command will return. */
-export const MIN_SAMPLE_COUNT = 1;
-/** Largest number of samples a `sample` command will return. */
-export const MAX_SAMPLE_COUNT = 5;
-/** Number of samples returned when `--count` is omitted. */
-export const DEFAULT_SAMPLE_COUNT = 2;
-
-/**
- * Resolve the raw `--count` param into a clamped sample count.
- *
- * @param raw - The raw param value (`params.count`), possibly undefined.
- * @returns An integer in [MIN_SAMPLE_COUNT, MAX_SAMPLE_COUNT].
- * @throws PragmaError INVALID_INPUT when `raw` is present but not an integer.
- */
-export default function parseSampleCount(raw: unknown): number {
-  if (raw === undefined || raw === null || raw === "") {
-    return DEFAULT_SAMPLE_COUNT;
-  }
-
-  // Accept only a plain decimal integer. Number() would otherwise coerce hex
-  // ("0x5"), scientific ("1e1"), and whitespace-padded forms, none of which a
-  // user should be able to pass to --count.
-  const text = String(raw).trim();
-  if (!/^-?\d+$/.test(text)) {
-    throw PragmaError.invalidInput("count", String(raw), {
-      recovery: {
-        message: `Provide an integer between ${MIN_SAMPLE_COUNT} and ${MAX_SAMPLE_COUNT}.`,
-      },
-    });
-  }
-
-  const parsed = Number(text);
-  return Math.max(MIN_SAMPLE_COUNT, Math.min(MAX_SAMPLE_COUNT, parsed));
-}

package/src/domains/shared/pickRandom.ts

@@ -1,22 +0,0 @@
-/**
- * Pick `count` random items from an array without replacement.
- *
- * Uses Fisher-Yates partial shuffle for uniform distribution.
- * Returns at most `arr.length` items if count exceeds the array size.
- */
-export default function pickRandom<T>(
-  arr: readonly T[],
-  count: number,
-): readonly T[] {
-  const n = Math.min(count, arr.length);
-  if (n === 0) return [];
-
-  const copy = [...arr];
-  for (let i = 0; i < n; i++) {
-    const j = i + Math.floor(Math.random() * (copy.length - i));
-    const tmp = copy[i];
-    copy[i] = copy[j] as T;
-    copy[j] = tmp as T;
-  }
-  return copy.slice(0, n);
-}

package/src/domains/shared/prefixes.test.ts

@@ -1,211 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  DEFAULT_PREFIX_MAP,
-  P,
-  PREFIX_MAP,
-  resolvePrefixes,
-  TRANSITIONAL_DS_PREFIX_MAP,
-  TTL_PREFIXES,
-} from "./prefixes.js";
-
-describe("core PREFIX_MAP", () => {
-  it("ships only generic RDF vocabularies — no design-system prefixes", () => {
-    expect(Object.keys(PREFIX_MAP).sort()).toEqual([
-      "owl",
-      "rdf",
-      "rdfs",
-      "skos",
-      "xsd",
-    ]);
-    expect(PREFIX_MAP).not.toHaveProperty("ds");
-    expect(PREFIX_MAP).not.toHaveProperty("cs");
-  });
-});
-
-describe("TRANSITIONAL_DS_PREFIX_MAP", () => {
-  it("bundles the design-system prefixes separately from the core", () => {
-    expect(TRANSITIONAL_DS_PREFIX_MAP).toEqual({
-      ds: "https://ds.canonical.com/",
-      cs: "http://pragma.canonical.com/codestandards#",
-    });
-  });
-});
-
-describe("DEFAULT_PREFIX_MAP (display set)", () => {
-  it("reproduces the pre-P0 compaction set — ds/cs plus rdfs/owl/skos", () => {
-    expect(Object.keys(DEFAULT_PREFIX_MAP).sort()).toEqual([
-      "cs",
-      "ds",
-      "owl",
-      "rdfs",
-      "skos",
-    ]);
-  });
-
-  it("omits rdf/xsd so URI compaction in output is unchanged", () => {
-    expect(DEFAULT_PREFIX_MAP).not.toHaveProperty("rdf");
-    expect(DEFAULT_PREFIX_MAP).not.toHaveProperty("xsd");
-  });
-});
-
-describe("P accessor", () => {
-  it("exposes prefixed-name accessors including the transitional ds/cs", () => {
-    expect(P.ds).toBe("ds:");
-    expect(P.cs).toBe("cs:");
-    expect(P.rdfs).toBe("rdfs:");
-    expect(P.owl).toBe("owl:");
-    expect(P.skos).toBe("skos:");
-  });
-});
-
-describe("TTL_PREFIXES", () => {
-  it("declares every display prefix plus xsd", () => {
-    expect(TTL_PREFIXES).toContain("@prefix ds: <https://ds.canonical.com/> .");
-    expect(TTL_PREFIXES).toContain(
-      "@prefix cs: <http://pragma.canonical.com/codestandards#> .",
-    );
-    expect(TTL_PREFIXES).toContain(
-      "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
-    );
-  });
-});
-
-describe("resolvePrefixes", () => {
-  it("returns core plus the transitional DS fallback for a bare core", () => {
-    const resolved = resolvePrefixes([]);
-    expect(resolved).toEqual({ ...PREFIX_MAP, ...TRANSITIONAL_DS_PREFIX_MAP });
-  });
-
-  it("layers package-declared prefixes over the fallback", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { ex: "https://example.org/" } },
-    ]);
-    expect(resolved.ex).toBe("https://example.org/");
-    // core + fallback still present
-    expect(resolved.ds).toBe(TRANSITIONAL_DS_PREFIX_MAP.ds);
-    expect(resolved.rdf).toBe(PREFIX_MAP.rdf);
-  });
-
-  it("lets a package override the transitional DS fallback", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { ds: "https://packaged-ds.example/" } },
-    ]);
-    expect(resolved.ds).toBe("https://packaged-ds.example/");
-  });
-
-  it("lets config prefixes win over both packages and the fallback", () => {
-    const resolved = resolvePrefixes(
-      [{ prefixes: { ds: "https://packaged-ds.example/" } }],
-      { ds: "https://config-ds.example/" },
-    );
-    expect(resolved.ds).toBe("https://config-ds.example/");
-  });
-
-  it("merges multiple packages in array order", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { a: "https://one.example/" } },
-      { prefixes: { a: "https://two.example/", b: "https://b.example/" } },
-    ]);
-    expect(resolved.a).toBe("https://two.example/");
-    expect(resolved.b).toBe("https://b.example/");
-  });
-
-  it("tolerates packages that declare no prefixes", () => {
-    const resolved = resolvePrefixes([{}, { prefixes: undefined }]);
-    expect(resolved).toEqual({ ...PREFIX_MAP, ...TRANSITIONAL_DS_PREFIX_MAP });
-  });
-});
-
-describe("resolvePrefixes — injection & shadowing hardening", () => {
-  let warnings: string[];
-  let write: typeof process.stderr.write;
-
-  beforeEach(() => {
-    warnings = [];
-    write = process.stderr.write;
-    process.stderr.write = ((chunk: string | Uint8Array) => {
-      warnings.push(String(chunk));
-      return true;
-    }) as typeof process.stderr.write;
-  });
-
-  afterEach(() => {
-    process.stderr.write = write;
-  });
-
-  it("drops a namespace that could break out of the SPARQL IRIREF", () => {
-    // A `>` would close `<...>` early and inject arbitrary SPARQL into every
-    // query the store runs.
-    const resolved = resolvePrefixes([
-      { prefixes: { evil: "http://e> SELECT * WHERE {?s ?p ?o} #" } },
-    ]);
-    expect(resolved).not.toHaveProperty("evil");
-    expect(warnings.join("")).toContain("not valid in an IRI");
-  });
-
-  it("rejects namespaces containing whitespace or angle/quote/brace chars", () => {
-    const resolved = resolvePrefixes([
-      {
-        prefixes: {
-          space: "http://e /x",
-          quote: 'http://e"x',
-          brace: "http://e{x}",
-        },
-      },
-    ]);
-    expect(resolved).not.toHaveProperty("space");
-    expect(resolved).not.toHaveProperty("quote");
-    expect(resolved).not.toHaveProperty("brace");
-  });
-
-  it("keeps a clean namespace untouched", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { ex: "https://example.org/ns#" } },
-    ]);
-    expect(resolved.ex).toBe("https://example.org/ns#");
-    expect(warnings).toHaveLength(0);
-  });
-
-  it("refuses to let a package redefine a reserved core prefix", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { rdf: "https://evil.example/rdf#" } },
-    ]);
-    expect(resolved.rdf).toBe(PREFIX_MAP.rdf);
-    expect(warnings.join("")).toContain("reserved");
-  });
-
-  it("refuses reserved prefixes from config too", () => {
-    const resolved = resolvePrefixes([], { owl: "https://evil.example/owl#" });
-    expect(resolved.owl).toBe(PREFIX_MAP.owl);
-  });
-
-  it("skips a malformed prefix name", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { "bad name!": "https://example.org/" } },
-    ]);
-    expect(resolved).not.toHaveProperty("bad name!");
-    expect(warnings.join("")).toContain("not a valid prefix name");
-  });
-
-  it("warns on a last-wins collision between two packages", () => {
-    const resolved = resolvePrefixes([
-      { prefixes: { a: "https://one.example/" } },
-      { prefixes: { a: "https://two.example/" } },
-    ]);
-    expect(resolved.a).toBe("https://two.example/");
-    expect(warnings.join("")).toContain("overrides an earlier declaration");
-  });
-
-  it("names the declaring package in collision warnings when available", () => {
-    resolvePrefixes([
-      { name: "@canonical/one", prefixes: { a: "https://one.example/" } },
-      { name: "@canonical/two", prefixes: { a: "https://two.example/" } },
-    ]);
-    expect(warnings.join("")).toContain('package "@canonical/two"');
-  });
-
-  it("does not warn when a package overrides the trusted DS fallback", () => {
-    resolvePrefixes([{ prefixes: { ds: "https://packaged-ds.example/" } }]);
-    expect(warnings).toHaveLength(0);
-  });
-});

package/src/domains/shared/prefixes.ts

@@ -1,204 +0,0 @@
-/**
- * Prefix maps for ke store creation and display compaction.
- *
- * The core ships only generic RDF vocabularies. Domain prefixes (e.g. the
- * design system's `ds:`/`cs:`) are supplied by the loaded semantic
- * packages and merged over the core at boot via {@link resolvePrefixes}.
- * Renaming a key here updates every derived accessor automatically.
- */
-
-import type { PrefixMap } from "@canonical/ke";
-
-/**
- * Core prefix map — the generic RDF vocabularies pragma itself ships.
- *
- * Registered as PREFIX declarations in every SPARQL query and used as the
- * base of the effective prefix map. Contains no domain-specific prefixes:
- * `ds:`/`cs:` and any other package namespaces arrive from the resolved
- * semantic packages (see {@link resolvePrefixes}).
- */
-export const PREFIX_MAP = {
-  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
-  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
-  owl: "http://www.w3.org/2002/07/owl#",
-  skos: "http://www.w3.org/2004/02/skos/core#",
-  xsd: "http://www.w3.org/2001/XMLSchema#",
-} as const satisfies PrefixMap;
-
-/**
- * Transitional design-system prefixes bundled with the core.
- *
- * @remarks transitional — remove in P4. These belong to the
- * `@canonical/design-system` and `@canonical/code-standards` packages and
- * must move into their own prefix declarations. Until those packages
- * declare `pragma.prefixes`, this bundled fallback keeps existing DS
- * queries resolving and DS IRIs compacting in output. Package-declared
- * prefixes (and config overrides) win over this fallback.
- */
-export const TRANSITIONAL_DS_PREFIX_MAP = {
-  ds: "https://ds.canonical.com/",
-  cs: "http://pragma.canonical.com/codestandards#",
-} as const satisfies PrefixMap;
-
-/**
- * The default display/compaction prefix set and the base of the derived
- * accessors — the exact set compacted before P0 split the core from the
- * design system, kept stable during the transition.
- *
- * Deliberately omits `rdf:`/`xsd:` (present in {@link PREFIX_MAP}) so URI
- * compaction in output is unchanged from pre-P0 behavior; the store's
- * query prefix map (see {@link resolvePrefixes}) still carries them.
- *
- * @remarks transitional — the `ds:`/`cs:` members move to their packages
- * in P4, at which point this collapses toward {@link PREFIX_MAP}. Runtime
- * code should prefer the map from {@link resolvePrefixes}, which layers in
- * package-declared and config prefixes over the store base.
- */
-export const DEFAULT_PREFIX_MAP = {
-  ds: TRANSITIONAL_DS_PREFIX_MAP.ds,
-  cs: TRANSITIONAL_DS_PREFIX_MAP.cs,
-  rdfs: PREFIX_MAP.rdfs,
-  owl: PREFIX_MAP.owl,
-  skos: PREFIX_MAP.skos,
-} as const satisfies PrefixMap;
-
-/**
- * Core prefixes reserved for pragma's own vocabularies. Packages and config
- * may not redefine these — every query and the RDF/OWL/SKOS toolchain depend
- * on them resolving to the canonical W3C namespaces, so a package that shadows
- * `rdf:` (accidentally or maliciously) would silently corrupt every query.
- */
-const RESERVED_PREFIXES: ReadonlySet<string> = new Set(Object.keys(PREFIX_MAP));
-
-/** A syntactically safe SPARQL prefix name (PN_PREFIX subset we accept). */
-const SAFE_PREFIX_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
-
-/**
- * Reject a namespace that cannot appear inside a SPARQL `<IRIREF>` unescaped.
- * ke injects prefixes verbatim as `PREFIX name: <iri>`; a namespace containing
- * `>` (or whitespace/control/`<"{}|^`\``) would break out of the IRI and inject
- * arbitrary SPARQL into every query. SPARQL's IRIREF grammar forbids exactly
- * these, so anything matching is both unsafe and invalid Turtle/SPARQL.
- */
-// biome-ignore lint/suspicious/noControlCharactersInRegex: IRIREF forbids U+0000–U+0020 by grammar
-const UNSAFE_NAMESPACE = /[\x00-\x20<>"{}|^`\\]/;
-
-/**
- * Validate and merge one source of declared prefixes onto an accumulator.
- *
- * Skips (with a stderr warning) any entry that is unsafe to inject: a
- * malformed prefix name, a namespace that could break out of the SPARQL
- * IRIREF, or an attempt to redefine a reserved core prefix. Also warns when a
- * later source silently overrides an already-declared prefix (last-wins
- * collision), so a name clash between two packages is visible rather than
- * mysterious.
- *
- * @note Impure — writes warnings to stderr.
- */
-function mergePrefixSource(
-  acc: Record<string, string>,
-  claimed: Set<string>,
-  source: Readonly<Record<string, string>> | undefined,
-  origin: string,
-): void {
-  if (!source) return;
-  for (const [name, namespace] of Object.entries(source)) {
-    if (!SAFE_PREFIX_NAME.test(name)) {
-      process.stderr.write(
-        `Warning: ignoring prefix "${name}" from ${origin} — not a valid prefix name.\n`,
-      );
-      continue;
-    }
-    if (RESERVED_PREFIXES.has(name)) {
-      process.stderr.write(
-        `Warning: ignoring prefix "${name}" from ${origin} — "${name}:" is reserved for a core RDF vocabulary and cannot be redefined.\n`,
-      );
-      continue;
-    }
-    if (UNSAFE_NAMESPACE.test(namespace)) {
-      process.stderr.write(
-        `Warning: ignoring prefix "${name}" from ${origin} — namespace contains characters that are not valid in an IRI.\n`,
-      );
-      continue;
-    }
-    // Warn only on a collision between two *validated* sources (package vs.
-    // package/config). Silently overriding the trusted DS fallback is the
-    // expected transitional handoff, not a clash.
-    if (claimed.has(name) && acc[name] !== namespace) {
-      process.stderr.write(
-        `Warning: prefix "${name}" from ${origin} overrides an earlier declaration (was <${acc[name]}>, now <${namespace}>).\n`,
-      );
-    }
-    acc[name] = namespace;
-    claimed.add(name);
-  }
-}
-
-/**
- * Resolve the effective prefix map for a boot.
- *
- * Precedence (lowest → highest): the generic {@link PREFIX_MAP}, the
- * transitional DS fallback, prefixes declared by resolved packages (in
- * array order), then config-level overrides. A package that declares its
- * own `ds:`/`cs:` therefore overrides the bundled fallback, and a user's
- * `pragma.config.json` `prefixes` wins over everything.
- *
- * Package- and config-declared prefixes are validated before they reach the
- * store: unsafe names/namespaces are skipped (they would otherwise be injected
- * verbatim into every SPARQL query), reserved core prefixes cannot be
- * redefined, and last-wins collisions are surfaced as warnings. The bundled
- * core and DS fallback are trusted and merged as-is.
- *
- * @param packages - Resolved packages, each optionally declaring prefixes.
- * @param configPrefixes - Config-level prefix overrides.
- * @returns The merged prefix map for the store and every query.
- */
-export function resolvePrefixes(
-  packages: readonly {
-    readonly name?: string;
-    readonly prefixes?: Readonly<Record<string, string>>;
-  }[] = [],
-  configPrefixes?: Readonly<Record<string, string>>,
-): Record<string, string> {
-  const merged: Record<string, string> = {
-    ...PREFIX_MAP,
-    ...TRANSITIONAL_DS_PREFIX_MAP,
-  };
-  // Keys claimed by a validated source, so collisions between two such
-  // sources warn while overriding the trusted seed stays silent.
-  const claimed = new Set<string>();
-  for (const pkg of packages) {
-    // Name the declaring package in the origin so collision/injection
-    // warnings point at the actual source, not a generic placeholder.
-    const origin = pkg.name ? `package "${pkg.name}"` : "a semantic package";
-    mergePrefixSource(merged, claimed, pkg.prefixes, origin);
-  }
-  mergePrefixSource(merged, claimed, configPrefixes, "pragma.config.json");
-  return merged;
-}
-
-/**
- * SPARQL prefix accessors derived from {@link DEFAULT_PREFIX_MAP}.
- *
- * Use in query templates: `${P.ds}Component` → `"ds:Component"`.
- * Renaming a key in the underlying maps automatically updates every query.
- *
- * @remarks The `ds:`/`cs:` accessors are transitional (see
- * {@link TRANSITIONAL_DS_PREFIX_MAP}); they resolve at query time against
- * the store's merged prefix map, which the packages now supply.
- */
-export const P = Object.fromEntries(
-  Object.keys(DEFAULT_PREFIX_MAP).map((k) => [k, `${k}:`]),
-) as { readonly [K in keyof typeof DEFAULT_PREFIX_MAP]: `${K}:` };
-
-/**
- * Turtle `@prefix` declarations derived from {@link DEFAULT_PREFIX_MAP},
- * plus `xsd:` — commonly used by TTL data files but omitted from the
- * display set (SPARQL queries auto-inject the store prefix map).
- */
-export const TTL_PREFIXES = [
-  ...Object.entries(DEFAULT_PREFIX_MAP).map(
-    ([k, uri]) => `@prefix ${k}: <${uri}> .`,
-  ),
-  `@prefix xsd: <${PREFIX_MAP.xsd}> .`,
-].join("\n");