lumen-framework 3.1.1 → 4.0.0

package/dist/testing.js

@@ -0,0 +1,280 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing.ts
+var testing_exports = {};
+__export(testing_exports, {
+  auditVisibility: () => auditVisibility,
+  startApp: () => startApp
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/packages/testing/utils/identifiers-in.ts
+var isIdentifier = (value) => typeof value === "object" && value !== null && "type" in value && "id" in value;
+function identifiersIn(document) {
+  const found = [];
+  const add = (value) => {
+    if (isIdentifier(value)) {
+      found.push({ type: value.type, id: String(value.id) });
+    }
+  };
+  const addLinkage = (linkage) => {
+    (Array.isArray(linkage) ? linkage : [linkage]).forEach(add);
+  };
+  const addResource = (resource) => {
+    add(resource);
+    if (isIdentifier(resource)) {
+      Object.values(resource.relationships ?? {}).forEach(
+        (relationship) => addLinkage(relationship?.data)
+      );
+    }
+  };
+  if (typeof document !== "object" || document === null) {
+    return found;
+  }
+  const { data, included } = document;
+  (Array.isArray(data) ? data : [data]).forEach(addResource);
+  (included ?? []).forEach(addResource);
+  return found;
+}
+
+// src/packages/testing/audit-visibility.ts
+var READS = /* @__PURE__ */ new Set(["index", "show", "showRelationship", "showRelated"]);
+var DENIED = /* @__PURE__ */ new Set([401, 403, 404]);
+var MAX_PAGES = 1e3;
+function originOf(app) {
+  const address = app.server.instance.address();
+  if (!address) {
+    throw new Error(
+      "auditVisibility: the application is not listening. Start it (`startApp()`), or pass the `origin` of the server to audit."
+    );
+  }
+  return `http://localhost:${address.port}`;
+}
+function allows(visible, id) {
+  if (visible === true) {
+    return true;
+  }
+  if (typeof visible === "function") {
+    return visible(id);
+  }
+  return Boolean(visible?.some((allowed) => String(allowed) === id));
+}
+function includesOf(route) {
+  const include = route.params.get("include");
+  const paths = include ? Array.from(include) : [];
+  const longest = paths.filter(
+    (path) => !paths.some((other) => other.startsWith(`${path}.`))
+  );
+  return longest.length ? [void 0, longest.join(",")] : [void 0];
+}
+async function auditVisibility(app, {
+  namespace = "",
+  visible,
+  headers = {},
+  ids = {},
+  query: required = {},
+  origin = originOf(app),
+  onDocument
+}) {
+  const audit = { requests: [], violations: [], seen: {} };
+  const seen = /* @__PURE__ */ new Map();
+  const routes = Array.from(app.router.values()).filter(
+    (route) => route.method === "GET" && READS.has(route.action) && route.controller.namespace === namespace
+  );
+  if (!routes.length) {
+    throw new Error(
+      `auditVisibility: namespace '/${namespace}' serves no index, show, relationship or related routes.`
+    );
+  }
+  const relative = (link) => {
+    const { pathname, search } = new URL(link, origin);
+    return pathname + search;
+  };
+  const idsCache = /* @__PURE__ */ new Map();
+  const idsOf = async (route) => {
+    const { model } = route.controller;
+    const type = model.resourceName;
+    let list = idsCache.get(type);
+    if (!list) {
+      const given = ids[type];
+      list = given ? given.map(String) : (await model.select(model.primaryKey)).map((record) => String(record.getPrimaryKey()));
+      idsCache.set(type, list);
+    }
+    return list;
+  };
+  const check = (url, status, found) => {
+    found.forEach(({ type, id }) => {
+      if (!seen.has(type)) {
+        seen.set(type, /* @__PURE__ */ new Set());
+      }
+      seen.get(type)?.add(id);
+      if (!allows(visible[type], id)) {
+        audit.violations.push({ url, status, type, id });
+      }
+    });
+  };
+  const read = async (first, route) => {
+    let url = first;
+    const hiddenOwner = route.action.startsWith("showRel") && route.id !== void 0 && !allows(visible[route.type], route.id);
+    for (let page = 0; url && page < MAX_PAGES; page += 1) {
+      audit.requests.push(url);
+      const res = await fetch(origin + url, {
+        headers: { Accept: "application/vnd.api+json", ...headers }
+      });
+      if (!res.ok && !DENIED.has(res.status)) {
+        audit.violations.push({ url, status: res.status });
+        await res.body?.cancel();
+        return;
+      }
+      if (res.ok && hiddenOwner && page === 0) {
+        audit.violations.push({
+          url,
+          status: res.status,
+          type: route.type,
+          id: route.id,
+          message: `answered for ${route.type} ${route.id}, which the request may not see`
+        });
+      }
+      if (!res.ok || !res.headers.get("content-type")?.includes("json")) {
+        await res.body?.cancel();
+        return;
+      }
+      const document = await res.json();
+      check(url, res.status, identifiersIn(document));
+      if (onDocument && document) {
+        const found = await onDocument({
+          url,
+          status: res.status,
+          route,
+          document
+        });
+        const messages = typeof found === "string" ? [found] : Array.from(found ?? []);
+        const at = { url, status: res.status };
+        messages.forEach((message) => {
+          audit.violations.push({ ...at, message });
+        });
+      }
+      const next = document?.links?.next;
+      url = typeof next === "string" ? relative(next) : void 0;
+    }
+  };
+  for (const route of routes) {
+    const paged = route.params.get("page") ? (route.related ?? route.controller).maxPerPage : void 0;
+    const served = route.type === "relationship" ? void 0 : (route.related ?? route.controller).model.resourceName;
+    const query = (include) => {
+      const params = new URLSearchParams(served ? required[served] : {});
+      if (include) {
+        params.set("include", include);
+      }
+      if (paged) {
+        params.set("page[size]", String(paged));
+      }
+      const search = params.toString();
+      return search ? `?${search}` : "";
+    };
+    const about = {
+      action: route.action,
+      type: route.controller.model.resourceName,
+      ...route.relationship ? { relationship: route.relationship } : {}
+    };
+    const targets = route.dynamicSegments.length ? (await idsOf(route)).map((id) => [
+      route.path.replace(":id", encodeURIComponent(id)),
+      { ...about, id }
+    ]) : [[route.path, about]];
+    for (const [path, target] of targets) {
+      for (const include of includesOf(route)) {
+        await read(path + query(include), target);
+      }
+    }
+  }
+  seen.forEach((list, type) => {
+    audit.seen[type] = Array.from(list);
+  });
+  return audit;
+}
+
+// src/packages/testing/start-app.ts
+var import_events = require("events");
+var import_module = require("module");
+var import_path = require("path");
+var started = /* @__PURE__ */ new Set();
+var failed = /* @__PURE__ */ new Map();
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+async function startApp(path, { env, port = 0 } = {}) {
+  const root = (0, import_path.resolve)(path);
+  const bundlePath = (0, import_path.join)(root, "dist", "bundle.js");
+  if (started.has(bundlePath)) {
+    throw new Error(
+      `startApp: ${root} was already started in this process. Its models are set up once per process: start it once and share it.`
+    );
+  }
+  const previous = process.env.NODE_ENV;
+  const restoreEnv = () => {
+    if (previous === void 0) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = previous;
+    }
+  };
+  process.env.NODE_ENV = env ?? previous ?? "test";
+  started.add(bundlePath);
+  let app;
+  try {
+    const {
+      Application: App,
+      config,
+      database
+    } = (0, import_module.createRequire)(bundlePath)(bundlePath);
+    app = await new App({ ...config, database, path: root, port });
+    if (!app.server.instance.listening) {
+      await (0, import_events.once)(app.server.instance, "listening");
+    }
+  } catch (error) {
+    started.delete(bundlePath);
+    restoreEnv();
+    const earlier = failed.get(bundlePath);
+    if (failed.has(bundlePath)) {
+      throw new Error(
+        `startApp: booting ${root} failed: ${messageOf(error)}. An earlier attempt in this process failed first, with: ${messageOf(earlier)}. A failed boot can leave the app half set up: fix that one first.`,
+        { cause: error }
+      );
+    }
+    failed.set(bundlePath, error);
+    throw error;
+  }
+  const { port: listening } = app.server.instance.address();
+  return {
+    app,
+    origin: `http://localhost:${listening}`,
+    close: async () => {
+      try {
+        await app.close();
+      } finally {
+        restoreEnv();
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  auditVisibility,
+  startApp
+});
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/testing.ts", "../src/packages/testing/utils/identifiers-in.ts", "../src/packages/testing/audit-visibility.ts", "../src/packages/testing/start-app.ts"],
+  "sourcesContent": ["/**\n * Helpers for an app's tests, imported from `lumen-framework/testing`. They\n * are kept out of the main entry, so they never reach an app's runtime\n * bundle.\n *\n * @module lumen-framework/testing\n */\nexport { auditVisibility, startApp } from './packages/testing';\nexport type {\n  AuditedDocument,\n  AuditedRoute,\n  AuditVisibilityOptions,\n  DocumentCheckResult,\n  StartAppOptions,\n  StartedApp,\n  VisibilityAudit,\n  VisibilityViolation,\n  VisibleRecords\n} from './packages/testing';\n", "/** A resource's `type` and `id`. */\nexport type Identifier = { type: string; id: string };\n\ntype Linkage = Identifier | Array<Identifier> | null | undefined;\n\ntype Resource = Identifier & {\n  relationships?: Record<string, { data?: Linkage }>;\n};\n\nconst isIdentifier = (value: unknown): value is Identifier =>\n  typeof value === 'object' &&\n  value !== null &&\n  'type' in value &&\n  'id' in value;\n\n/**\n * Every resource a JSON:API document names: its primary data, its `included`\n * resources, and the linkage of each one's relationships. A relationship\n * endpoint's primary data is linkage itself, so it is covered the same way.\n * Ids are strings, as JSON:API sends them.\n *\n * @internal\n */\nexport default function identifiersIn(document: unknown): Array<Identifier> {\n  const found: Array<Identifier> = [];\n\n  const add = (value: unknown) => {\n    if (isIdentifier(value)) {\n      found.push({ type: value.type, id: String(value.id) });\n    }\n  };\n\n  const addLinkage = (linkage: Linkage) => {\n    (Array.isArray(linkage) ? linkage : [linkage]).forEach(add);\n  };\n\n  const addResource = (resource: unknown) => {\n    add(resource);\n\n    if (isIdentifier(resource)) {\n      Object.values((resource as Resource).relationships ?? {}).forEach(\n        relationship => addLinkage(relationship?.data)\n      );\n    }\n  };\n\n  if (typeof document !== 'object' || document === null) {\n    return found;\n  }\n\n  const { data, included } = document as {\n    data?: unknown;\n    included?: Array<unknown>;\n  };\n\n  (Array.isArray(data) ? data : [data]).forEach(addResource);\n  (included ?? []).forEach(addResource);\n\n  return found;\n}\n", "import type { AddressInfo } from 'net';\n\nimport type Application from '../application';\nimport type { Model } from '../database';\nimport type Route from '../router/route';\n\nimport identifiersIn from './utils/identifiers-in';\nimport type { Identifier } from './utils/identifiers-in';\n\n/**\n * Which records of one type a request may see, for {@link auditVisibility}:\n * every one (`true`), the ids listed, or the ids a function accepts.\n */\nexport type VisibleRecords =\n  true | ReadonlyArray<string | number> | ((id: string) => boolean);\n\n/** The options of {@link auditVisibility}. */\nexport type AuditVisibilityOptions = {\n  /**\n   * The namespace to audit: `''` (the default) for the root, `'admin'` for\n   * `/admin`. Nested namespaces are audited on their own.\n   */\n  namespace?: string;\n\n  /**\n   * What the request may see, keyed by type. Written by hand, independently\n   * of the app's visibility rules: it is what they are checked against. A\n   * type left out may not appear at all.\n   */\n  visible: Record<string, VisibleRecords>;\n\n  /**\n   * Headers sent with every request, such as the `Authorization` of the user\n   * the audit is for.\n   */\n  headers?: Record<string, string>;\n\n  /**\n   * The ids to request each type's routes with (`GET /posts/:id`,\n   * `/posts/:id/comments`, \u2026), keyed by type: visible and hidden ones\n   * alike. A type left out is requested with every id in the database, so\n   * keep the database small or list the ids.\n   */\n  ids?: Record<string, ReadonlyArray<string | number>>;\n\n  /**\n   * Query parameters a read requires, keyed by the type it serves: they are\n   * sent with that type's list, its records by id, and every related\n   * endpoint that serves it (`/posts/:id/comments` serves `comments`, and\n   * takes the parameters of the comments' controller). Relationship\n   * endpoints take none.\n   *\n   * ```javascript\n   * query: { comments: { fromDate: '2026-01-01' } }\n   * ```\n   */\n  query?: Record<string, Record<string, string>>;\n\n  /**\n   * Where the application is served, when not by `app` itself: a server\n   * started as a separate process (`lumen serve`), such as\n   * `'http://localhost:4000'`. `app` still provides the routes, the\n   * include paths and the ids, so it must be booted in the test, but need\n   * not listen.\n   */\n  origin?: string;\n\n  /**\n   * Called with each document a read answers with, for checks beyond which\n   * records appear, such as the fields a request may see of each. Return a\n   * message, or several, for each problem found: each is reported as a\n   * violation of that request. May be async.\n   *\n   * ```javascript\n   * onDocument({ document }) {\n   *   return document.included\n   *     ?.filter(({ type, attributes }) => type === 'users' && attributes.email)\n   *     .map(({ id }) => `users ${id} shows its email`);\n   * }\n   * ```\n   */\n  onDocument?: (\n    response: AuditedDocument\n  ) => DocumentCheckResult | Promise<DocumentCheckResult>;\n};\n\n/**\n * The read a request was made to, as the route defines it: so a check need\n * not parse the URL to know which record it is about.\n */\nexport type AuditedRoute = {\n  /** The action, as hooks see it. */\n  action: 'index' | 'show' | 'showRelationship' | 'showRelated';\n  /**\n   * The route's resource type: for a relationship or related endpoint, the\n   * owner's (`posts` for `/posts/3/comments`).\n   */\n  type: string;\n  /**\n   * The id in the URL: the record of a `show`, the owner of a relationship\n   * or related endpoint. None for a list.\n   */\n  id?: string;\n  /** The relationship of a relationship or related endpoint (`comments`). */\n  relationship?: string;\n};\n\n/** A document a read answered with, for `onDocument`. */\nexport type AuditedDocument = {\n  /** The request, as a path and query string. */\n  url: string;\n  /** Its status. */\n  status: number;\n  /** The read the request was made to. */\n  route: AuditedRoute;\n  /** The parsed JSON:API document. */\n  document: Record<string, unknown>;\n};\n\n/**\n * What `onDocument` returns: a message for each problem found, or nothing\n * when there is none.\n */\nexport type DocumentCheckResult =\n  string | ReadonlyArray<string> | null | undefined | void;\n\n/**\n * A record a response contained that the audit's `visible` does not allow; a\n * relationship or related endpoint that answered for an owner `visible` does\n * not allow; a request that failed with an error other than `401`, `403` or\n * `404`, so that what it serves could not be checked; or a problem\n * `onDocument` found.\n */\nexport type VisibilityViolation = {\n  /** The request, as a path and query string. */\n  url: string;\n  /** Its status. */\n  status: number;\n  /**\n   * The record's type, if the violation is a record: one the response named,\n   * or the hidden owner an endpoint answered for.\n   */\n  type?: string;\n  /** The record's id, if the violation is a record. */\n  id?: string;\n  /**\n   * What is wrong, for a hidden owner an endpoint answered for and for what\n   * `onDocument` found.\n   */\n  message?: string;\n};\n\n/** What {@link auditVisibility} found. */\nexport type VisibilityAudit = {\n  /** Every request made, as a path and query string. */\n  requests: Array<string>;\n  /** What should not have been in a response, in request order. */\n  violations: Array<VisibilityViolation>;\n  /**\n   * Every record the responses named, keyed by type: as primary data,\n   * included or as linkage, allowed or not, each id once. Compare it with\n   * what the request should see to check that the audit reached it all.\n   */\n  seen: Record<string, Array<string>>;\n};\n\n// The built-in reads; custom routes take parameters the audit cannot know.\nconst READS = new Set(['index', 'show', 'showRelationship', 'showRelated']);\n\n// Statuses that reveal nothing: the request may not read, or there is nothing\n// it may see. Any other error means the read went unchecked.\nconst DENIED = new Set([401, 403, 404]);\n\n// Bounds the `links.next` chain of a single list, should one never end.\nconst MAX_PAGES = 1000;\n\n/** Where `app` itself is listening, if it is. */\nfunction originOf(app: Application): string {\n  const address = app.server.instance.address() as AddressInfo | null;\n\n  if (!address) {\n    throw new Error(\n      'auditVisibility: the application is not listening. Start it ' +\n        '(`startApp()`), or pass the `origin` of the server to audit.'\n    );\n  }\n\n  return `http://localhost:${address.port}`;\n}\n\nfunction allows(visible: VisibleRecords | undefined, id: string): boolean {\n  if (visible === true) {\n    return true;\n  }\n\n  if (typeof visible === 'function') {\n    return visible(id);\n  }\n\n  return Boolean(visible?.some(allowed => String(allowed) === id));\n}\n\n/**\n * The `include` values to request a route with: none, and every path it\n * accepts at once. A compound document holds what each path reaches, so one\n * request covers them all; a path that leads on to a longer one\n * (`comments` to `comments.user`) adds nothing and is left out. A\n * relationship endpoint (linkage only) accepts none.\n */\nfunction includesOf(route: Route): Array<string | undefined> {\n  const include = route.params.get('include') as Set<string> | undefined;\n  const paths = include ? Array.from(include) : [];\n  const longest = paths.filter(\n    path => !paths.some(other => other.startsWith(`${path}.`))\n  );\n\n  return longest.length ? [undefined, longest.join(',')] : [undefined];\n}\n\n/**\n * Request every read a namespace serves \u2014 each list, each record by id, each\n * relationship and related endpoint, without `include` and with every path\n * it accepts, following every page \u2014 and report each record in a response that\n * `visible` does not allow: in `data`, in `included`, or in any\n * relationship's linkage. A relationship or related endpoint that answers\n * for an owner `visible` does not allow is reported too, whatever it\n * answers with: that it answers reveals the owner. A `401`, `403` or `404`\n * (for a hidden record) reveals nothing and passes; any other error is\n * reported, since the read it answers went unchecked.\n *\n * Visibility rules apply to every one of these paths, but scoping in an\n * `index` or `show` override, or in a hook keyed on the action, does not.\n * This checks the result rather than the mechanism, against a list written\n * by hand:\n *\n * ```javascript\n * import { auditVisibility } from 'lumen-framework/testing';\n *\n * it('shows a member only public posts and their comments', async () => {\n *   const { violations } = await auditVisibility(app, {\n *     namespace: 'members',\n *     headers: { Authorization: `Bearer ${memberToken}` },\n *     visible: {\n *       posts: [publicPost.id],\n *       comments: [commentOnPublicPost.id],\n *       users: true\n *     }\n *   });\n *\n *   expect(violations).toEqual([]);\n * });\n * ```\n *\n * Requests are made one at a time, to `app` itself (which must then be\n * listening, as {@link startApp} leaves it) or to `origin`. Custom routes are\n * not requested. Each route is requested once per\n * id (and per page), so run it against a small fixture database, or narrow\n * the ids with `ids`.\n *\n * @param app - The application, listening.\n * @param options - What to audit, and what the request may see.\n * @returns Every request made, every violation found, and every record\n * seen.\n * @throws When the namespace serves no reads, so a mistyped namespace cannot\n * pass by checking nothing.\n */\nexport default async function auditVisibility(\n  app: Application,\n  {\n    namespace = '',\n    visible,\n    headers = {},\n    ids = {},\n    query: required = {},\n    origin = originOf(app),\n    onDocument\n  }: AuditVisibilityOptions\n): Promise<VisibilityAudit> {\n  const audit: VisibilityAudit = { requests: [], violations: [], seen: {} };\n  const seen = new Map<string, Set<string>>();\n\n  const routes = Array.from(app.router.values()).filter(\n    route =>\n      route.method === 'GET' &&\n      READS.has(route.action) &&\n      route.controller.namespace === namespace\n  );\n\n  if (!routes.length) {\n    throw new Error(\n      `auditVisibility: namespace '/${namespace}' serves no index, show, ` +\n        'relationship or related routes.'\n    );\n  }\n\n  // A link as a path and query string, which the audit reports.\n  const relative = (link: string) => {\n    const { pathname, search } = new URL(link, origin);\n\n    return pathname + search;\n  };\n\n  const idsCache = new Map<string, Array<string>>();\n\n  const idsOf = async (route: Route): Promise<Array<string>> => {\n    const { model } = route.controller;\n    const type = model.resourceName;\n    let list = idsCache.get(type);\n\n    if (!list) {\n      const given = ids[type];\n\n      list = given\n        ? given.map(String)\n        : (\n            (await model.select(model.primaryKey)) as unknown as Array<Model>\n          ).map(record => String(record.getPrimaryKey()));\n\n      idsCache.set(type, list);\n    }\n\n    return list;\n  };\n\n  const check = (url: string, status: number, found: Array<Identifier>) => {\n    found.forEach(({ type, id }) => {\n      if (!seen.has(type)) {\n        seen.set(type, new Set());\n      }\n\n      seen.get(type)?.add(id);\n\n      if (!allows(visible[type], id)) {\n        audit.violations.push({ url, status, type, id });\n      }\n    });\n  };\n\n  // One request, and the pages after it.\n  const read = async (first: string, route: AuditedRoute) => {\n    let url: string | undefined = first;\n\n    // A relationship or related endpoint whose owner the request may not\n    // see. Answering at all, whatever it answers with, tells the client the\n    // owner exists, and what it is linked to: the owner is in the URL, not\n    // in the response, so `check()` cannot catch it.\n    const hiddenOwner =\n      route.action.startsWith('showRel') &&\n      route.id !== undefined &&\n      !allows(visible[route.type], route.id);\n\n    for (let page = 0; url && page < MAX_PAGES; page += 1) {\n      audit.requests.push(url);\n\n      const res: globalThis.Response = await fetch(origin + url, {\n        headers: { Accept: 'application/vnd.api+json', ...headers }\n      });\n\n      if (!res.ok && !DENIED.has(res.status)) {\n        audit.violations.push({ url, status: res.status });\n        await res.body?.cancel();\n        return;\n      }\n\n      if (res.ok && hiddenOwner && page === 0) {\n        audit.violations.push({\n          url,\n          status: res.status,\n          type: route.type,\n          id: route.id,\n          message:\n            `answered for ${route.type} ${route.id}, which the request ` +\n            'may not see'\n        });\n      }\n\n      // An override may answer with something other than a document (a\n      // string is `text/plain`); only a JSON body can name records.\n      if (!res.ok || !res.headers.get('content-type')?.includes('json')) {\n        await res.body?.cancel();\n        return;\n      }\n\n      const document = (await res.json()) as {\n        links?: { next?: unknown };\n      } | null;\n\n      check(url, res.status, identifiersIn(document));\n\n      if (onDocument && document) {\n        const found = await onDocument({\n          url,\n          status: res.status,\n          route,\n          document: document as Record<string, unknown>\n        });\n        const messages =\n          typeof found === 'string' ? [found] : Array.from(found ?? []);\n\n        const at = { url, status: res.status };\n\n        messages.forEach(message => {\n          audit.violations.push({ ...at, message });\n        });\n      }\n\n      const next: unknown = document?.links?.next;\n\n      url = typeof next === 'string' ? relative(next) : undefined;\n    }\n  };\n\n  for (const route of routes) {\n    const paged = route.params.get('page')\n      ? (route.related ?? route.controller).maxPerPage\n      : undefined;\n\n    // The type the route's records are of: none for a relationship\n    // endpoint, which answers with linkage and takes no parameters.\n    const served =\n      route.type === 'relationship'\n        ? undefined\n        : (route.related ?? route.controller).model.resourceName;\n\n    const query = (include: string | undefined) => {\n      const params = new URLSearchParams(served ? required[served] : {});\n\n      if (include) {\n        params.set('include', include);\n      }\n\n      if (paged) {\n        params.set('page[size]', String(paged));\n      }\n\n      const search = params.toString();\n\n      return search ? `?${search}` : '';\n    };\n\n    const about = {\n      action: route.action as AuditedRoute['action'],\n      type: route.controller.model.resourceName,\n      ...(route.relationship ? { relationship: route.relationship } : {})\n    };\n\n    const targets: Array<[string, AuditedRoute]> = route.dynamicSegments.length\n      ? (await idsOf(route)).map(id => [\n          route.path.replace(':id', encodeURIComponent(id)),\n          { ...about, id }\n        ])\n      : [[route.path, about]];\n\n    for (const [path, target] of targets) {\n      for (const include of includesOf(route)) {\n        await read(path + query(include), target);\n      }\n    }\n  }\n\n  seen.forEach((list, type) => {\n    audit.seen[type] = Array.from(list);\n  });\n\n  return audit;\n}\n", "import { once } from 'events';\nimport { createRequire } from 'module';\nimport { resolve as resolvePath, join as joinPath } from 'path';\nimport type { AddressInfo } from 'net';\n\nimport type Application from '../application';\n\n/** The options of {@link startApp}. */\nexport type StartAppOptions = {\n  /**\n   * The environment to boot in: which `config/environments/*.js` and which\n   * entry of `config/database.js` apply. Sets `NODE_ENV` when given, and\n   * defaults it to `'test'` when unset, until `close()` restores it.\n   */\n  env?: string;\n\n  /** The port to listen on. `0`, the default, takes a free one. */\n  port?: number;\n};\n\n/** An application {@link startApp} booted. */\nexport type StartedApp = {\n  /** The application, for {@link auditVisibility} and the models. */\n  app: Application;\n  /** Where it listens, such as `'http://localhost:53017'`. */\n  origin: string;\n  /**\n   * Stops the server, closes the database connections, and restores\n   * `NODE_ENV` to what it was before `startApp()`.\n   */\n  close: () => Promise<void>;\n};\n\ntype Bundle = {\n  Application: new (options: Record<string, unknown>) => Promise<Application>;\n  config: Record<string, unknown>;\n  database: Record<string, unknown>;\n};\n\n// The bundles booting or booted in this process. Booting sets up an app's\n// model classes, which happens once per process: a second boot of the same\n// bundle fails. A failed boot is removed again, so a retry reports its own\n// error rather than \"already started\".\nconst started = new Set<string>();\n\n// The first error each bundle failed to boot with: a failed boot can leave the\n// app half set up, so a retry may fail on that rather than on the cause.\nconst failed = new Map<string, unknown>();\n\nconst messageOf = (error: unknown) =>\n  error instanceof Error ? error.message : String(error);\n\n/**\n * Boot the app at `path` in the test's own process, from its compiled\n * bundle (`dist/bundle.js`), and listen on a free port.\n *\n * ```javascript\n * import { startApp } from 'lumen-framework/testing';\n *\n * let app, origin, close;\n *\n * beforeAll(async () => {\n *   ({ app, origin, close } = await startApp(process.cwd()));\n * });\n *\n * afterAll(() => close());\n * ```\n *\n * The bundle must be compiled for the environment first, as `lumen build`\n * and the `lumen db:*` commands do. Its model classes are set up once per\n * process, so start an app once and share it between test files; starting\n * the same one again throws. `NODE_ENV` holds the app's environment until\n * `close()`.\n *\n * @param path - The app's root directory.\n * @param options - The environment and port.\n * @returns The application, where it listens, and how to stop it.\n * @throws When the app at `path` was already started in this process.\n */\nexport default async function startApp(\n  path: string,\n  { env, port = 0 }: StartAppOptions = {}\n): Promise<StartedApp> {\n  const root = resolvePath(path);\n  const bundlePath = joinPath(root, 'dist', 'bundle.js');\n\n  if (started.has(bundlePath)) {\n    throw new Error(\n      `startApp: ${root} was already started in this process. Its models ` +\n        'are set up once per process: start it once and share it.'\n    );\n  }\n\n  // Read when the bundle loads, which is why it is set first. It stays set\n  // while the app runs: the app reads it again per request (whether a 500\n  // shows its message).\n  const previous = process.env.NODE_ENV;\n  const restoreEnv = () => {\n    if (previous === undefined) {\n      delete process.env.NODE_ENV;\n    } else {\n      process.env.NODE_ENV = previous;\n    }\n  };\n\n  process.env.NODE_ENV = env ?? previous ?? 'test';\n  started.add(bundlePath);\n\n  let app: Application;\n\n  try {\n    // The app's bundle, resolved at runtime: not a module of the framework.\n    const {\n      Application: App,\n      config,\n      database\n    } = createRequire(bundlePath)(bundlePath) as Bundle;\n\n    app = await new App({ ...config, database, path: root, port });\n\n    if (!app.server.instance.listening) {\n      await once(app.server.instance, 'listening');\n    }\n  } catch (error) {\n    started.delete(bundlePath);\n    restoreEnv();\n\n    const earlier = failed.get(bundlePath);\n\n    if (failed.has(bundlePath)) {\n      throw new Error(\n        `startApp: booting ${root} failed: ${messageOf(error)}. An earlier ` +\n          `attempt in this process failed first, with: ${messageOf(earlier)}. ` +\n          'A failed boot can leave the app half set up: fix that one first.',\n        { cause: error }\n      );\n    }\n\n    failed.set(bundlePath, error);\n    throw error;\n  }\n\n  const { port: listening } = app.server.instance.address() as AddressInfo;\n\n  return {\n    app,\n    origin: `http://localhost:${listening}`,\n    close: async () => {\n      try {\n        await app.close();\n      } finally {\n        restoreEnv();\n      }\n    }\n  };\n}\n"],
+  "mappings": "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",
+  "names": ["resolvePath", "joinPath"]
+}

package/dist/testing.mjs

@@ -0,0 +1,252 @@
+// src/packages/testing/utils/identifiers-in.ts
+var isIdentifier = (value) => typeof value === "object" && value !== null && "type" in value && "id" in value;
+function identifiersIn(document) {
+  const found = [];
+  const add = (value) => {
+    if (isIdentifier(value)) {
+      found.push({ type: value.type, id: String(value.id) });
+    }
+  };
+  const addLinkage = (linkage) => {
+    (Array.isArray(linkage) ? linkage : [linkage]).forEach(add);
+  };
+  const addResource = (resource) => {
+    add(resource);
+    if (isIdentifier(resource)) {
+      Object.values(resource.relationships ?? {}).forEach(
+        (relationship) => addLinkage(relationship?.data)
+      );
+    }
+  };
+  if (typeof document !== "object" || document === null) {
+    return found;
+  }
+  const { data, included } = document;
+  (Array.isArray(data) ? data : [data]).forEach(addResource);
+  (included ?? []).forEach(addResource);
+  return found;
+}
+
+// src/packages/testing/audit-visibility.ts
+var READS = /* @__PURE__ */ new Set(["index", "show", "showRelationship", "showRelated"]);
+var DENIED = /* @__PURE__ */ new Set([401, 403, 404]);
+var MAX_PAGES = 1e3;
+function originOf(app) {
+  const address = app.server.instance.address();
+  if (!address) {
+    throw new Error(
+      "auditVisibility: the application is not listening. Start it (`startApp()`), or pass the `origin` of the server to audit."
+    );
+  }
+  return `http://localhost:${address.port}`;
+}
+function allows(visible, id) {
+  if (visible === true) {
+    return true;
+  }
+  if (typeof visible === "function") {
+    return visible(id);
+  }
+  return Boolean(visible?.some((allowed) => String(allowed) === id));
+}
+function includesOf(route) {
+  const include = route.params.get("include");
+  const paths = include ? Array.from(include) : [];
+  const longest = paths.filter(
+    (path) => !paths.some((other) => other.startsWith(`${path}.`))
+  );
+  return longest.length ? [void 0, longest.join(",")] : [void 0];
+}
+async function auditVisibility(app, {
+  namespace = "",
+  visible,
+  headers = {},
+  ids = {},
+  query: required = {},
+  origin = originOf(app),
+  onDocument
+}) {
+  const audit = { requests: [], violations: [], seen: {} };
+  const seen = /* @__PURE__ */ new Map();
+  const routes = Array.from(app.router.values()).filter(
+    (route) => route.method === "GET" && READS.has(route.action) && route.controller.namespace === namespace
+  );
+  if (!routes.length) {
+    throw new Error(
+      `auditVisibility: namespace '/${namespace}' serves no index, show, relationship or related routes.`
+    );
+  }
+  const relative = (link) => {
+    const { pathname, search } = new URL(link, origin);
+    return pathname + search;
+  };
+  const idsCache = /* @__PURE__ */ new Map();
+  const idsOf = async (route) => {
+    const { model } = route.controller;
+    const type = model.resourceName;
+    let list = idsCache.get(type);
+    if (!list) {
+      const given = ids[type];
+      list = given ? given.map(String) : (await model.select(model.primaryKey)).map((record) => String(record.getPrimaryKey()));
+      idsCache.set(type, list);
+    }
+    return list;
+  };
+  const check = (url, status, found) => {
+    found.forEach(({ type, id }) => {
+      if (!seen.has(type)) {
+        seen.set(type, /* @__PURE__ */ new Set());
+      }
+      seen.get(type)?.add(id);
+      if (!allows(visible[type], id)) {
+        audit.violations.push({ url, status, type, id });
+      }
+    });
+  };
+  const read = async (first, route) => {
+    let url = first;
+    const hiddenOwner = route.action.startsWith("showRel") && route.id !== void 0 && !allows(visible[route.type], route.id);
+    for (let page = 0; url && page < MAX_PAGES; page += 1) {
+      audit.requests.push(url);
+      const res = await fetch(origin + url, {
+        headers: { Accept: "application/vnd.api+json", ...headers }
+      });
+      if (!res.ok && !DENIED.has(res.status)) {
+        audit.violations.push({ url, status: res.status });
+        await res.body?.cancel();
+        return;
+      }
+      if (res.ok && hiddenOwner && page === 0) {
+        audit.violations.push({
+          url,
+          status: res.status,
+          type: route.type,
+          id: route.id,
+          message: `answered for ${route.type} ${route.id}, which the request may not see`
+        });
+      }
+      if (!res.ok || !res.headers.get("content-type")?.includes("json")) {
+        await res.body?.cancel();
+        return;
+      }
+      const document = await res.json();
+      check(url, res.status, identifiersIn(document));
+      if (onDocument && document) {
+        const found = await onDocument({
+          url,
+          status: res.status,
+          route,
+          document
+        });
+        const messages = typeof found === "string" ? [found] : Array.from(found ?? []);
+        const at = { url, status: res.status };
+        messages.forEach((message) => {
+          audit.violations.push({ ...at, message });
+        });
+      }
+      const next = document?.links?.next;
+      url = typeof next === "string" ? relative(next) : void 0;
+    }
+  };
+  for (const route of routes) {
+    const paged = route.params.get("page") ? (route.related ?? route.controller).maxPerPage : void 0;
+    const served = route.type === "relationship" ? void 0 : (route.related ?? route.controller).model.resourceName;
+    const query = (include) => {
+      const params = new URLSearchParams(served ? required[served] : {});
+      if (include) {
+        params.set("include", include);
+      }
+      if (paged) {
+        params.set("page[size]", String(paged));
+      }
+      const search = params.toString();
+      return search ? `?${search}` : "";
+    };
+    const about = {
+      action: route.action,
+      type: route.controller.model.resourceName,
+      ...route.relationship ? { relationship: route.relationship } : {}
+    };
+    const targets = route.dynamicSegments.length ? (await idsOf(route)).map((id) => [
+      route.path.replace(":id", encodeURIComponent(id)),
+      { ...about, id }
+    ]) : [[route.path, about]];
+    for (const [path, target] of targets) {
+      for (const include of includesOf(route)) {
+        await read(path + query(include), target);
+      }
+    }
+  }
+  seen.forEach((list, type) => {
+    audit.seen[type] = Array.from(list);
+  });
+  return audit;
+}
+
+// src/packages/testing/start-app.ts
+import { once } from "events";
+import { createRequire } from "module";
+import { resolve as resolvePath, join as joinPath } from "path";
+var started = /* @__PURE__ */ new Set();
+var failed = /* @__PURE__ */ new Map();
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+async function startApp(path, { env, port = 0 } = {}) {
+  const root = resolvePath(path);
+  const bundlePath = joinPath(root, "dist", "bundle.js");
+  if (started.has(bundlePath)) {
+    throw new Error(
+      `startApp: ${root} was already started in this process. Its models are set up once per process: start it once and share it.`
+    );
+  }
+  const previous = process.env.NODE_ENV;
+  const restoreEnv = () => {
+    if (previous === void 0) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = previous;
+    }
+  };
+  process.env.NODE_ENV = env ?? previous ?? "test";
+  started.add(bundlePath);
+  let app;
+  try {
+    const {
+      Application: App,
+      config,
+      database
+    } = createRequire(bundlePath)(bundlePath);
+    app = await new App({ ...config, database, path: root, port });
+    if (!app.server.instance.listening) {
+      await once(app.server.instance, "listening");
+    }
+  } catch (error) {
+    started.delete(bundlePath);
+    restoreEnv();
+    const earlier = failed.get(bundlePath);
+    if (failed.has(bundlePath)) {
+      throw new Error(
+        `startApp: booting ${root} failed: ${messageOf(error)}. An earlier attempt in this process failed first, with: ${messageOf(earlier)}. A failed boot can leave the app half set up: fix that one first.`,
+        { cause: error }
+      );
+    }
+    failed.set(bundlePath, error);
+    throw error;
+  }
+  const { port: listening } = app.server.instance.address();
+  return {
+    app,
+    origin: `http://localhost:${listening}`,
+    close: async () => {
+      try {
+        await app.close();
+      } finally {
+        restoreEnv();
+      }
+    }
+  };
+}
+export {
+  auditVisibility,
+  startApp
+};
+//# sourceMappingURL=testing.mjs.map