@piwitests/instrumentation-nitro 0.52.0 → 0.53.0

package/README.md

@@ -28,7 +28,21 @@ export { default } from '@piwitests/instrumentation-nitro'
 
 That's all. Nitro auto-loads every file in that directory on startup (`server/plugins/` in a Nuxt app, `plugins/` under the Nitro `srcDir` in a standalone Nitro app).
 
-A runnable end-to-end demo lives in [`examples/playwright-fixtures`](../../examples/playwright-fixtures) — a standalone Nitro app instrumented with this package, with a Playwright spec showing the captured logs in the dashboard.
+[`examples/sample-app`](../../examples/sample-app) runs a standalone Nitro app with this package wired in (`backends/nitro/`), and a Playwright suite that checks what it sends: backend logs, the route manifest, server spans and server probes.
+
+## Route manifest
+
+Outside production, the plugin serves `GET /__piwi/manifest`: the routes the app declares. The Piwi reporter fetches it when a run starts and uploads it, so a declared route no test reaches becomes a **declared, never hit** gap in the Test Map. Nitro has no route table to read while it runs, so add the package's module, which reads it when the server is bundled (again on each rebuild in development):
+
+```typescript
+// Standalone Nitro: nitro.config.ts
+export default defineNitroConfig({ modules: ['@piwitests/instrumentation-nitro/module'] })
+
+// Nuxt: nuxt.config.ts
+export default defineNuxtConfig({ nitro: { modules: ['@piwitests/instrumentation-nitro/module'] } })
+```
+
+The manifest then lists every route Nitro scanned (`routes/`, `api/`) and every handler the config declares, middleware and a fallback catch-all (`/**`) left out, each with its method (`GET` for a route that answers any method), its pattern (`/api/orders/:id`) and its file relative to the git repository. Without the module, it lists only the routes the server has answered since it started, which the reporter, reading it before any test runs, rarely sees. Nuxt pages are rendered by one catch-all route, so they are not listed: name them in a `piwi.manifest.json`.
 
 ## What gets captured
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { NitroAppPlugin } from 'nitropack';
-export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, type PiwiProbeSpec, type SignedProbe, } from './probe';
-export { buildRouteManifest, recordObservedRoute, collapsePathPattern, type RouteManifest } from './manifest';
-export * from './faults';
+export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, type PiwiProbeSpec, type SignedProbe, } from './probe.js';
+export { buildRouteManifest, recordObservedRoute, collapsePathPattern, type RouteManifest } from './manifest.js';
+export * from './faults.js';
 export interface PiwiTestLogEntry {
     timestamp: number;
     level: string;

package/dist/index.js

@@ -3,12 +3,13 @@ import { randomBytes } from 'node:crypto';
 import { gzipSync } from 'node:zlib';
 import { consola } from 'consola';
 import { createError } from 'h3';
-import { verifyProbeHeader, ProbeNonceCache } from './probe';
-import { buildRouteManifest, recordObservedRoute, collapsePathPattern, } from './manifest';
-import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtremeFault, isDataFault, isDependencyFault, dependencyCallMatches, mutateResponseBody, appliedFaultLabel, } from './faults';
-export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe';
-export { buildRouteManifest, recordObservedRoute, collapsePathPattern } from './manifest';
-export * from './faults';
+import { verifyProbeHeader, ProbeNonceCache } from './probe.js';
+import { buildRouteManifest, recordObservedRoute, collapsePathPattern, } from './manifest.js';
+import { declaredRoutes } from './route-table.js';
+import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtremeFault, isDataFault, isDependencyFault, dependencyCallMatches, mutateResponseBody, appliedFaultLabel, } from './faults.js';
+export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe.js';
+export { buildRouteManifest, recordObservedRoute, collapsePathPattern } from './manifest.js';
+export * from './faults.js';
 const MAX_ENTRIES = 50;
 const MAX_MSG_LENGTH = 500;
 const MAX_STACK_FRAMES = 5;
@@ -90,8 +91,9 @@ const PROBE_SECRET = process.env.PIWI_PROBE_SECRET || undefined;
 /** The declared-surface route path the plugin serves outside production. */
 const MANIFEST_PATH = '/__piwi/manifest';
 /**
- * Routes the server has matched this process, accumulated for `/__piwi/manifest`.
- * Nitro exposes no runtime route table, so the manifest is built from observation.
+ * Routes the server has matched this process, accumulated for `/__piwi/manifest`
+ * next to the declared ones: Nitro exposes no runtime route table, so without the
+ * module (`./module`, which reads it at build time) only these are listed.
  */
 const observedRoutes = new Map();
 /**
@@ -141,13 +143,17 @@ const piwiTestLogs = (nitroApp) => {
     const originalHandler = nitroApp.h3App.handler;
     nitroApp.h3App.handler = ((event) => {
         // Serve the declared-surface manifest outside production (the plugin already
-        // returned early when log capture is disabled). Built from observed routes.
+        // returned early when log capture is disabled): the routes the module declared,
+        // then the ones observed.
         const requestPath = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
         if (requestPath === MANIFEST_PATH) {
+            const routes = new Map();
+            for (const route of [...declaredRoutes(), ...observedRoutes.values()])
+                recordObservedRoute(routes, route);
             const res = event.node.res;
             res.statusCode = 200;
             res.setHeader('Content-Type', 'application/json');
-            res.end(JSON.stringify(buildRouteManifest(observedRoutes)));
+            res.end(JSON.stringify(buildRouteManifest(routes)));
             return;
         }
         const store = { logs: [], spans: [], startMs: Date.now() };
@@ -220,8 +226,10 @@ const piwiTestLogs = (nitroApp) => {
                 const traceId = parseTraceparent(event.node.req.headers['traceparent']) ?? randomBytes(16).toString('hex');
                 const handlerFile = resolveHandlerFile(event);
                 // Record this route for the declared-surface manifest. Prefer the matched
-                // route's own pattern; fall back to collapsing the concrete path.
-                const matchedPattern = event.context?.matchedRoute?.route;
+                // route's own pattern (`path` in h3 1.x, `route` in later versions); fall
+                // back to collapsing the concrete path.
+                const matchedRoute = event.context?.matchedRoute;
+                const matchedPattern = matchedRoute?.route ?? matchedRoute?.path;
                 const pattern = typeof matchedPattern === 'string' && matchedPattern ? matchedPattern : collapsePathPattern(path);
                 recordObservedRoute(observedRoutes, { method, pattern, handler: handlerFile });
                 const rootSpan = {

package/dist/manifest.d.ts

@@ -1,10 +1,11 @@
 /**
  * The declared-surface route manifest the plugin serves at `/__piwi/manifest`
  * outside production. Nitro has no stable public API to enumerate its route table
- * at runtime, so the manifest is accumulated from the routes the server actually
- * matches — each request contributes its method, matched pattern and handler
- * file. The Piwi reporter fetches it once at run start and uploads it, and a
- * declared route no test reaches becomes a "declared, never hit" gap.
+ * at runtime: the module (`./module`) reads it at build time (`route-table.ts`),
+ * and the routes the server matches are added as they come, each request with its
+ * method, matched pattern and handler file. The Piwi reporter fetches it once at
+ * run start and uploads it, and a declared route no test reaches becomes a
+ * "declared, never hit" gap, which only the module's routes can give.
  */
 /** One declared route: method, path pattern and the handler's source file. */
 export interface ManifestRouteEntry {

package/dist/manifest.js

@@ -1,10 +1,11 @@
 /**
  * The declared-surface route manifest the plugin serves at `/__piwi/manifest`
  * outside production. Nitro has no stable public API to enumerate its route table
- * at runtime, so the manifest is accumulated from the routes the server actually
- * matches — each request contributes its method, matched pattern and handler
- * file. The Piwi reporter fetches it once at run start and uploads it, and a
- * declared route no test reaches becomes a "declared, never hit" gap.
+ * at runtime: the module (`./module`) reads it at build time (`route-table.ts`),
+ * and the routes the server matches are added as they come, each request with its
+ * method, matched pattern and handler file. The Piwi reporter fetches it once at
+ * run start and uploads it, and a declared route no test reaches becomes a
+ * "declared, never hit" gap, which only the module's routes can give.
  */
 /**
  * Collapse a concrete request path to a pattern: numeric and uuid segments become

package/dist/module.d.ts

@@ -0,0 +1,3 @@
+import type { NitroModule } from 'nitropack';
+declare const piwiRouteTable: NitroModule;
+export default piwiRouteTable;

package/dist/module.js

@@ -0,0 +1,33 @@
+/**
+ * The Nitro module that gives the route manifest Nitro's whole route table:
+ *
+ * ```ts
+ * export default defineNitroConfig({ modules: ['@piwitests/instrumentation-nitro/module'] });
+ * ```
+ *
+ * In Nuxt, the same entry goes under `nitro.modules`. Without it, `/__piwi/manifest`
+ * lists only the routes the server has answered. Modules run before Nitro scans its
+ * route files, so the table is read when the server is bundled, again on each
+ * rebuild in development.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ROUTE_TABLE_ID, declaredRoutesOf, routeTablePlugin } from './route-table.js';
+/** The repository root above `dir` (the closest folder holding `.git`), else `dir` itself. */
+function repositoryRoot(dir) {
+    for (let current = dir;; current = dirname(current)) {
+        if (existsSync(join(current, '.git')))
+            return current;
+        if (dirname(current) === current)
+            return dir;
+    }
+}
+const piwiRouteTable = {
+    name: 'piwi-route-table',
+    setup(nitro) {
+        const root = repositoryRoot(nitro.options.rootDir);
+        nitro.options.virtual[ROUTE_TABLE_ID] = () => routeTablePlugin(declaredRoutesOf([...nitro.scannedHandlers, ...nitro.options.handlers], root));
+        nitro.options.plugins.push(ROUTE_TABLE_ID);
+    },
+};
+export default piwiRouteTable;

package/dist/route-table.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The route table the Nitro module (`@piwitests/instrumentation-nitro/module`)
+ * reads at build time, from the routes Nitro scanned (`routes/`, `api/`) and the
+ * handlers its config declares. The module writes it into a small generated
+ * plugin, which hands it to the runtime plugin through a global, so
+ * `/__piwi/manifest` lists every declared route from the server's first request,
+ * reached or not.
+ */
+import type { ManifestRouteEntry } from './manifest.js';
+/** The id of the generated plugin that carries the route table. */
+export declare const ROUTE_TABLE_ID = "#piwi/route-table";
+/** A Nitro handler, as `nitro.scannedHandlers` and `nitro.options.handlers` list it. */
+export interface NitroHandlerLike {
+    route?: string;
+    method?: string;
+    handler?: string;
+    middleware?: boolean;
+}
+/**
+ * The declared routes of Nitro's handlers: every handler with a route, middleware
+ * and a fallback catch-all left out, one entry per method and pattern. A handler
+ * without a method answers every method and is declared as `GET`. Its file is
+ * named relative to `root` (the repository root, else the app's root) with `/`
+ * separators.
+ */
+export declare function declaredRoutesOf(handlers: NitroHandlerLike[], root: string): ManifestRouteEntry[];
+/** The source of the generated plugin: it sets the route table on the global the runtime plugin reads. */
+export declare function routeTablePlugin(routes: ManifestRouteEntry[]): string;
+/** The routes the generated plugin set; none when the app does not use the module. */
+export declare function declaredRoutes(): ManifestRouteEntry[];

package/dist/route-table.js

@@ -0,0 +1,42 @@
+/** The id of the generated plugin that carries the route table. */
+export const ROUTE_TABLE_ID = '#piwi/route-table';
+/** The global the generated plugin sets the route table on. */
+const DECLARED_ROUTES_KEY = '__piwiDeclaredRoutes';
+/** A route that is only a catch-all (`/**`, `/**:path`): an app's fallback, such as Nuxt's page renderer. */
+const FALLBACK_ROUTE = /^\/\*\*(?::[^/]*)?$/;
+/**
+ * The declared routes of Nitro's handlers: every handler with a route, middleware
+ * and a fallback catch-all left out, one entry per method and pattern. A handler
+ * without a method answers every method and is declared as `GET`. Its file is
+ * named relative to `root` (the repository root, else the app's root) with `/`
+ * separators.
+ */
+export function declaredRoutesOf(handlers, root) {
+    const routes = new Map();
+    for (const handler of handlers) {
+        if (handler.middleware || !handler.route || FALLBACK_ROUTE.test(handler.route))
+            continue;
+        const method = (handler.method || 'get').toUpperCase();
+        const key = `${method} ${handler.route}`;
+        if (routes.has(key))
+            continue;
+        const file = handler.handler ? relativeFile(root, handler.handler) : undefined;
+        routes.set(key, { method, pattern: handler.route, ...(file ? { handler: file } : {}) });
+    }
+    return [...routes.values()];
+}
+/** `file` relative to `root`, with `/` separators; undefined when it is not under `root`. */
+function relativeFile(root, file) {
+    const normalizedRoot = root.replace(/\\/g, '/').replace(/\/$/, '');
+    const normalizedFile = file.replace(/\\/g, '/');
+    return normalizedFile.startsWith(`${normalizedRoot}/`) ? normalizedFile.slice(normalizedRoot.length + 1) : undefined;
+}
+/** The source of the generated plugin: it sets the route table on the global the runtime plugin reads. */
+export function routeTablePlugin(routes) {
+    return `export default function piwiRouteTable() {\n  globalThis.${DECLARED_ROUTES_KEY} = ${JSON.stringify(routes)};\n}\n`;
+}
+/** The routes the generated plugin set; none when the app does not use the module. */
+export function declaredRoutes() {
+    const routes = globalThis[DECLARED_ROUTES_KEY];
+    return Array.isArray(routes) ? routes : [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/instrumentation-nitro",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Nitro/Nuxt server plugin for sending backend logs to Piwi Dashboard via the X-Piwi-Logs response header",
   "homepage": "https://piwitests.dev",
   "repository": {
@@ -17,6 +17,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
     }
   },
   "keywords": [