@nitpicker/core 0.14.0 → 0.15.0

package/lib/get-table-cache-root.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve the storage location for the analyze command's scratch `table`
+ * cache (per-page axe results, cleared at the start of every `analyze` run).
+ *
+ * Defined as a child of {@link getArchiveCacheRoot} so that
+ * `NITPICKER_TAR_CACHE_DIR` — which already redirects the tar-extraction
+ * cache — consistently redirects this cache too, instead of the two caches
+ * silently splitting across different roots.
+ * @returns Absolute path to the `table` cache directory. The `Cache` class
+ *   creates a further subdirectory under this path named after its `name`
+ *   argument.
+ * @example
+ * ```ts
+ * const cache = new Cache('nitpicker-axe', getTableCacheRoot());
+ * await cache.clear();
+ * ```
+ */
+export declare function getTableCacheRoot(): string;

package/lib/get-table-cache-root.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { getArchiveCacheRoot } from '@nitpicker/crawler';
+/**
+ * Resolve the storage location for the analyze command's scratch `table`
+ * cache (per-page axe results, cleared at the start of every `analyze` run).
+ *
+ * Defined as a child of {@link getArchiveCacheRoot} so that
+ * `NITPICKER_TAR_CACHE_DIR` — which already redirects the tar-extraction
+ * cache — consistently redirects this cache too, instead of the two caches
+ * silently splitting across different roots.
+ * @returns Absolute path to the `table` cache directory. The `Cache` class
+ *   creates a further subdirectory under this path named after its `name`
+ *   argument.
+ * @example
+ * ```ts
+ * const cache = new Cache('nitpicker-axe', getTableCacheRoot());
+ * await cache.clear();
+ * ```
+ */
+export function getTableCacheRoot() {
+    return path.join(getArchiveCacheRoot(), 'table');
+}

package/lib/nitpicker.js

@@ -4,6 +4,7 @@ import { Cache } from '@d-zero/shared/cache';
 import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
 import { Archive } from '@nitpicker/crawler';
 import c from 'ansi-colors';
+import { getTableCacheRoot } from './get-table-cache-root.js';
 import { importModules } from './import-modules.js';
 import { loadPluginSettings } from './load-plugin-settings.js';
 import { Table } from './table.js';
@@ -238,7 +239,7 @@ export class Nitpicker extends EventEmitter {
             table.addHeaders(mod.headers);
         }
         const allViolations = [];
-        const cache = new Cache('nitpicker-axe', path.join(os.tmpdir(), 'nitpicker/cache/table'));
+        const cache = new Cache('nitpicker-axe', getTableCacheRoot());
         await cache.clear();
         // Build plugin metadata: lane IDs and display labels
         const eachPagePlugins = [];
@@ -471,7 +472,7 @@ export class Nitpicker extends EventEmitter {
         // phase's outcome.
         if (templateClassificationLaneId != null) {
             try {
-                const templateKeys = await classifyPageTemplates({
+                const classification = await classifyPageTemplates({
                     archive: this.archive,
                     pages: accumulatedPages,
                     // Only worth paying for when there's a lane to update —
@@ -479,16 +480,19 @@ export class Nitpicker extends EventEmitter {
                     // demotes `resolvePageClusterKeys` off its byte-identical,
                     // yield-overhead-free sync path for corpora at or below its
                     // inline threshold (see @d-zero/page-cluster's own docs).
+                    // `classifyPageTemplates` always requests cluster reasons too,
+                    // independent of this — see its own JSDoc for why that no
+                    // longer costs the sync-path demotion this comment warns about.
                     onProgress: lanes
                         ? (event) => {
                             lanes.update(templateClassificationLaneId, `Template classification: ${formatTemplateClassificationProgress(event)}%braille%`);
                         }
                         : undefined,
                 });
-                if (templateKeys.size > 0) {
-                    await this.archive.replacePageTemplates(templateKeys);
+                if (classification.templateKeysByUrl.size > 0) {
+                    await this.archive.replacePageTemplates(classification.templateKeysByUrl, classification.clusterReasonsByTemplateKey);
                 }
-                lanes?.update(templateClassificationLaneId, c.green(`Template classification: Done (${templateKeys.size} pages)`));
+                lanes?.update(templateClassificationLaneId, c.green(`Template classification: Done (${classification.templateKeysByUrl.size} pages)`));
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);

package/lib/template-classification/classify-page-templates.d.ts

@@ -1,24 +1,4 @@
-import type { ProgressEvent } from '@d-zero/page-cluster/resolve-page-cluster-keys';
-import type { Archive, Page } from '@nitpicker/crawler';
-/**
- * Options for {@link classifyPageTemplates}.
- */
-export interface ClassifyPageTemplatesOptions {
-    /** The archive to read pages/stylesheets from and to derive the cache key from. */
-    archive: Archive;
-    /**
-     * All pages already loaded for this `analyze()` run (see
-     * `Nitpicker.analyze`'s accumulation across `getPagesWithRefs` batches —
-     * classification must run once, globally, not per batch).
-     */
-    pages: readonly Page[];
-    /**
-     * Progress callback forwarded to `@d-zero/page-cluster`'s
-     * `resolvePageClusterKeys`, so long-running classification on large
-     * archives isn't silently unresponsive.
-     */
-    onProgress?: (event: ProgressEvent) => void;
-}
+import type { ClassifyPageTemplatesOptions, PageTemplateClassification } from './types.js';
 /**
  * Classifies every internal HTML page in the archive into a template group
  * by DOM-structure similarity, using `@d-zero/page-cluster`.
@@ -50,15 +30,20 @@ export interface ClassifyPageTemplatesOptions {
  * cluster" concept (`@nitpicker/query`'s `compute-isolated-clusters.ts`,
  * link-reachability graph components — a completely different kind of
  * grouping from DOM-structure similarity).
+ *
+ * `onClusterReason` is always passed to `resolvePageClusterKeys` (not made
+ * conditional the way `onProgress` is) — as of `@d-zero/page-cluster` 0.5.3,
+ * requesting cluster reasons no longer forces small corpora off the
+ * progress-emitting path (see that option's own JSDoc), so there is no
+ * responsiveness cost to always capturing them.
  * @param options - See {@link ClassifyPageTemplatesOptions}.
- * @returns Map from page URL (`page.url.href`) to its template key. Only
- *   internal HTML pages with retrievable HTML have an entry.
+ * @returns See {@link PageTemplateClassification}.
  * @example
  * ```ts
- * const templateKeys = await classifyPageTemplates({ archive, pages });
- * for (const [url, templateKey] of templateKeys) {
+ * const { templateKeysByUrl } = await classifyPageTemplates({ archive, pages });
+ * for (const [url, templateKey] of templateKeysByUrl) {
  *   table.addData({ [url]: { templateKey: { value: templateKey } } });
  * }
  * ```
  */
-export declare function classifyPageTemplates(options: ClassifyPageTemplatesOptions): Promise<Map<string, string>>;
+export declare function classifyPageTemplates(options: ClassifyPageTemplatesOptions): Promise<PageTemplateClassification>;

package/lib/template-classification/classify-page-templates.js

@@ -5,6 +5,26 @@ import { resolvePageClusterKeys } from '@d-zero/page-cluster/resolve-page-cluste
 import { Cache } from '@d-zero/shared/cache';
 import { collectPageStylesheetUrls } from './collect-page-stylesheet-urls.js';
 import { createPageClusterFactory } from './create-page-cluster-factory.js';
+/**
+ * Narrows a loaded cache value to the current {@link TemplateClassificationCacheEntry}
+ * shape, so a pre-existing on-disk cache entry from before cluster-reason
+ * capture was added (a bare `Record<string, string>`, no `templateKeys` key)
+ * is treated as a miss instead of being misread as `{ templateKeys: undefined,
+ * clusterReasons: undefined }`. No version counter is used for this — the
+ * structural check is sufficient and avoids a magic number that would need
+ * bumping on every future cache-shape change.
+ * @param value - The value loaded from the persistent cache.
+ */
+function isTemplateClassificationCacheEntry(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.templateKeys === 'object' &&
+        candidate.templateKeys !== null &&
+        typeof candidate.clusterReasons === 'object' &&
+        candidate.clusterReasons !== null);
+}
 /**
  * Classifies every internal HTML page in the archive into a template group
  * by DOM-structure similarity, using `@d-zero/page-cluster`.
@@ -36,13 +56,18 @@ import { createPageClusterFactory } from './create-page-cluster-factory.js';
  * cluster" concept (`@nitpicker/query`'s `compute-isolated-clusters.ts`,
  * link-reachability graph components — a completely different kind of
  * grouping from DOM-structure similarity).
+ *
+ * `onClusterReason` is always passed to `resolvePageClusterKeys` (not made
+ * conditional the way `onProgress` is) — as of `@d-zero/page-cluster` 0.5.3,
+ * requesting cluster reasons no longer forces small corpora off the
+ * progress-emitting path (see that option's own JSDoc), so there is no
+ * responsiveness cost to always capturing them.
  * @param options - See {@link ClassifyPageTemplatesOptions}.
- * @returns Map from page URL (`page.url.href`) to its template key. Only
- *   internal HTML pages with retrievable HTML have an entry.
+ * @returns See {@link PageTemplateClassification}.
  * @example
  * ```ts
- * const templateKeys = await classifyPageTemplates({ archive, pages });
- * for (const [url, templateKey] of templateKeys) {
+ * const { templateKeysByUrl } = await classifyPageTemplates({ archive, pages });
+ * for (const [url, templateKey] of templateKeysByUrl) {
  *   table.addData({ [url]: { templateKey: { value: templateKey } } });
  * }
  * ```
@@ -53,13 +78,22 @@ export async function classifyPageTemplates(options) {
     const cacheKey = await buildArchiveCacheKey(archive.filePath, pages.length);
     if (cacheKey) {
         const cached = await cache.load(cacheKey);
-        if (cached) {
-            return new Map(Object.entries(cached));
+        if (cached && isTemplateClassificationCacheEntry(cached)) {
+            return {
+                templateKeysByUrl: new Map(Object.entries(cached.templateKeys)),
+                clusterReasonsByTemplateKey: new Map(Object.entries(cached.clusterReasons)),
+            };
         }
     }
     const stylesheetsByUrl = await collectPageStylesheetUrls(archive);
     const { factory, getYieldedUrls } = createPageClusterFactory(pages, stylesheetsByUrl);
-    const clusterKeys = await resolvePageClusterKeys(factory, onProgress ? { onProgress } : undefined);
+    const clusterReasonsByTemplateKey = new Map();
+    const clusterKeys = await resolvePageClusterKeys(factory, {
+        ...(onProgress ? { onProgress } : {}),
+        onClusterReason: (clusterKey, reason) => {
+            clusterReasonsByTemplateKey.set(clusterKey, reason);
+        },
+    });
     // Safe only after `resolvePageClusterKeys` has resolved — see
     // `createPageClusterFactory`'s JSDoc for why.
     const yieldedUrls = getYieldedUrls();
@@ -67,17 +101,23 @@ export async function classifyPageTemplates(options) {
         // Would silently mis-map template keys to the wrong URLs if allowed
         // through — see createPageClusterFactory's JSDoc for why this should
         // be structurally impossible, but a loud failure here is far
-        // preferable to a quiet mis-assignment.
+        // preferable to a quiet mis-assignment. No equivalent check exists for
+        // `clusterReasonsByTemplateKey` — see `PageTemplateClassification`'s
+        // own JSDoc for why that map is a best-effort side channel, not a
+        // per-page guarantee.
         throw new Error(`classifyPageTemplates: resolvePageClusterKeys returned ${clusterKeys.length} keys for ${yieldedUrls.length} yielded pages.`);
     }
-    const result = new Map();
+    const templateKeysByUrl = new Map();
     for (const [index, url] of yieldedUrls.entries()) {
-        result.set(url, clusterKeys[index]);
+        templateKeysByUrl.set(url, clusterKeys[index]);
     }
     if (cacheKey) {
-        await cache.store(cacheKey, Object.fromEntries(result));
+        await cache.store(cacheKey, {
+            templateKeys: Object.fromEntries(templateKeysByUrl),
+            clusterReasons: Object.fromEntries(clusterReasonsByTemplateKey),
+        });
     }
-    return result;
+    return { templateKeysByUrl, clusterReasonsByTemplateKey };
 }
 /**
  * Lazily constructs the persistent template-classification cache. Kept as a

package/lib/template-classification/types.d.ts

@@ -0,0 +1,44 @@
+import type { ProgressEvent } from '@d-zero/page-cluster/resolve-page-cluster-keys';
+import type { Archive, Page, TemplateClusterReason } from '@nitpicker/crawler';
+/**
+ * Options for {@link import('./classify-page-templates.js').classifyPageTemplates}.
+ */
+export interface ClassifyPageTemplatesOptions {
+    /** The archive to read pages/stylesheets from and to derive the cache key from. */
+    archive: Archive;
+    /**
+     * All pages already loaded for this `analyze()` run (see
+     * `Nitpicker.analyze`'s accumulation across `getPagesWithRefs` batches —
+     * classification must run once, globally, not per batch).
+     */
+    pages: readonly Page[];
+    /**
+     * Progress callback forwarded to `@d-zero/page-cluster`'s
+     * `resolvePageClusterKeys`, so long-running classification on large
+     * archives isn't silently unresponsive. Independent of cluster-reason
+     * capture — `@d-zero/page-cluster` 0.5.3+ composes `onProgress` and
+     * `onClusterReason` without either one demoting the corpus off its
+     * progress-emitting path (see `classifyPageTemplates`'s own JSDoc).
+     */
+    onProgress?: (event: ProgressEvent) => void;
+}
+/**
+ * Result of {@link import('./classify-page-templates.js').classifyPageTemplates}.
+ */
+export interface PageTemplateClassification {
+    /**
+     * Page URL (`page.url.href`) → template key. Only internal HTML pages
+     * with retrievable HTML have an entry.
+     */
+    readonly templateKeysByUrl: ReadonlyMap<string, string>;
+    /**
+     * Template key → `@d-zero/page-cluster`'s cluster-selection evidence for
+     * that key. **Not guaranteed to cover every key in `templateKeysByUrl`**:
+     * `@d-zero/page-cluster` only emits a reason for a final cluster it still
+     * holds full grouping state for at the moment `onClusterReason` fires,
+     * which is a best-effort side channel rather than a per-page guarantee
+     * (unlike `templateKeysByUrl`, which is verified 1:1 against the yielded
+     * page set — see the hard length check in `classifyPageTemplates`).
+     */
+    readonly clusterReasonsByTemplateKey: ReadonlyMap<string, TemplateClusterReason>;
+}

package/lib/template-classification/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nitpicker/core",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"description": "Plugin-based page analysis engine for Nitpicker",
 	"author": "D-ZERO",
 	"license": "Apache-2.0",
@@ -28,13 +28,13 @@
 	},
 	"dependencies": {
 		"@d-zero/dealer": "1.9.4",
-		"@d-zero/page-cluster": "0.3.1",
+		"@d-zero/page-cluster": "0.5.3",
 		"@d-zero/shared": "0.22.2",
-		"@nitpicker/crawler": "0.14.0",
-		"@nitpicker/types": "0.14.0",
+		"@nitpicker/crawler": "0.15.0",
+		"@nitpicker/types": "0.15.0",
 		"ansi-colors": "4.1.3",
 		"cosmiconfig": "9.0.2",
 		"jsdom": "29.1.1"
 	},
-	"gitHead": "d6e1894a29aa29ca94785d9db0acfc3acc74764b"
+	"gitHead": "d1485df6e43375c6a44edfe07a0293fd39d7810d"
 }