@nitpicker/report-html 0.20.0 → 0.22.0

package/lib/collect-html-report-pages.d.ts

@@ -1,12 +1,23 @@
 import type { ArchiveAccessor } from '@nitpicker/crawler';
 import type { HtmlReportPage } from '@nitpicker/viewer/report-ui';
+/** Row-set restriction for {@link collectHtmlReportPages}. */
+export interface CollectHtmlReportPagesOptions {
+    /** Directory-prefix filters. Empty or omitted lists every inner page. */
+    readonly directories?: readonly string[];
+    /**
+     * Exact-match URL allowlist, already normalized (see
+     * `resolvePageListUrlFilter`). ANDed with `directories` when both are
+     * given — see `PageListRowFilterOptions.urls`'s docs.
+     */
+    readonly urls?: readonly string[];
+}
 /**
  * Collects inner-page rows for a static HTML report in `natural_url_rank`
  * order, attaching redirect sources and per-page resource-file tallies.
  * @param accessor - Archive whose viewer read model is already current.
- * @param directories - Directory-prefix filters. Empty or omitted lists every inner page.
+ * @param options - Row-set restriction. Empty or omitted lists every inner page.
  * @returns Page rows ready for `renderHtmlReport`.
  * @example
- * const pages = await collectHtmlReportPages(accessor, ['/docs']);
+ * const pages = await collectHtmlReportPages(accessor, { directories: ['/docs'] });
  */
-export declare function collectHtmlReportPages(accessor: ArchiveAccessor, directories?: readonly string[]): Promise<HtmlReportPage[]>;
+export declare function collectHtmlReportPages(accessor: ArchiveAccessor, options?: CollectHtmlReportPagesOptions): Promise<HtmlReportPage[]>;

package/lib/collect-html-report-pages.js

@@ -3,15 +3,15 @@ import { buildRedirectFromUrlsByDestId, getResourceFileCountsByPageIds, streamPa
  * Collects inner-page rows for a static HTML report in `natural_url_rank`
  * order, attaching redirect sources and per-page resource-file tallies.
  * @param accessor - Archive whose viewer read model is already current.
- * @param directories - Directory-prefix filters. Empty or omitted lists every inner page.
+ * @param options - Row-set restriction. Empty or omitted lists every inner page.
  * @returns Page rows ready for `renderHtmlReport`.
  * @example
- * const pages = await collectHtmlReportPages(accessor, ['/docs']);
+ * const pages = await collectHtmlReportPages(accessor, { directories: ['/docs'] });
  */
-export async function collectHtmlReportPages(accessor, directories = []) {
+export async function collectHtmlReportPages(accessor, options = {}) {
     const redirectFrom = await buildRedirectFromUrlsByDestId(accessor);
     const pages = [];
-    for await (const chunk of streamPageListRows(accessor, { directories })) {
+    for await (const chunk of streamPageListRows(accessor, options)) {
         const counts = await getResourceFileCountsByPageIds(accessor, chunk.map((row) => row.pageId));
         for (const row of chunk) {
             const resources = counts.get(row.pageId) ?? { total: 0, exists: 0 };
@@ -24,6 +24,7 @@ export async function collectHtmlReportPages(accessor, directories = []) {
                 resourceFilesExists: resources.exists,
                 resourceFilesTotal: resources.total,
                 consoleErrorCount: row.consoleErrorCount,
+                redirectTo: row.redirectDestUrl,
             });
         }
     }

package/lib/page-report-limit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The static HTML report's inner-page ceiling, shared by both page-selection
+ * paths (`resolveDirectoryPrefixes`'s interactive `--html-dirs` narrowing and
+ * `resolvePageSelection`'s non-interactive `--urls` guard) so the two can
+ * never drift to different limits.
+ */
+export declare const PAGE_REPORT_LIMIT = 10000;

package/lib/page-report-limit.js

@@ -0,0 +1,7 @@
+/**
+ * The static HTML report's inner-page ceiling, shared by both page-selection
+ * paths (`resolveDirectoryPrefixes`'s interactive `--html-dirs` narrowing and
+ * `resolvePageSelection`'s non-interactive `--urls` guard) so the two can
+ * never drift to different limits.
+ */
+export const PAGE_REPORT_LIMIT = 10_000;

package/lib/report.js

@@ -1,11 +1,11 @@
 import { writeFile } from 'node:fs/promises';
 import { TaskList } from '@d-zero/dealer';
-import { getViewerSummary, requireViewerReadModel } from '@nitpicker/query';
+import { getViewerSummary, requireViewerReadModel, resolveAndValidatePageListUrlFilter, warnUnmatchedPageListUrls, } from '@nitpicker/query';
 import { renderHtmlReport } from '@nitpicker/viewer/report-ui';
 import { collectHtmlReportPages } from './collect-html-report-pages.js';
 import { openReportArchive } from './open-report-archive.js';
-import { resolveDirectoryPrefixes } from './resolve-directory-prefixes.js';
 import { resolveOutputPath } from './resolve-output-path.js';
+import { resolvePageSelection } from './resolve-page-selection.js';
 /** A `write()`-only sink that renders nothing, for `params.silent`. */
 const NULL_STREAM = {
     write: () => true,
@@ -33,24 +33,32 @@ const NULL_STREAM = {
 export async function report(params) {
     await using archive = await openReportArchive(params.filePath, params.onExtractProgress);
     await requireViewerReadModel(archive.accessor);
-    const prefixes = await resolveDirectoryPrefixes({
+    const warn = params.silent
+        ? () => { }
+        : (message) => {
+            // eslint-disable-next-line no-console
+            console.warn(message);
+        };
+    const normalizedUrls = params.urls === undefined
+        ? undefined
+        : await resolveAndValidatePageListUrlFilter(archive.accessor, params.urls, warn);
+    const selection = await resolvePageSelection({
         accessor: archive.accessor,
-        initialInput: params.directoryInput,
+        directoryInput: params.directoryInput,
+        urls: normalizedUrls,
         interactive: params.interactive === true,
-        onWarn: params.silent
-            ? () => { }
-            : (message) => {
-                // eslint-disable-next-line no-console
-                console.warn(message);
-            },
+        onWarn: warn,
     });
-    const directoryPrefixes = prefixes.map((prefix) => prefix.display);
+    const directoryPrefixes = selection.directories;
     const outputPath = resolveOutputPath(params.filePath, params.outputPath);
     let html = '';
     let pipeline = TaskList.from(0);
     pipeline = pipeline.pipe('Collect pages', async (input, ctx) => {
         ctx.progress('reading inner pages...');
-        const pages = await collectHtmlReportPages(archive.accessor, directoryPrefixes);
+        const pages = await collectHtmlReportPages(archive.accessor, {
+            directories: directoryPrefixes,
+            urls: selection.urls,
+        });
         const summary = await getViewerSummary(archive.accessor);
         ctx.progress(`${pages.length.toLocaleString()} pages`);
         html = renderHtmlReport({
@@ -60,6 +68,9 @@ export async function report(params) {
             generatedAt: new Date().toISOString(),
             directoryPrefixes,
         });
+        if (selection.urls) {
+            await warnUnmatchedPageListUrls(archive.accessor, selection.urls, warn);
+        }
         return input;
     });
     pipeline = pipeline.pipe('Write HTML', async (input, ctx) => {

package/lib/resolve-directory-prefixes.js

@@ -1,8 +1,8 @@
 import { countPageListHostnames, countPageListRows } from '@nitpicker/query';
 import enquirer from 'enquirer';
 import { HtmlReportCancelledError } from './html-report-cancelled-error.js';
+import { PAGE_REPORT_LIMIT } from './page-report-limit.js';
 import { parseDirectoryInput } from './parse-directory-input.js';
-const PAGE_LIMIT = 10_000;
 /**
  * Asks for comma-separated directory prefixes on a TTY.
  * @returns The raw input string.
@@ -40,7 +40,7 @@ export async function resolveDirectoryPrefixes(options) {
     const unfilteredTotal = await countPageListRows(options.accessor);
     const hostnameCount = await countPageListHostnames(options.accessor);
     let input = options.initialInput;
-    if (unfilteredTotal <= PAGE_LIMIT && input == null) {
+    if (unfilteredTotal <= PAGE_REPORT_LIMIT && input == null) {
         return [];
     }
     for (;;) {
@@ -68,7 +68,7 @@ export async function resolveDirectoryPrefixes(options) {
             const selectedTotal = await countPageListRows(options.accessor, {
                 directories: prefixes.map((prefix) => prefix.display),
             });
-            if (selectedTotal > PAGE_LIMIT) {
+            if (selectedTotal > PAGE_REPORT_LIMIT) {
                 throw new Error(`The selected directories contain ${selectedTotal.toLocaleString()} inner pages; narrow them to 10,000 or fewer.`);
             }
             return prefixes;

package/lib/resolve-page-selection.d.ts

@@ -0,0 +1,40 @@
+import type { ArchiveAccessor } from '@nitpicker/crawler';
+/** Row-set restriction {@link resolvePageSelection} resolves to. */
+export interface PageSelection {
+    /** Directory-prefix filters, display form, ready for `collectHtmlReportPages`. */
+    readonly directories: string[];
+    /** Normalized URL allowlist, or `undefined` when `--urls` was not given. */
+    readonly urls: readonly string[] | undefined;
+}
+interface ResolvePageSelectionOptions {
+    readonly accessor: ArchiveAccessor;
+    readonly directoryInput?: string;
+    /** Already-normalized URLs (via `resolvePageListUrlFilter`), or `undefined` when `--urls` was not given. */
+    readonly urls?: readonly string[];
+    readonly interactive: boolean;
+    readonly onWarn: (message: string) => void;
+}
+/**
+ * Decides the report's page restriction: the `--urls` path (this function's
+ * own AND-combination with `--html-dirs`, no interactive prompting, no
+ * 10,000-page-limit *enforcement via prompting* since a URL list is expected
+ * to already be well under it) or the pre-existing `--html-dirs`-only path
+ * (delegated to {@link resolveDirectoryPrefixes} unchanged, including its
+ * interactive prompt loop).
+ *
+ * `--urls` skips `resolveDirectoryPrefixes`'s prompt-forcing flow entirely
+ * because that flow's whole purpose — interactively narrowing an
+ * unboundedly large report down to size — doesn't apply once the caller has
+ * already named the exact pages it wants. The 10,000-page ceiling itself
+ * still applies (checked after combining `--urls` with any `--html-dirs`
+ * narrowing), so a directory prefix that happens to still leave the
+ * URL-restricted set too large is still rejected.
+ * @param options - Archive, optional non-interactive directory input,
+ *   optional normalized URL allowlist, interactivity, and warning sink.
+ * @returns The resolved directory prefixes and URL allowlist to pass to
+ *   `collectHtmlReportPages`.
+ * @throws {Error} If the `--urls` path's combined row count exceeds the
+ *   10,000-page ceiling.
+ */
+export declare function resolvePageSelection(options: ResolvePageSelectionOptions): Promise<PageSelection>;
+export {};

package/lib/resolve-page-selection.js

@@ -0,0 +1,51 @@
+import { countPageListRows } from '@nitpicker/query';
+import { PAGE_REPORT_LIMIT } from './page-report-limit.js';
+import { parseDirectoryInput } from './parse-directory-input.js';
+import { resolveDirectoryPrefixes } from './resolve-directory-prefixes.js';
+/**
+ * Decides the report's page restriction: the `--urls` path (this function's
+ * own AND-combination with `--html-dirs`, no interactive prompting, no
+ * 10,000-page-limit *enforcement via prompting* since a URL list is expected
+ * to already be well under it) or the pre-existing `--html-dirs`-only path
+ * (delegated to {@link resolveDirectoryPrefixes} unchanged, including its
+ * interactive prompt loop).
+ *
+ * `--urls` skips `resolveDirectoryPrefixes`'s prompt-forcing flow entirely
+ * because that flow's whole purpose — interactively narrowing an
+ * unboundedly large report down to size — doesn't apply once the caller has
+ * already named the exact pages it wants. The 10,000-page ceiling itself
+ * still applies (checked after combining `--urls` with any `--html-dirs`
+ * narrowing), so a directory prefix that happens to still leave the
+ * URL-restricted set too large is still rejected.
+ * @param options - Archive, optional non-interactive directory input,
+ *   optional normalized URL allowlist, interactivity, and warning sink.
+ * @returns The resolved directory prefixes and URL allowlist to pass to
+ *   `collectHtmlReportPages`.
+ * @throws {Error} If the `--urls` path's combined row count exceeds the
+ *   10,000-page ceiling.
+ */
+export async function resolvePageSelection(options) {
+    if (options.urls === undefined) {
+        const prefixes = await resolveDirectoryPrefixes({
+            accessor: options.accessor,
+            initialInput: options.directoryInput,
+            interactive: options.interactive,
+            onWarn: options.onWarn,
+        });
+        return { directories: prefixes.map((prefix) => prefix.display), urls: undefined };
+    }
+    const directoryPrefixes = options.directoryInput
+        ? parseDirectoryInput(options.directoryInput)
+        : [];
+    const directories = directoryPrefixes.map((prefix) => prefix.display);
+    const total = await countPageListRows(options.accessor, {
+        urls: options.urls,
+        directories,
+    });
+    if (total > PAGE_REPORT_LIMIT) {
+        throw new Error(`--urls matched ${total.toLocaleString()} inner page(s)` +
+            (directories.length > 0 ? ' after --html-dirs narrowing' : '') +
+            `; exceeds the ${PAGE_REPORT_LIMIT.toLocaleString()}-page report limit. Narrow --urls or --html-dirs further.`);
+    }
+    return { directories, urls: options.urls };
+}

package/lib/types.d.ts

@@ -6,6 +6,16 @@ export interface HtmlReportParams {
     readonly outputPath?: string;
     /** Comma-separated directory prefixes used for non-interactive large reports. */
     readonly directoryInput?: string;
+    /**
+     * URL allowlist restricting the report to exactly these pages, already
+     * classified into valid/invalid by the CLI (`readUrlListFile` +
+     * `isValidUrl`) but not yet normalized to the archive's own URL form —
+     * `report()` does that via `resolveAndValidatePageListUrlFilter` once the
+     * archive is open. ANDed with `directoryInput` when both are given. Skips the
+     * interactive/10,000-page-limit-prompting flow `directoryInput` alone
+     * triggers — see `resolvePageSelection`.
+     */
+    readonly urls?: readonly string[];
     /** Whether the reporter may prompt for directory prefixes. */
     readonly interactive?: boolean;
     /** Suppresses completion and warning output. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nitpicker/report-html",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"description": "Self-contained static HTML reports for Nitpicker archives",
 	"author": "D-ZERO",
 	"license": "Apache-2.0",
@@ -30,10 +30,10 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/dealer": "1.13.1",
-		"@nitpicker/crawler": "0.20.0",
-		"@nitpicker/query": "0.20.0",
-		"@nitpicker/viewer": "0.20.0",
+		"@d-zero/dealer": "1.14.0",
+		"@nitpicker/crawler": "0.22.0",
+		"@nitpicker/query": "0.22.0",
+		"@nitpicker/viewer": "0.22.0",
 		"enquirer": "2.4.1",
 		"react": "19.2.8",
 		"react-dom": "19.2.8"
@@ -42,5 +42,5 @@
 		"@d-zero/shared": "0.23.0",
 		"vitest": "4.1.11"
 	},
-	"gitHead": "c322c99bbaca356646d06130cb6eec2706c0ddc5"
+	"gitHead": "934b1714f4394effb3865d84bf8348ed74f45840"
 }