@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/shared/loaders/localLoader.ts

@@ -28,30 +28,14 @@ export default function createLocalLoader(): PackageLoader {
       // file:// refs → direct path check first
       if (ref.kind === "file") {
         if (!existsSync(ref.path)) return undefined;
-        const { version, graphs, skills, stories } = readPackageDir(ref.path);
-        return {
-          name: ref.pkg,
-          version,
-          source: "local",
-          graphs,
-          skills,
-          stories,
-        };
+        return { name: ref.pkg, source: "local", ...readPackageDir(ref.path) };
       }
 
       // All ref kinds → try node_modules walk
       const dir = findPackageDir(ref.pkg);
       if (!dir) return undefined;
 
-      const { version, graphs, skills, stories } = readPackageDir(dir);
-      return {
-        name: ref.pkg,
-        version,
-        source: "local",
-        graphs,
-        skills,
-        stories,
-      };
+      return { name: ref.pkg, source: "local", ...readPackageDir(dir) };
     },
   };
 }

package/src/domains/shared/loaders/readPackageDir.test.ts

@@ -0,0 +1,58 @@
+import { 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 readPackageDir from "./readPackageDir.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "pragma-readpkg-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/** Write a package.json into the temp package root. */
+function writeManifest(manifest: unknown): void {
+  writeFileSync(join(dir, "package.json"), JSON.stringify(manifest), "utf-8");
+}
+
+describe("readPackageDir — prefixes", () => {
+  it("reads package-declared prefixes from package.json pragma.prefixes", () => {
+    writeManifest({
+      version: "1.2.3",
+      pragma: { prefixes: { ds: "https://ds.canonical.com/" } },
+    });
+    const { version, prefixes } = readPackageDir(dir);
+    expect(version).toBe("1.2.3");
+    expect(prefixes).toEqual({ ds: "https://ds.canonical.com/" });
+  });
+
+  it("omits prefixes when the package declares none", () => {
+    writeManifest({ version: "1.0.0" });
+    expect(readPackageDir(dir).prefixes).toBeUndefined();
+  });
+
+  it("ignores a malformed pragma.prefixes field", () => {
+    writeManifest({ version: "1.0.0", pragma: { prefixes: "not-an-object" } });
+    expect(readPackageDir(dir).prefixes).toBeUndefined();
+  });
+
+  it("keeps only string-valued prefix entries", () => {
+    writeManifest({
+      version: "1.0.0",
+      pragma: { prefixes: { ds: "https://ds.canonical.com/", bad: 42 } },
+    });
+    expect(readPackageDir(dir).prefixes).toEqual({
+      ds: "https://ds.canonical.com/",
+    });
+  });
+
+  it("returns a default version and no prefixes when package.json is absent", () => {
+    const contents = readPackageDir(dir);
+    expect(contents.version).toBe("0.0.0");
+    expect(contents.prefixes).toBeUndefined();
+  });
+});

package/src/domains/shared/loaders/readPackageDir.ts

@@ -38,6 +38,7 @@ const TTL_DIRS: readonly { dir: string; glob: string }[] = [
 export interface PackageDirContents {
   readonly version: string;
   readonly graphs: GraphContent[];
+  readonly prefixes?: Readonly<Record<string, string>>;
   readonly skills: SkillEntry[];
   readonly stories: StoryFileEntry[];
 }
@@ -46,12 +47,15 @@ export interface PackageDirContents {
  * Read semantic package content from a directory.
  *
  * @param dir - Absolute path to the package root directory.
- * @returns Package version, TTL graph content, and skill entries.
+ * @returns Package version, TTL graph content, declared prefixes, and skills.
  */
 export default function readPackageDir(dir: string): PackageDirContents {
+  const manifest = readManifest(dir);
+  const prefixes = parsePrefixesField(manifest);
   return {
-    version: readVersion(dir),
+    version: typeof manifest.version === "string" ? manifest.version : "0.0.0",
     graphs: readGraphs(dir),
+    ...(prefixes ? { prefixes } : {}),
     skills: readSkills(dir),
     stories: readStories(dir),
   };
@@ -61,15 +65,49 @@ export default function readPackageDir(dir: string): PackageDirContents {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function readVersion(dir: string): string {
-  const pjsonPath = join(dir, "package.json");
+/** A package.json shape with the fields this loader reads. */
+interface PackageManifest {
+  readonly version?: unknown;
+  readonly pragma?: unknown;
+}
+
+/** Read and parse `package.json`, returning an empty object on failure. */
+function readManifest(dir: string): PackageManifest {
   try {
-    const raw = readFileSync(pjsonPath, "utf-8");
-    const parsed = JSON.parse(raw) as { version?: string };
-    return parsed.version ?? "0.0.0";
+    return JSON.parse(
+      readFileSync(join(dir, "package.json"), "utf-8"),
+    ) as PackageManifest;
   } catch {
-    return "0.0.0";
+    return {};
+  }
+}
+
+/**
+ * Extract package-declared prefixes from a parsed manifest.
+ *
+ * Convention: a package declares its namespaces under
+ * `pragma.prefixes` in `package.json`, e.g.
+ * `{ "pragma": { "prefixes": { "ds": "https://ds.canonical.com/" } } }`.
+ * Chosen over a separate file because the manifest is already read for the
+ * version, keeping the convention zero-extra-file and discoverable. Only
+ * string→string entries are kept; malformed shapes are ignored so one bad
+ * field cannot break boot.
+ *
+ * @returns The declared prefix map, or `undefined` when none is present.
+ */
+function parsePrefixesField(
+  manifest: PackageManifest,
+): Readonly<Record<string, string>> | undefined {
+  const pragma = manifest.pragma;
+  if (typeof pragma !== "object" || pragma === null) return undefined;
+  const raw = (pragma as { prefixes?: unknown }).prefixes;
+  if (typeof raw !== "object" || raw === null) return undefined;
+
+  const prefixes: Record<string, string> = {};
+  for (const [name, namespace] of Object.entries(raw)) {
+    if (typeof namespace === "string") prefixes[name] = namespace;
   }
+  return Object.keys(prefixes).length > 0 ? prefixes : undefined;
 }
 
 function readGraphs(dir: string): GraphContent[] {

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

@@ -88,6 +88,21 @@ describe("lookupMany", () => {
     ]);
     expect(result.meta).toEqual({ internalErrorCount: 2 });
   });
+
+  it("reclassifies a rejected SPARQL value as INVALID_INPUT, not internal", async () => {
+    const result = await lookupMany(["}; DROP"], async (q) => {
+      throw new Error(
+        `Potentially dangerous SPARQL value rejected: ${JSON.stringify(q)}`,
+      );
+    });
+
+    expect(result.results).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors.at(0)?.code).toBe("INVALID_INPUT");
+    expect(result.errors.at(0)?.message).not.toContain("Internal error");
+    // A rejected value is user input, so it is not counted as an internal fault.
+    expect(result.meta).toEqual({ internalErrorCount: 0 });
+  });
 });
 
 describe("lookupToolMeta", () => {

package/src/domains/shared/lookupMany.ts

@@ -1,6 +1,13 @@
 import { PragmaError } from "#error";
 import type { LookupResult } from "./contracts.js";
 
+/**
+ * Marker in the ke SPARQL guard's rejection message. A rejected value is user
+ * input, not an internal fault, so it is reclassified as INVALID_INPUT rather
+ * than mislabelled as an internal error.
+ */
+const SPARQL_REJECTION_MARKER = "Potentially dangerous SPARQL value rejected";
+
 /**
  * Resolve multiple lookup queries and collect structured per-query failures.
  *
@@ -51,13 +58,22 @@ export default async function lookupMany<TResult>(
         }),
       });
     } else {
-      internalErrorCount += 1;
       const reason = error instanceof Error ? error.message : String(error);
-      errors.push({
-        query,
-        code: "INTERNAL_ERROR",
-        message: `Internal error: ${reason}`,
-      });
+      if (reason.includes(SPARQL_REJECTION_MARKER)) {
+        // A rejected value is invalid user input, not an internal fault.
+        errors.push({
+          query,
+          code: "INVALID_INPUT",
+          message: `Invalid lookup value "${query}": rejected as unsafe.`,
+        });
+      } else {
+        internalErrorCount += 1;
+        errors.push({
+          query,
+          code: "INTERNAL_ERROR",
+          message: `Internal error: ${reason}`,
+        });
+      }
     }
   }
 

package/src/domains/shared/namespaces.ts

@@ -6,12 +6,20 @@
  */
 
 import { createNamespace } from "@canonical/ke";
-import { PREFIX_MAP } from "./prefixes.js";
+import { PREFIX_MAP, TRANSITIONAL_DS_PREFIX_MAP } from "./prefixes.js";
 
-/** Design system namespace — classes, properties, and instances (e.g., `ds:Component`). */
-export const ds = createNamespace(PREFIX_MAP.ds);
-/** Component specification namespace — component-level metadata (e.g., `cs:anatomy`). */
-export const cs = createNamespace(PREFIX_MAP.cs);
+/**
+ * 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`). */

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

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

@@ -0,0 +1,45 @@
+/**
+ * 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/prefixes.test.ts

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