@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/kernel/packs/schema.ts

@@ -14,17 +14,50 @@
  * statically by `capabilities/distribution.ts` and never revalidated at dispatch
  * (`collect.projectStoryTiers`'s default-origin carve-out); this runs for config-
  * and package-declared stories, and in `distribution.test.ts`'s round-trip.
+ *
+ * That carve-out is exactly why the rest of the compilability rules are NOT
+ * here. A rule stated only in this file reaches a third-party author at
+ * declaration and the distribution's own stories not at all — they meet it as a
+ * first-call CONFIG_ERROR. Those rules live in {@link ./storyRules}, which
+ * `compileStoryModule` runs for every tier, and {@link refineListShape} reports
+ * them as zod issues so a config author still reads them here, in the same
+ * words and at the same paths.
  */
 
 import { z } from "zod";
 import { DETAIL_LEVELS, RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { PragmaError } from "../error/index.js";
-import type { PackDefinition } from "./types.js";
+import { listShapeIssues, tierScopeIssues } from "./storyRules.js";
+import {
+  type PackDefinition,
+  type PackList,
+  type PackTierScope,
+  RESERVED_STORY_PARAMS,
+} from "./types.js";
 
 const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
 /** Message for {@link NOUN_PATTERN} — third-party authors never see the regex. */
 const NOUN_MESSAGE = 'must be lowercase kebab-case, e.g. "design-token"';
-const FILTER_PARAM_PATTERN = /^[a-z][a-z0-9]*$/;
+/**
+ * A filter's parameter name: lowercase-initial, then letters and digits.
+ *
+ * camelCase is admitted because the PROJECTOR already relies on it —
+ * `emitSurface`'s `emitVerb` writes a flag as `--${kebabCase(param)}`, so a
+ * param named `channelOf` was always going to become `--channel-of`, and only
+ * this gate refused to let anyone declare it. A story wanting a two-word
+ * dimension had no spelling at all: `channel-of` fails the pattern too, and
+ * `channelof` projects to the unreadable `--channelof`.
+ *
+ * This is a WIDENING of what an author may declare, matched to what the
+ * projector already emits, and it closes a tier split rather than opening one:
+ * the distribution's own stories are compiled statically and never revalidated
+ * (see `storyRules.ts`), so `pragma.conf.ts` could already declare a param this
+ * schema would have refused from a package. The same rule now reaches both.
+ *
+ * Still lowercase-INITIAL: a leading capital would kebab to a leading dash and
+ * Commander would read the flag as empty.
+ */
+const FILTER_PARAM_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
 const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const GRAPHQL_NAME_PATTERN = /^[_A-Za-z][_0-9A-Za-z]*$/;
 /**
@@ -38,14 +71,22 @@ const GRAPHQL_NAME_PATTERN = /^[_A-Za-z][_0-9A-Za-z]*$/;
 const TERM_PATTERN =
   /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/[^<>"\s]+|\^?[A-Za-z][\w-]*:[^/<>"\s]+(?:\/\^?[A-Za-z][\w-]*:[^/<>"\s]+)*)$/;
 
-/** Params a filter/verb may not claim (they are the shared read vocabulary). */
-const RESERVED_PARAMS = new Set(["search", "detail", "name", "count"]);
+/** Params a filter/verb may not claim — the kernel's own, from the grammar. */
+const RESERVED_PARAMS = new Set(RESERVED_STORY_PARAMS);
 
 /**
  * Whether an author-supplied query is a SELECT (optionally preceded by its own
  * PREFIX lines). Every author query a story declares runs through `runSelect`,
  * which reads `result.bindings` — so a non-SELECT is a shape mismatch caught
  * here rather than downstream.
+ *
+ * Used for a `vocabulary.query` only, which is run exactly as the author wrote
+ * it. A `list.query` gets the real reader instead ({@link ./storyRules}, via
+ * `sparql/authorQuery.ts`), because this pattern is NARROWER than what a page
+ * can now serve: it admits `PREFIX` lines but not a leading comment, not
+ * `BASE`, and not a lower-case `prefix` — all of which the lift handles. A
+ * grammar that refuses the shape the kernel supports is the same defect as one
+ * that admits the shape it cannot, read from the other side.
  */
 function isSelectQuery(query: string): boolean {
   return /^\s*(?:PREFIX\s+[^\n]*\n\s*)*SELECT\s/i.test(query);
@@ -89,6 +130,12 @@ const filterSchema = z
   .refine((f) => !f.vocabulary || isSelectQuery(f.vocabulary.query), {
     message: '"vocabulary.query" must be a SPARQL SELECT query',
   });
+// A filter must also say WHAT it admits, one way or the other — it used to be
+// able to say neither and fall back to the values the returned ROWS carried,
+// which a page makes actively wrong. That rule is a compilability rule rather
+// than a shape rule, so it is checked in `storyRules.ts` (which the
+// distribution's own stories reach too) and reported from `refineListShape`
+// below at the same `…filters.N` path it always used.
 
 const searchSchema = z
   .object({
@@ -146,6 +193,7 @@ const fieldSchema = z
 
 const sectionSchema = fieldSchema.extend({
   kind: z.enum(["field", "code"]).optional(),
+  note: z.string().optional(),
 });
 
 const nestedExpandSchema = z
@@ -174,6 +222,7 @@ const expandFieldSchema = z
     property: term,
     label: z.string().optional(),
     graphqlField: graphqlName.optional(),
+    blankWhenSelf: z.literal(true).optional(),
   })
   .strict();
 
@@ -187,6 +236,12 @@ const expandSchema = z
     select: z.array(z.union([nestedExpandSchema, expandFieldSchema])).min(1),
     showWhenEmpty: z.boolean().optional(),
     level: z.string().optional(),
+    note: z.string().optional(),
+    orderBy: z.array(fieldName).min(1).optional(),
+    // Only "sparql": see PackExpand.source — the SPARQL lane is every lookup's
+    // default, so an expand opting INTO GraphQL would ask for a document the
+    // lookup never builds.
+    source: z.literal("sparql").optional(),
   })
   .strict();
 
@@ -247,6 +302,24 @@ const scopeWeightSchema = z
   })
   .strict();
 
+/**
+ * The declared tier hierarchy (`PackTierScope`) that SCOPES a noun's reads.
+ *
+ * Four terms, no options: the class whose instances are the tiers, the edge
+ * from an entity to its tier, the tier property whose `/`-separated name IS the
+ * hierarchy, and the base tier every scope keeps. Everything else about the
+ * scope — the default, the ancestors, the escape — is the kernel's rule, not a
+ * knob, so a pack cannot declare a noun that scopes differently from the rest.
+ */
+const tierScopeSchema = z
+  .object({
+    type: term,
+    via: term,
+    by: term,
+    base: term.optional(),
+  })
+  .strict();
+
 const lookupSchema = z
   .object({
     source: z.enum(["sparql", "graphql"]).optional(),
@@ -277,6 +350,7 @@ const definitionSchema = z
     verbs: z.array(verbSchema).min(1).optional(),
     lookup: lookupSchema.optional(),
     colophon: z.string().optional(),
+    tierScope: tierScopeSchema.optional(),
   })
   .strict()
   .superRefine((def, ctx) => {
@@ -286,17 +360,19 @@ const definitionSchema = z
         message: 'a pack must declare at least one of "list" or "lookup".',
       });
     }
-    if (def.list && !isSelectQuery(def.list.query)) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: '"list.query" must be a SPARQL SELECT query.',
-        path: ["list", "query"],
-      });
-    }
+    // "must be a SELECT" for a `list.query` is `refineListShape`'s to say, and
+    // it says it from the reader that actually splits the query — which admits
+    // the prologue shapes this file's own pattern does not.
     refineVerbNames(def, ctx);
-    if (def.list) refineFilterParams(def.list.filters, ["list"], ctx);
+    if (def.list) {
+      refineFilterParams(def.list.filters, ["list"], ctx);
+      refineListShape(def.list, ["list"], ctx);
+      refineTierScope(def.tierScope, def.list, ["list"], ctx);
+    }
     for (const [index, verb] of (def.verbs ?? []).entries()) {
       refineFilterParams(verb.filters, ["verbs", index], ctx);
+      refineListShape(verb, ["verbs", index], ctx);
+      refineTierScope(def.tierScope, verb, ["verbs", index], ctx);
     }
     if (def.lookup) refineLookup(def.lookup, ctx);
   });
@@ -360,6 +436,60 @@ function refineFilterParams(
   }
 }
 
+/**
+ * The COMPILABILITY rules for one list-shaped body, reported as zod issues.
+ *
+ * The rules themselves live in {@link ./storyRules}, deliberately outside this
+ * module: zod runs only for config- and package-declared stories, and a rule
+ * whose violation is a CONFIG_ERROR has to reach the distribution's own stories
+ * too — which it does by being checked in `compileStoryModule`, the door every
+ * tier comes through. Stated in two places it would be two rules; delegated, a
+ * third-party author and the distribution read the same sentence.
+ *
+ * What they cover: a query a page cannot wrap (its own prologue is lifted, but
+ * a `FROM` clause and an unreadable projection cannot be), a filter or search
+ * over a variable the query does not project, a filtered query shadowing the
+ * generated variable prefix, and a filter that declares neither `values` nor a
+ * `vocabulary`. None of them could be checked while filters were predicates
+ * over returned rows: a variable that was not there simply matched nothing,
+ * silently, with exit 0.
+ */
+function refineListShape(
+  shape: PackList,
+  path: readonly (string | number)[],
+  ctx: z.RefinementCtx,
+): void {
+  for (const issue of listShapeIssues(shape, path)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: issue.message,
+      path: [...issue.path],
+    });
+  }
+}
+
+/**
+ * The tier-scope rules, stated by the same reader the compiler uses.
+ *
+ * Delegated for the reason every other compilability rule is: a third-party
+ * author must be refused where they declare, and the distribution's own stories
+ * — which never see zod — must be held to the same rule at compile time.
+ */
+function refineTierScope(
+  tierScope: PackTierScope | undefined,
+  shape: PackList,
+  path: readonly (string | number)[],
+  ctx: z.RefinementCtx,
+): void {
+  for (const issue of tierScopeIssues(tierScope, shape, path)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: issue.message,
+      path: [...issue.path],
+    });
+  }
+}
+
 /** Cross-field lookup rules — the source rule (§3, F8). */
 function refineLookup(
   lookup: z.infer<typeof lookupSchema>,
@@ -446,14 +576,51 @@ function refineLookup(
         path: ["lookup"],
       });
     }
+    // The EXPAND's lane, not the lookup's: an expand may opt out of a graphql
+    // lookup's document, and the three rules below are rules about the lane
+    // that will actually resolve it.
+    const expandSource = expand.source ?? source;
     for (const entry of expand.select) {
-      if ("relation" in entry && source !== "graphql") {
+      if ("relation" in entry && expandSource !== "graphql") {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message: `expand "${expand.name}" nests a relation, which requires lookup.source "graphql" (the SPARQL expand sub-SELECT is single-hop).`,
           path: ["lookup"],
         });
       }
+      if (
+        "blankWhenSelf" in entry &&
+        entry.blankWhenSelf &&
+        expandSource !== "sparql"
+      ) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `expand "${expand.name}" field "${entry.name}" sets "blankWhenSelf", which only the SPARQL lane can express — set the expand's "source" to "sparql".`,
+          path: ["lookup"],
+        });
+      }
+    }
+    if (expand.orderBy !== undefined) {
+      if (expandSource !== "sparql") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `expand "${expand.name}" declares "orderBy", which only the SPARQL lane can express — a GraphQL collection's order is the schema's. Set the expand's "source" to "sparql".`,
+          path: ["lookup"],
+        });
+      }
+      // A name that no select entry declares would order by an unbound
+      // variable, which SPARQL permits and which silently orders by nothing —
+      // so it is refused where it is written rather than ignored at runtime.
+      const selected = new Set(expand.select.map((entry) => entry.name));
+      for (const name of expand.orderBy) {
+        if (!selected.has(name)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `expand "${expand.name}" orders by "${name}", which its "select" does not declare.`,
+            path: ["lookup"],
+          });
+        }
+      }
     }
   }
 }

package/src/kernel/packs/sparql/authorQuery.test.ts

@@ -0,0 +1,179 @@
+/**
+ * The author-query reader: the prologue it lifts, the projection it reproduces,
+ * and the shapes it refuses BY NAME.
+ *
+ * The last of those is the point. Every refusal here used to be the same
+ * sentence — "project its variables by name" — whether the reader had found
+ * `SELECT *`, a comment where it wanted a variable, or a `FROM` clause. Two of
+ * those three were wrong, and a wrong reason sends an author to the wrong part
+ * of their own file. So each case below asserts what the message SAYS, not only
+ * that it refused.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readAuthorQuery } from "./authorQuery.js";
+
+/** The parts, for a query the reader can read. */
+function parts(text: string) {
+  const read = readAuthorQuery(text);
+  if (!read.ok) throw new Error(`unreadable: ${read.reason}`);
+  return read.query;
+}
+
+/** The reason, for one it cannot. */
+function reason(text: string): string {
+  const read = readAuthorQuery(text);
+  if (read.ok) throw new Error("expected a refusal");
+  return read.reason;
+}
+
+describe("the projection", () => {
+  it("reads bare variables and aliased expressions, in author order", () => {
+    expect(
+      parts(
+        [
+          "SELECT ?uri ?name ?category",
+          '       (GROUP_CONCAT(DISTINCT ?slug; SEPARATOR=" ") AS ?categories)',
+          "WHERE { ?uri a cs:CodeStandard }",
+        ].join("\n"),
+      ).projection,
+    ).toEqual(["uri", "name", "category", "categories"]);
+  });
+
+  it("reads through DISTINCT and through a nested projection expression", () => {
+    expect(
+      parts(
+        "SELECT DISTINCT ?a (COALESCE(IF(?d = 0, 1, 1 - (0.2 * ?d)), 0) AS ?rank) WHERE { ?a ds:x ?d }",
+      ).projection,
+    ).toEqual(["a", "rank"]);
+  });
+
+  it("reads $-sigil variables, and a projection with no WHERE keyword", () => {
+    expect(parts("SELECT $a $b { $a ds:x $b }").projection).toEqual(["a", "b"]);
+  });
+
+  it("answers undefined for SELECT * — the one projection it cannot enumerate", () => {
+    expect(parts("SELECT * WHERE { ?s ?p ?o }").projection).toBeUndefined();
+  });
+
+  it("is not fooled by a brace or a WHERE inside a string literal", () => {
+    expect(
+      parts(
+        'SELECT ?a (REPLACE(?a, "WHERE {", ")") AS ?b) WHERE { ?a ds:x ?y }',
+      ).projection,
+    ).toEqual(["a", "b"]);
+  });
+
+  it("reads through a comment sitting where a variable was expected", () => {
+    // Previously undefined, which refused the story with a message saying it
+    // must not use `SELECT *` — which it does not.
+    expect(
+      parts("SELECT # the columns\n  ?uri ?name\nWHERE { ?uri ds:name ?name }")
+        .projection,
+    ).toEqual(["uri", "name"]);
+  });
+});
+
+describe("the prologue", () => {
+  it("is empty, and the body is the whole text, when the author declares none", () => {
+    const query = "SELECT ?s WHERE { ?s ?p ?o }";
+    expect(parts(query)).toEqual({
+      prologue: "",
+      projection: ["s"],
+      body: query,
+    });
+  });
+
+  it("is lifted whole, and the body starts at SELECT", () => {
+    const read = parts(
+      [
+        "PREFIX a: <https://example.test/a#>",
+        "PREFIX b: <https://example.test/b#>",
+        "SELECT ?s WHERE { ?s a:p ?o }",
+      ].join("\n"),
+    );
+    expect(read.prologue).toBe(
+      "PREFIX a: <https://example.test/a#>\nPREFIX b: <https://example.test/b#>",
+    );
+    expect(read.body).toBe("SELECT ?s WHERE { ?s a:p ?o }");
+  });
+
+  it("reads a `#` and a `>`-free IRI as an IRI, not as a comment", () => {
+    // `IRIREF` excludes `>` and admits `#`, so the IRI ends at its own `>` and
+    // a `#` inside it does not start a comment.
+    const read = parts(
+      "prefix q: <https://example.test/x#select> SELECT ?s WHERE { ?s q:p ?o }",
+    );
+    expect(read.prologue).toBe("prefix q: <https://example.test/x#select>");
+    expect(read.projection).toEqual(["s"]);
+  });
+
+  it("tolerates lower case, a leading comment, and comments between declarations", () => {
+    const read = parts(
+      [
+        "# select the standards",
+        "base <https://example.test/>",
+        "# and their categories",
+        "Prefix cs: <https://example.test/cs#>",
+        "select ?s where { ?s cs:p ?o }",
+      ].join("\n"),
+    );
+    expect(read.prologue).toBe(
+      [
+        "base <https://example.test/>",
+        "# and their categories",
+        "Prefix cs: <https://example.test/cs#>",
+      ].join("\n"),
+    );
+    expect(read.body).toBe("select ?s where { ?s cs:p ?o }");
+    expect(read.projection).toEqual(["s"]);
+  });
+
+  it("is not confused by a `PREFIX` IRI containing the word select", () => {
+    expect(
+      parts("PREFIX p: <https://example.test/select#> SELECT ?s { ?s p:x ?o }")
+        .projection,
+    ).toEqual(["s"]);
+  });
+
+  it("takes the default prefix (`PREFIX : <…>`) as a declaration", () => {
+    const read = parts(
+      "PREFIX : <https://example.test/> SELECT ?s { ?s :x ?o }",
+    );
+    expect(read.prologue).toBe("PREFIX : <https://example.test/>");
+  });
+});
+
+describe("what it refuses, and what it says it found", () => {
+  it("names a FROM dataset clause", () => {
+    expect(
+      reason("SELECT ?s FROM <https://example.test/g> WHERE { ?s ?p ?o }"),
+    ).toContain("FROM dataset clause");
+  });
+
+  it("names a FROM NAMED clause the same way", () => {
+    expect(
+      reason(
+        "SELECT ?s FROM NAMED <https://example.test/g> WHERE { ?s ?p ?o }",
+      ),
+    ).toContain("FROM dataset clause");
+  });
+
+  it("names a text with no SELECT at all", () => {
+    expect(reason("ASK { ?s ?p ?o }")).toContain("no SPARQL SELECT");
+  });
+
+  it("names a projection that binds no result variable", () => {
+    expect(reason("SELECT (COUNT(?s)) WHERE { ?s ?p ?o }")).toContain(
+      "names no result variable",
+    );
+  });
+
+  it("names a token it does not recognise, and quotes it", () => {
+    expect(reason("SELECT ?a , ?b WHERE { ?a ?p ?b }")).toContain('","');
+  });
+
+  it("names a SELECT clause that projects nothing", () => {
+    expect(reason("SELECT WHERE { ?s ?p ?o }")).toContain("projects nothing");
+  });
+});