@terpjs/contract 0.8.0 → 0.9.0

package/openapi.json

@@ -104,6 +104,14 @@
             "title": "Id",
             "type": "string"
           },
+          "permissions": {
+            "default": [],
+            "items": {
+              "type": "string"
+            },
+            "title": "Permissions",
+            "type": "array"
+          },
           "role_name": {
             "title": "Role Name",
             "type": "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/contract",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Terp frontend contract \u2014 the OpenAPI-generated TypeScript client, design tokens, and the stack-agnostic module/route/nav + auth types.",
   "exports": {

package/src/manifest.ts

@@ -26,6 +26,20 @@ export interface ModuleRoute {
   view: string;
   /** Minimum role required to see the route; omitted = any authenticated user. */
   role?: RoleName;
+  /**
+   * Query-string keys this route reads, e.g. `["status", "page"]`.
+   *
+   * Declared for the same reason params are: the router is realised at runtime, so
+   * nothing checks a search key either — and a list screen's filters live in the query
+   * string, which is why *most* screens were the ones bypassing the typed navigation
+   * seam entirely. `terp routes` emits these into the generated table, so navigating
+   * with an undeclared key (or reading one) is a typecheck error.
+   *
+   * Values are `string | undefined` and nothing more: a query parameter is text, and
+   * every key is absent until someone sets it. Parsing `page` into a number is the
+   * screen's business — declaring the key is what stops it being a typo.
+   */
+  search?: string[];
 }
 
 export interface NavItem {

package/src/routes-codegen.js

@@ -35,9 +35,10 @@ import ts from "typescript";
 const HEADER = [
   "// Generated by `terp routes` from this app's module manifests. Do not edit.",
   "//",
-  "// Maps every route path the manifests declare to that route's params, so",
-  "// useRouteParams / useRouteParam / useTerpNavigate check paths and param names at",
-  "// compile time (ADR 0092). Regenerate after changing a manifest route — `terp verify`",
+  "// Maps every route path the manifests declare to that route's params and its declared",
+  "// query-string keys, so useRouteParams / useRouteParam / useRouteSearch /",
+  "// useTerpNavigate check paths, param names and search keys at compile time",
+  "// (ADR 0092, ADR 0096). Regenerate after changing a manifest route — `terp verify`",
   "// fails on a stale copy. Routes mounted by a packaged area (the admin area) are not",
   "// keyed here: this file is a pure function of this app's own manifests.",
   "",
@@ -57,15 +58,29 @@ export function canonicalPath(routePath) {
   return routePath.replace(/(^|\/)\$([A-Za-z_][A-Za-z0-9_]*)/g, "$1:$2");
 }
 
+/** Find a property assignment by name on an object literal, or undefined. */
+function propertyNamed(element, name) {
+  return element.properties.find(
+    (property) =>
+      ts.isPropertyAssignment(property) &&
+      (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+      property.name.text === name,
+  );
+}
+
 /**
- * Every route path a source file's `defineModuleManifest(...)` calls declare.
+ * Every route a source file's `defineModuleManifest(...)` calls declare.
  *
- * Returns `{ paths, problems }`. A shape that cannot be read statically lands in
- * `problems` (with file:line) rather than being skipped — the caller refuses on any.
+ * Returns `{ routes, problems }`, where a route is `{ path, search }`. A shape that
+ * cannot be read statically lands in `problems` (with file:line) rather than being
+ * skipped — the caller refuses on any. `search` is held to the same standard as `path`:
+ * a computed key list is refused rather than silently dropped, because a missing search
+ * key turns a real navigation into a type error, which is the failure mode that teaches
+ * authors to distrust the check.
  */
-export function extractRoutePaths(sourceText, label) {
+export function extractRoutes(sourceText, label) {
   const source = ts.createSourceFile(label, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-  const paths = [];
+  const routes = [];
   const problems = [];
   let manifests = 0;
 
@@ -90,12 +105,7 @@ export function extractRoutePaths(sourceText, label) {
         );
         continue;
       }
-      const pathProperty = element.properties.find(
-        (property) =>
-          ts.isPropertyAssignment(property) &&
-          (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
-          property.name.text === "path",
-      );
+      const pathProperty = propertyNamed(element, "path");
       if (pathProperty === undefined) {
         problems.push(`${at(element)}: a route declares no \`path\`.`);
         continue;
@@ -108,8 +118,48 @@ export function extractRoutePaths(sourceText, label) {
         );
         continue;
       }
-      paths.push(value.text);
+      const search = readSearchKeys(element);
+      if (search === null) {
+        continue;
+      }
+      routes.push({ path: value.text, search });
+    }
+  };
+
+  /** A route's declared query-string keys, `[]` when it declares none, `null` on refusal. */
+  const readSearchKeys = (element) => {
+    const searchProperty = propertyNamed(element, "search");
+    if (searchProperty === undefined) {
+      return [];
+    }
+    const value = searchProperty.initializer;
+    if (!ts.isArrayLiteralExpression(value)) {
+      problems.push(
+        `${at(value)}: a route \`search\` is not an array literal, so its keys cannot be read ` +
+          'statically. Write them inline (e.g. search: ["status", "page"]).',
+      );
+      return null;
+    }
+    const keys = [];
+    for (const key of value.elements) {
+      if (!ts.isStringLiteral(key)) {
+        problems.push(
+          `${at(key)}: a route \`search\` key is not a plain string literal, so it cannot be ` +
+            'read statically. Write each key inline (e.g. search: ["status", "page"]).',
+        );
+        return null;
+      }
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key.text)) {
+        problems.push(
+          `${at(key)}: search key ${JSON.stringify(key.text)} is not a plain identifier, so it ` +
+            "cannot be emitted as a typed property. Rename it to letters, digits and " +
+            "underscores.",
+        );
+        return null;
+      }
+      keys.push(key.text);
     }
+    return keys;
   };
 
   const visit = (node) => {
@@ -127,16 +177,11 @@ export function extractRoutePaths(sourceText, label) {
             "cannot be read statically.",
         );
       } else {
-        const routes = argument.properties.find(
-          (property) =>
-            ts.isPropertyAssignment(property) &&
-            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
-            property.name.text === "routes",
-        );
-        if (routes === undefined) {
+        const declared = propertyNamed(argument, "routes");
+        if (declared === undefined) {
           problems.push(`${at(argument)}: the manifest declares no \`routes\`.`);
         } else {
-          readRoutesArray(routes.initializer);
+          readRoutesArray(declared.initializer);
         }
       }
     }
@@ -150,7 +195,7 @@ export function extractRoutePaths(sourceText, label) {
         "a module whose manifest is built elsewhere cannot be extracted.",
     );
   }
-  return { paths, problems };
+  return { routes, problems };
 }
 
 /** The module files to scan: `<modulesDir>/<name>/module.tsx` (or `.ts`), sorted. */
@@ -174,9 +219,18 @@ export function moduleFiles(modulesDir) {
   return found;
 }
 
-/** Render the declaration file for *paths* — deterministic: deduped, sorted, LF. */
-export function renderRouteTable(paths) {
-  const unique = [...new Set(paths.map(canonicalPath))].sort();
+/** Render the declaration file for *routes* — deterministic: deduped, sorted, LF. */
+export function renderRouteTable(routes) {
+  // Two manifests may mount the same path; their declared search keys are unioned, which
+  // is the honest reading of "this route reads these keys".
+  const searchByPath = new Map();
+  for (const route of routes) {
+    const key = canonicalPath(route.path);
+    const merged = searchByPath.get(key) ?? [];
+    searchByPath.set(key, [...merged, ...(route.search ?? [])]);
+  }
+  const unique = [...searchByPath.keys()].sort();
+
   const lines = [...HEADER];
   for (const routePath of unique) {
     const params = paramNamesOf(routePath);
@@ -186,7 +240,21 @@ export function renderRouteTable(paths) {
         : `{ ${params.map((name) => `${name}: string`).join("; ")} }`;
     lines.push(`    ${JSON.stringify(routePath)}: ${shape};`);
   }
-  lines.push("  }", "}", "");
+  lines.push("  }");
+
+  // Only emitted when some route declares keys: an app that declares none gets exactly
+  // the file it had before, and no empty interface for its own linter to complain about.
+  const withSearch = unique.filter((routePath) => searchByPath.get(routePath).length > 0);
+  if (withSearch.length > 0) {
+    lines.push("  interface TerpRouteSearchTable {");
+    for (const routePath of withSearch) {
+      const keys = [...new Set(searchByPath.get(routePath))].sort();
+      const shape = keys.map((name) => `${name}?: string`).join("; ");
+      lines.push(`    ${JSON.stringify(routePath)}: { ${shape} };`);
+    }
+    lines.push("  }");
+  }
+  lines.push("}", "");
   return lines.join("\n");
 }
 
@@ -202,11 +270,11 @@ export function generateRouteTable(modulesDir) {
         "src/modules/<name>/module.tsx; pass --modules-dir if this app keeps them elsewhere.",
     );
   }
-  const paths = [];
+  const routes = [];
   const problems = [];
   for (const file of files) {
-    const result = extractRoutePaths(fs.readFileSync(file, "utf8"), path.relative(process.cwd(), file).split(path.sep).join("/"));
-    paths.push(...result.paths);
+    const result = extractRoutes(fs.readFileSync(file, "utf8"), path.relative(process.cwd(), file).split(path.sep).join("/"));
+    routes.push(...result.routes);
     problems.push(...result.problems);
   }
   if (problems.length > 0) {
@@ -216,7 +284,7 @@ export function generateRouteTable(modulesDir) {
         problems.map((problem) => `  - ${problem}`).join("\n"),
     );
   }
-  return renderRouteTable(paths);
+  return renderRouteTable(routes);
 }
 
 /** Parse `--flag value` / `--flag` argv into a plain object. */

package/src/routes-codegen.test.js

@@ -8,7 +8,7 @@ import { afterEach, describe, expect, it } from "vitest";
 
 import {
   canonicalPath,
-  extractRoutePaths,
+  extractRoutes,
   generateRouteTable,
   moduleFiles,
   paramNamesOf,
@@ -66,17 +66,17 @@ describe("param extraction from a path", () => {
 
 describe("extraction from a module manifest", () => {
   it("reads every route path a manifest declares", () => {
-    const { paths, problems } = extractRoutePaths(
+    const { routes, problems } = extractRoutes(
       manifest('{ path: "/records", view: "List" }, { path: "/records/:recordId", view: "Detail" }'),
       "module.tsx",
     );
     expect(problems).toEqual([]);
-    expect(paths).toEqual(["/records", "/records/:recordId"]);
+    expect(routes.map((route) => route.path)).toEqual(["/records", "/records/:recordId"]);
   });
 
   it("reads a manifest declared as a property value, not only `export const manifest`", () => {
     // The packaged admin area's shape: defineModuleManifest(...) inside an object literal.
-    const { paths, problems } = extractRoutePaths(
+    const { routes, problems } = extractRoutes(
       [
         'import { defineModuleManifest } from "@terpjs/contract";',
         "export const adminModule = {",
@@ -86,25 +86,25 @@ describe("extraction from a module manifest", () => {
       "module.tsx",
     );
     expect(problems).toEqual([]);
-    expect(paths).toEqual(["/admin"]);
+    expect(routes.map((route) => route.path)).toEqual(["/admin"]);
   });
 
   it("refuses a path that is not a plain string literal, naming file and line", () => {
-    const { paths, problems } = extractRoutePaths(
+    const { routes, problems } = extractRoutes(
       manifest("{ path: `/records/${base}`, view: \"List\" }"),
       "src/modules/records/module.tsx",
     );
-    expect(paths).toEqual([]);
+    expect(routes.map((route) => route.path)).toEqual([]);
     expect(problems).toHaveLength(1);
     expect(problems[0]).toContain("src/modules/records/module.tsx:4");
     expect(problems[0]).toContain("not a plain string literal");
   });
 
   it("refuses a spread route and a non-literal routes array", () => {
-    const spread = extractRoutePaths(manifest("...shared"), "module.tsx");
+    const spread = extractRoutes(manifest("...shared"), "module.tsx");
     expect(spread.problems[0]).toContain("not an object literal");
 
-    const dynamic = extractRoutePaths(
+    const dynamic = extractRoutes(
       [
         'import { defineModuleManifest } from "@terpjs/contract";',
         "export const manifest = defineModuleManifest({ name: \"x\", routes: buildRoutes() });",
@@ -115,20 +115,20 @@ describe("extraction from a module manifest", () => {
   });
 
   it("refuses a module slot with no manifest call at all", () => {
-    const { problems } = extractRoutePaths("export const views = {};", "module.tsx");
+    const { problems } = extractRoutes("export const views = {};", "module.tsx");
     expect(problems[0]).toContain("no defineModuleManifest");
   });
 
   it("refuses a route with no path", () => {
-    const { problems } = extractRoutePaths(manifest('{ view: "List" }'), "module.tsx");
+    const { problems } = extractRoutes(manifest('{ view: "List" }'), "module.tsx");
     expect(problems[0]).toContain("declares no `path`");
   });
 });
 
 describe("rendering the declaration file", () => {
   it("is deterministic: deduped, sorted, LF-only, one trailing newline", () => {
-    const first = renderRouteTable(["/b", "/a", "/b"]);
-    const second = renderRouteTable(["/b", "/b", "/a"]);
+    const first = renderRouteTable([{ path: "/b", search: [] }, { path: "/a", search: [] }, { path: "/b", search: [] }]);
+    const second = renderRouteTable([{ path: "/b", search: [] }, { path: "/b", search: [] }, { path: "/a", search: [] }]);
     expect(first).toBe(second);
     expect(first).not.toContain("\r");
     expect(first.endsWith("}\n")).toBe(true);
@@ -136,14 +136,14 @@ describe("rendering the declaration file", () => {
   });
 
   it("types a parameterised route's params and leaves a paramless route empty", () => {
-    const rendered = renderRouteTable(["/records/:recordId", "/records", "/s/:a/i/:b"]);
+    const rendered = renderRouteTable([{ path: "/records/:recordId", search: [] }, { path: "/records", search: [] }, { path: "/s/:a/i/:b", search: [] }]);
     expect(rendered).toContain('"/records": Record<never, never>;');
     expect(rendered).toContain('"/records/:recordId": { recordId: string };');
     expect(rendered).toContain('"/s/:a/i/:b": { a: string; b: string };');
   });
 
   it("augments the react-core table so the app's own types pick it up", () => {
-    const rendered = renderRouteTable(["/"]);
+    const rendered = renderRouteTable([{ path: "/", search: [] }]);
     expect(rendered).toContain('declare module "@terpjs/react-core"');
     expect(rendered).toContain("interface TerpRouteTable");
     // A module augmentation only applies from a file that IS a module.
@@ -151,6 +151,83 @@ describe("rendering the declaration file", () => {
   });
 });
 
+describe("declared query-string keys", () => {
+  it("reads a route's search keys, and defaults to none", () => {
+    const { routes, problems } = extractRoutes(
+      manifest(
+        '{ path: "/records", view: "List", search: ["status", "page"] }, ' +
+          '{ path: "/records/:recordId", view: "Detail" }',
+      ),
+      "module.tsx",
+    );
+    expect(problems).toEqual([]);
+    expect(routes).toEqual([
+      { path: "/records", search: ["status", "page"] },
+      { path: "/records/:recordId", search: [] },
+    ]);
+  });
+
+  it("refuses keys that cannot be read statically, naming file and line", () => {
+    // Held to the same standard as `path`: a key list assembled at runtime would emit a
+    // table missing a key, which turns a real navigation into a type error.
+    const spread = extractRoutes(
+      manifest('{ path: "/r", view: "L", search: [...FILTERS] }'),
+      "module.tsx",
+    );
+    expect(spread.problems.join("\n")).toMatch(/search` key is not a plain string literal/);
+
+    const dynamic = extractRoutes(
+      manifest('{ path: "/r", view: "L", search: FILTERS }'),
+      "module.tsx",
+    );
+    expect(dynamic.problems.join("\n")).toMatch(/search` is not an array literal/);
+    expect(dynamic.problems[0]).toMatch(/^module\.tsx:4:/);
+  });
+
+  it("refuses a key that is not a plain identifier, because it cannot be a typed property", () => {
+    const { problems } = extractRoutes(
+      manifest('{ path: "/r", view: "L", search: ["not-an-identifier"] }'),
+      "module.tsx",
+    );
+    expect(problems.join("\n")).toMatch(/is not a plain identifier/);
+  });
+
+  it("emits a second table keyed only for routes that declare keys", () => {
+    const rendered = renderRouteTable([
+      { path: "/records", search: ["status"] },
+      { path: "/records/:recordId", search: [] },
+    ]);
+    expect(rendered).toContain('    "/records": Record<never, never>;');
+    expect(rendered).toContain("  interface TerpRouteSearchTable {");
+    expect(rendered).toContain('    "/records": { status?: string };');
+    // The route that declares no keys is absent from the SEARCH table (it is of course
+    // present in the params table above), so passing `search` to it stays a typecheck
+    // error rather than accepting anything.
+    const searchTable = rendered.slice(rendered.indexOf("interface TerpRouteSearchTable"));
+    expect(searchTable).not.toContain("/records/:recordId");
+  });
+
+  it("omits the search table entirely when no route declares a key", () => {
+    // An app that declares none gets exactly the file it had before route search existed
+    // — and no empty interface for its own linter to complain about.
+    const rendered = renderRouteTable([{ path: "/records", search: [] }]);
+    expect(rendered).not.toContain("TerpRouteSearchTable");
+  });
+
+  it("unions the keys when two manifests mount one path", () => {
+    const rendered = renderRouteTable([
+      { path: "/shared", search: ["b"] },
+      { path: "/shared", search: ["a", "b"] },
+    ]);
+    expect(rendered).toContain('    "/shared": { a?: string; b?: string };');
+  });
+
+  it("keys the search table by the canonical spelling, like the params table", () => {
+    const rendered = renderRouteTable([{ path: "/admin/users/$userId", search: ["q"] }]);
+    expect(rendered).toContain('    "/admin/users/:userId": { q?: string };');
+  });
+});
+
 describe("generating across an app's module slots", () => {
   it("merges every slot and dedupes a path two modules claim", () => {
     const root = appWithModules({

package/src/schema.d.ts

@@ -382,6 +382,11 @@ export interface components {
              * Format: uuid
              */
             id: string;
+            /**
+             * Permissions
+             * @default []
+             */
+            permissions: string[];
             /** Role Name */
             role_name: string;
             /** Role Rank */

package/src/tokens.manifest.json

@@ -1193,6 +1193,20 @@
       "bg": "--color-neutral-50",
       "layer": "primitive"
     },
+    {
+      "id": "danger-on-card",
+      "label": "danger text on a card",
+      "fg": "--color-status-danger",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "danger-on-canvas",
+      "label": "danger text on the canvas",
+      "fg": "--color-status-danger",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
+    },
     {
       "id": "primary-button-label",
       "label": "primary button label",

package/token-pairs.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Token pairings the framework renders, as data, in two sections held to two different bars. `textPairs` are foreground/background pairs painted as TEXT and held to WCAG 2.1 AA for normal text; `nonTextPairs` are the visual boundaries and state indicators SC 1.4.11 asks 3:1 of — a focus indicator, the border that says which control is active, the outline of a control against its surface. Two consumers read both: tokens.contrast.test.js measures each pairing at its own bar, and the generated token manifest publishes them so a theme editor or an agent can tell which tokens must stay legible against which. A pair of token names appears in one section only: the text bar is the stricter of the two, so restating a text pairing under a non-text name would add a case that cannot fail unless the stricter one already has, and would overstate how much the ratchets cover. Purely decorative marks stay absent from both sections — WCAG sets no ratio for a divider or for an aria-hidden ornament, and asserting one would teach the next reader to ignore this file. Names are CSS custom properties because that is the vocabulary a theme author writes and a manifest consumer reads.",
+  "$comment": "Token pairings the framework renders, as data, in two sections held to two different bars. `textPairs` are foreground/background pairs painted as TEXT and held to WCAG 2.1 AA for normal text; `nonTextPairs` are the visual boundaries and state indicators SC 1.4.11 asks 3:1 of — a focus indicator, the border that says which control is active, the outline of a control against its surface. Two consumers read both: tokens.contrast.test.js measures each pairing at its own bar, and the generated token manifest publishes them so a theme editor or an agent can tell which tokens must stay legible against which. A pair of token names appears in one section only: the text bar is the stricter of the two, so restating a text pairing under a non-text name would add a case that cannot fail unless the stricter one already has, and would overstate how much the ratchets cover. Purely decorative marks stay absent from both sections — WCAG sets no ratio for a divider or for an aria-hidden ornament, and asserting one would teach the next reader to ignore this file. Names are CSS custom properties because that is the vocabulary a theme author writes and a manifest consumer reads. A pairing earns its place here even when no specimen paints it, and two of them are exactly that: axe measures the pixels a lane renders, so a surface that only appears on a state no specimen can reach - a failed sign-in, a failed create - has no lane coverage at all, and the declared pairing is the only gate it will ever have.",
   "textPairs": [
     {
       "id": "body-on-card",
@@ -29,6 +29,20 @@
       "bg": "--color-neutral-50",
       "layer": "primitive"
     },
+    {
+      "id": "danger-on-card",
+      "label": "danger text on a card",
+      "fg": "--color-status-danger",
+      "bg": "--color-neutral-0",
+      "layer": "primitive"
+    },
+    {
+      "id": "danger-on-canvas",
+      "label": "danger text on the canvas",
+      "fg": "--color-status-danger",
+      "bg": "--color-neutral-50",
+      "layer": "primitive"
+    },
     {
       "id": "primary-button-label",
       "label": "primary button label",