@d-zero/page-cluster 0.4.0 → 0.5.0

package/dist/resolve-page-cluster-keys.js

@@ -1,5 +1,5 @@
 import { autoCutThreshold } from './auto-cut-threshold.js';
-import { buildPageLandmarkReport, } from './build-page-landmark-report.js';
+import { buildClusterReason } from './build-cluster-reason.js';
 import { capContentDepth } from './cap-content-depth.js';
 import { detectContentDepthCap, validateDetectContentDepthCapOptions, } from './detect-content-depth-cap.js';
 import { extractLandmarks } from './extract-landmarks.js';
@@ -9,7 +9,6 @@ import { mergeCrossBlockClusters } from './merge-cross-block-clusters.js';
 import { groupIndicesByBlockKey, resolveBlockKeys } from './pass0-blocking.js';
 import { computePerPageLandmarkInstances } from './per-page-landmark-signatures.js';
 import { removeContentBlocks } from './remove-content-blocks.js';
-import { shellQuorum } from './shell-quorum.js';
 import { stageAPerBlock } from './stage-a-per-block.js';
 import { tokenize } from './tokenize.js';
 /**
@@ -238,37 +237,61 @@ export function computeLocalLandmarkTokens(landmarks, tokenizeOptions) {
     return [...computeLocalChromeArtifacts(landmarks, tokenizeOptions).localTokensByPage];
 }
 /**
- * Builds every page's {@link PageLandmarkReport} for the `includeLandmarkPositions`
- * result path. Groups pages by their *final* cluster key (post–Stage-B), runs
- * {@link ./shell-quorum.js | shellQuorum} once per cluster over the pooled
- * member `PerPageLandmarkInstance`s (the same "shell tokens" concept Stage B
- * itself uses for L2 shell corroboration, just recomputed at the final-
- * cluster granularity rather than the pre-merge unit granularity), then
- * classifies each member page's own landmark instances against that
- * cluster-level shell.
- * @param finalKeys
- * @param landmarks
- * @param perPageInstances
+ * Builds and emits one {@link ClusterReason} per final cluster via
+ * `onClusterReason`, from data Stage A/B already computed for clustering
+ * itself: `crossBlockUnits` (Stage A's pre-merge units, each carrying its
+ * originating block key inside `JSON.parse(unit.key)[0]`), Stage B's
+ * `rootByKey`/`finalGroupsByRoot`, the per-block-key `BlockingReason`s Pass 0
+ * derived, and the per-block sibling-unit-key lists the driver accumulated
+ * alongside its Stage A loop. No re-tokenization and no extra corpus pass —
+ * this only re-groups references the driver already held.
+ * @param crossBlockUnits
+ * @param rootByKey
+ * @param finalGroupsByRoot
+ * @param reasonsByBlockKey
+ * @param siblingUnitKeysByBlock
+ * @param onClusterReason
  */
-function buildLandmarkReportsByCluster(finalKeys, landmarks, perPageInstances) {
-    const indicesByKey = new Map();
-    for (const [i, key] of finalKeys.entries()) {
-        const indices = indicesByKey.get(key);
-        if (indices) {
-            indices.push(i);
+function emitClusterReasons(crossBlockUnits, rootByKey, finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason) {
+    const unitKeysByRoot = new Map();
+    for (const unit of crossBlockUnits) {
+        const root = rootByKey.get(unit.key) ?? unit.key;
+        const list = unitKeysByRoot.get(root);
+        if (list) {
+            list.push(unit.key);
         }
         else {
-            indicesByKey.set(key, [i]);
+            unitKeysByRoot.set(root, [unit.key]);
         }
     }
-    const reports = Array.from({ length: finalKeys.length });
-    for (const indices of indicesByKey.values()) {
-        const shellTokens = shellQuorum(indices.map((i) => perPageInstances[i]));
-        for (const i of indices) {
-            reports[i] = buildPageLandmarkReport(landmarks[i], shellTokens);
+    for (const [rootKey, unitKeys] of unitKeysByRoot) {
+        const finalGroup = finalGroupsByRoot.get(rootKey);
+        if (!finalGroup)
+            continue;
+        const seenBlockKeys = new Set();
+        const blocking = [];
+        const siblingRoots = new Set();
+        for (const unitKey of unitKeys) {
+            const blockKey = JSON.parse(unitKey)[0];
+            if (!seenBlockKeys.has(blockKey)) {
+                seenBlockKeys.add(blockKey);
+                const reason = reasonsByBlockKey.get(blockKey);
+                if (reason)
+                    blocking.push({ blockKey, reason });
+            }
+            for (const siblingUnitKey of siblingUnitKeysByBlock.get(blockKey) ?? []) {
+                const siblingRoot = rootByKey.get(siblingUnitKey) ?? siblingUnitKey;
+                if (siblingRoot !== rootKey)
+                    siblingRoots.add(siblingRoot);
+            }
         }
+        onClusterReason(rootKey, buildClusterReason({
+            tokenSets: finalGroup.tokenSets,
+            landmarkInstances: finalGroup.landmarkInstances,
+            blocking,
+            siblingClusterKeys: [...siblingRoots].toSorted(),
+        }));
     }
-    return reports;
 }
 /**
  * Corpus size at or below which the async factory-based
@@ -292,21 +315,6 @@ function buildLandmarkReportsByCluster(finalKeys, landmarks, perPageInstances) {
  * anything above 20,000 is routed to streaming.
  */
 export const CORPUS_INLINE_THRESHOLD = 20_000;
-/**
- * Throws when `includeLandmarkPositions` is combined with a corpus over
- * `threshold` pages (the streaming path — see `includeLandmarkPositions`'s
- * own JSDoc for why it has no sample-based equivalent there). Split out from
- * its call site so tests can exercise the boundary with a small injected
- * `threshold` instead of constructing a 20,001-page fixture to cross the
- * real {@link CORPUS_INLINE_THRESHOLD}.
- * @param pageCount
- * @param threshold
- */
-export function assertLandmarkPositionsSupportedForPageCount(pageCount, threshold) {
-    if (pageCount > threshold) {
-        throw new RangeError(`resolvePageClusterKeys: includeLandmarkPositions is not supported for corpora larger than ${threshold} pages (the streaming path) — this corpus has ${pageCount}`);
-    }
-}
 /**
  * Reservoir-sample size per block on the streaming path. Blocks larger than
  * this have Stage A run on a random sample of `BLOCK_SAMPLE_SIZE` pages,
@@ -342,6 +350,23 @@ export function assertLandmarkPositionsSupportedForPageCount(pageCount, threshol
  * {@link CORPUS_INLINE_THRESHOLD} — sampling is streaming-mode only.
  */
 export const BLOCK_SAMPLE_SIZE = 100;
+/**
+ * Preserves the previous synchronous, array-in / array-out API of
+ * `resolvePageClusterKeys` under a new name so the factory-based async
+ * export can take the primary name while callers that already had a
+ * materialized page array (spec tests, the in-repo dogfood harness,
+ * downstream code that hasn't switched to streaming yet) retain the
+ * exact same behavior.
+ *
+ * Semantics: identical to the pre-refactor `resolvePageClusterKeys`.
+ * Corpus-wide chrome discovery, Stage B across every page, no memory
+ * bound — meant to be called on inputs already known to fit in memory.
+ * The async factory-based export delegates here whenever
+ * `pages.length ≤ CORPUS_INLINE_THRESHOLD`, guaranteeing existing corpora
+ * hit exactly this code path.
+ * @param pages
+ * @param options
+ */
 export function resolvePageClusterKeysInMemory(pages, options) {
     const excludeLandmarks = options?.excludeLandmarks ?? true;
     const similarityThreshold = options?.similarityThreshold ?? 0.8;
@@ -349,14 +374,9 @@ export function resolvePageClusterKeysInMemory(pages, options) {
         throw new RangeError(`resolvePageClusterKeys: similarityThreshold must be between 0 and 1, got ${similarityThreshold}`);
     }
     // Always computed: landmark fields are needed by Stage B's shell
-    // corroboration regardless of `excludeLandmarks`, and `remainderHtml` is
-    // needed whenever `excludeLandmarks` is true.
+    // corroboration regardless of `excludeLandmarks`.
     const landmarks = pages.map((page) => extractLandmarks(page.html));
-    // Corpus-level chrome discovery. `perPageInstances` is only consumed
-    // below when `includeLandmarkPositions` is set — computed unconditionally
-    // anyway since `computeLocalChromeArtifacts` already builds it internally
-    // for chrome discovery, so exposing it here costs nothing extra.
-    const { localTokensByPage: localLandmarkTokensByPage, perPageInstances } = computeLocalChromeArtifacts(landmarks, options);
+    const { localTokensByPage: localLandmarkTokensByPage } = computeLocalChromeArtifacts(landmarks, options);
     const contentBlockAttribute = options?.contentBlockAttribute;
     const preparedHtml = pages.map((page, index) => {
         const landmarksExcised = excludeLandmarks
@@ -371,7 +391,20 @@ export function resolvePageClusterKeysInMemory(pages, options) {
     const blockingPages = restrictStylesheetsToFirstParty
         ? filterFirstPartyStylesheetHrefs(pages)
         : pages;
-    const blockKeys = resolveBlockKeys(blockingPages, options);
+    // Reasons (blocking evidence) are only worth deriving when a caller
+    // actually asked for `onClusterReason` — see that option's own JSDoc for
+    // why this is the only place ClusterReason bookkeeping is opt-in.
+    const onClusterReason = options?.onClusterReason;
+    let blockKeys;
+    let reasonsByBlockKey;
+    if (onClusterReason) {
+        const result = resolveBlockKeys(blockingPages, { ...options, includeReasons: true });
+        blockKeys = result.blockKeys;
+        reasonsByBlockKey = result.reasonsByBlockKey;
+    }
+    else {
+        blockKeys = resolveBlockKeys(blockingPages, options);
+    }
     const indicesByBlockKey = groupIndicesByBlockKey(blockKeys);
     // Validated here, eagerly, because it's otherwise only reached from
     // inside the per-block loop below — which never runs at all for an empty
@@ -380,6 +413,9 @@ export function resolvePageClusterKeysInMemory(pages, options) {
     validateDetectContentDepthCapOptions(options);
     const finalKeys = Array.from({ length: pages.length });
     const crossBlockUnits = [];
+    const siblingUnitKeysByBlock = onClusterReason
+        ? new Map()
+        : undefined;
     for (const [blockKey, indices] of indicesByBlockKey) {
         const result = stageAPerBlock({
             blockKey,
@@ -392,20 +428,21 @@ export function resolvePageClusterKeysInMemory(pages, options) {
             finalKeys[pageIndex] = key;
         }
         crossBlockUnits.push(...result.crossBlockUnits);
+        siblingUnitKeysByBlock?.set(blockKey, result.crossBlockUnits.map((u) => u.key));
     }
     // Stage B: cross-block merge — always runs regardless of options
-    const stageBResult = mergeCrossBlockClusters(crossBlockUnits, options);
+    const { rootByKey, finalGroupsByRoot } = mergeCrossBlockClusters(crossBlockUnits, options);
     for (let i = 0; i < finalKeys.length; i++) {
         const currentKey = finalKeys[i];
-        const rootKey = stageBResult.get(currentKey);
+        const rootKey = rootByKey.get(currentKey);
         if (rootKey !== undefined && rootKey !== currentKey) {
             finalKeys[i] = rootKey;
         }
     }
-    if (!options?.includeLandmarkPositions)
-        return finalKeys;
-    const reports = buildLandmarkReportsByCluster(finalKeys, landmarks, perPageInstances);
-    return finalKeys.map((clusterKey, i) => ({ clusterKey, landmarks: reports[i] }));
+    if (onClusterReason && reasonsByBlockKey && siblingUnitKeysByBlock) {
+        emitClusterReasons(crossBlockUnits, rootByKey, finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
+    }
+    return finalKeys;
 }
 /**
  * Async twin of {@link ./resolve-page-cluster-keys.js | resolvePageClusterKeysInMemory}
@@ -485,16 +522,58 @@ async function resolveSmallCorpusWithProgress(pages, onProgress, options) {
         await new Promise((resolve) => setImmediate(resolve));
     }
     onProgress({ phase: 'stage-b-start', unitCount: crossBlockUnits.length });
-    const stageBResult = mergeCrossBlockClusters(crossBlockUnits, options);
+    const { rootByKey } = mergeCrossBlockClusters(crossBlockUnits, options);
     for (let i = 0; i < finalKeys.length; i++) {
         const currentKey = finalKeys[i];
-        const rootKey = stageBResult.get(currentKey);
+        const rootKey = rootByKey.get(currentKey);
         if (rootKey !== undefined && rootKey !== currentKey) {
             finalKeys[i] = rootKey;
         }
     }
     return finalKeys;
 }
+/**
+ * Streaming, memory-bounded version of `resolvePageClusterKeysInMemory`.
+ *
+ * ## Behavior gate
+ *
+ * - `pageCount ≤ CORPUS_INLINE_THRESHOLD` — reads the whole factory into an
+ *   array, delegates to `resolvePageClusterKeysInMemory`. Same corpus-wide
+ *   chrome discovery, same Stage B across every page. All previously
+ *   validated corpora (302 / 1,416 / 8,936 / 89 pages) hit this path.
+ * - `pageCount > CORPUS_INLINE_THRESHOLD` — streaming path: reads the
+ *   factory twice (once for blocking signals, once for HTML processing),
+ *   dispatches HTML per block, runs Stage A per block, accumulates
+ *   cross-block units, then runs Stage B across all accumulated units. Peak
+ *   memory ≈ largest single block, not the whole corpus.
+ *
+ * ## Semantic differences in streaming mode
+ *
+ * - **Chrome discovery is per-block, not corpus-wide.** In the in-memory
+ *   path, {@link ./resolve-page-cluster-keys.js | computeLocalLandmarkTokens}
+ *   runs on all pages at once. In streaming mode the entire corpus cannot
+ *   be held at once, so chrome discovery runs per block. A landmark
+ *   signature that is rare corpus-wide but common within one block will
+ *   be treated as global chrome in streaming mode, whereas the in-memory
+ *   mode would treat it as local. This trade-off is why the threshold
+ *   above is set generously — every real corpus historically validated
+ *   here stays on the in-memory path.
+ * @param pages
+ * @param options
+ * @example
+ * ```ts
+ * // JSONL file source — factory can be re-invoked to re-open the file.
+ * import { createReadStream } from 'node:fs';
+ * import readline from 'node:readline';
+ *
+ * const keys = await resolvePageClusterKeys(() => {
+ *   const lines = readline.createInterface({ input: createReadStream('pages.jsonl') });
+ *   return (async function* () {
+ *     for await (const line of lines) yield JSON.parse(line);
+ *   })();
+ * });
+ * ```
+ */
 export async function resolvePageClusterKeys(pages, options) {
     const onProgress = options?.onProgress;
     // Pass 0: HTML-free — collect blocking signals (paths, stylesheetHrefs,
@@ -530,22 +609,17 @@ export async function resolvePageClusterKeys(pages, options) {
         // into per-block progress, so delegate to the untouched sync path —
         // keeping behavior byte-for-byte identical (and yield-overhead-free)
         // to how library-only consumers experienced this before the CLI
-        // progress work landed. `includeLandmarkPositions` always routes here
-        // too (see its own JSDoc): `resolveSmallCorpusWithProgress` has no
-        // landmark-report support, and duplicating that logic into the
+        // progress work landed. `onClusterReason` always routes here too (see
+        // its own JSDoc): `resolveSmallCorpusWithProgress` has no
+        // cluster-reason support, and duplicating that logic into the
         // progress-emitting path for a reporting feature that has nothing to
         // do with progress observability isn't worth the added surface.
-        if (onProgress === undefined || options?.includeLandmarkPositions) {
+        if (onProgress === undefined || options?.onClusterReason) {
             return resolvePageClusterKeysInMemory(fullPages, options);
         }
         return resolveSmallCorpusWithProgress(fullPages, onProgress, options);
     }
-    // Large corpus: streaming path. includeLandmarkPositions has no sample-
-    // based equivalent (see its own JSDoc) — fail fast rather than silently
-    // ignoring the option or returning a semantically-wrong report.
-    if (options?.includeLandmarkPositions) {
-        assertLandmarkPositionsSupportedForPageCount(blockingSignals.length, CORPUS_INLINE_THRESHOLD);
-    }
+    // Large corpus: streaming path.
     const excludeLandmarks = options?.excludeLandmarks ?? true;
     const similarityThreshold = options?.similarityThreshold ?? 0.8;
     if (!(similarityThreshold >= 0 && similarityThreshold <= 1)) {
@@ -556,11 +630,30 @@ export async function resolvePageClusterKeys(pages, options) {
     const blockingPagesForKeys = restrictStylesheetsToFirstParty
         ? filterFirstPartyStylesheetHrefs(blockingSignals)
         : blockingSignals;
-    const blockKeys = resolveBlockKeys(blockingPagesForKeys, options);
+    // Reasons (blocking evidence) cost nothing beyond bookkeeping — a Map
+    // keyed by distinct block key, not by page — but are only derived when a
+    // caller actually asked for `onClusterReason`.
+    const onClusterReason = options?.onClusterReason;
+    let blockKeys;
+    let reasonsByBlockKey;
+    if (onClusterReason) {
+        const result = resolveBlockKeys(blockingPagesForKeys, {
+            ...options,
+            includeReasons: true,
+        });
+        blockKeys = result.blockKeys;
+        reasonsByBlockKey = result.reasonsByBlockKey;
+    }
+    else {
+        blockKeys = resolveBlockKeys(blockingPagesForKeys, options);
+    }
     const indicesByBlockKey = groupIndicesByBlockKey(blockKeys);
     const finalKeys = Array.from({ length: blockingSignals.length });
     const crossBlockUnits = [];
     const contentBlockAttribute = options?.contentBlockAttribute;
+    const siblingUnitKeysByBlock = onClusterReason
+        ? new Map()
+        : undefined;
     /** Non-sample page indices that need Pass 1b Jaccard-based assignment. */
     const pendingAssignmentBlockKeyByIndex = new Map();
     /** Block-level artifacts saved after Stage A runs on the sample. */
@@ -599,6 +692,7 @@ export async function resolvePageClusterKeys(pages, options) {
             finalKeys[idx] = key;
         }
         crossBlockUnits.push(...result.crossBlockUnits);
+        siblingUnitKeysByBlock?.set(bucket.blockKey, result.crossBlockUnits.map((u) => u.key));
         if (bucket.seenCount > bucket.reservoirIndices.length) {
             // Save assignment artifacts for Pass 1b.
             const maxMainDepth = bucket.reservoirPreparedHtml.length > 1
@@ -724,19 +818,38 @@ export async function resolvePageClusterKeys(pages, options) {
     if (onProgress) {
         onProgress({ phase: 'stage-b-start', unitCount: crossBlockUnits.length });
     }
-    const stageBResult = mergeCrossBlockClusters(crossBlockUnits, {
+    const { rootByKey, finalGroupsByRoot } = mergeCrossBlockClusters(crossBlockUnits, {
         ...options,
         capMembers: BLOCK_SAMPLE_SIZE,
     });
     for (let i = 0; i < finalKeys.length; i++) {
         const currentKey = finalKeys[i];
-        const rootKey = stageBResult.get(currentKey);
+        const rootKey = rootByKey.get(currentKey);
         if (rootKey !== undefined && rootKey !== currentKey) {
             finalKeys[i] = rootKey;
         }
     }
+    if (onClusterReason && reasonsByBlockKey && siblingUnitKeysByBlock) {
+        emitClusterReasons(crossBlockUnits, rootByKey, finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
+    }
     return finalKeys;
 }
+/**
+ * Convenience wrapper that runs {@link ./resolve-page-cluster-keys.js | resolvePageClusterKeys}
+ * on a materialized array. Preserves the pre-refactor sync API for callers
+ * that already have all pages in memory, while flowing through the same
+ * async driver so behavior stays consistent across the two entry points.
+ * @param pages
+ * @param options
+ * @example
+ * ```ts
+ * const keys = await resolvePageClusterKeysFromArray([
+ *   { paths: ['news', '1'], stylesheetHrefs: [], html: '<body><article>one</article></body>' },
+ *   { paths: ['news', '2'], stylesheetHrefs: [], html: '<body><article>two</article></body>' },
+ *   { paths: ['about'], stylesheetHrefs: [], html: '<body><section>about</section></body>' },
+ * ]);
+ * ```
+ */
 export function resolvePageClusterKeysFromArray(pages, options) {
     return resolvePageClusterKeys(() => pages, options);
 }

package/dist/shell-quorum.d.ts

@@ -61,10 +61,10 @@ import type { PerPageLandmarkInstance } from './per-page-landmark-signatures.js'
  *
  * Originally private to {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
  * Stage B L2 corroboration; exported from its own module so
- * {@link ./resolve-page-cluster-keys.js | resolvePageClusterKeysInMemory}'s
- * `includeLandmarkPositions` reporting path can run it once per final
- * cluster to classify individual landmark instances as chrome (see
- * {@link ./is-chrome-landmark-instance.js | isChromeLandmarkInstance}).
+ * {@link ./build-cluster-reason.js | buildClusterReason} can run it once per
+ * final cluster, per landmark type, to classify individual landmark
+ * instances as chrome (see {@link ./is-chrome-landmark-instance.js |
+ * isChromeLandmarkInstance}).
  * @param perPageInstances
  */
 export declare function shellQuorum(perPageInstances: readonly (readonly PerPageLandmarkInstance[])[]): ReadonlySet<string>;

package/dist/shell-quorum.js

@@ -70,10 +70,10 @@ const SHELL_QUORUM_FALLBACK_FRACTION = 0.8;
  *
  * Originally private to {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s
  * Stage B L2 corroboration; exported from its own module so
- * {@link ./resolve-page-cluster-keys.js | resolvePageClusterKeysInMemory}'s
- * `includeLandmarkPositions` reporting path can run it once per final
- * cluster to classify individual landmark instances as chrome (see
- * {@link ./is-chrome-landmark-instance.js | isChromeLandmarkInstance}).
+ * {@link ./build-cluster-reason.js | buildClusterReason} can run it once per
+ * final cluster, per landmark type, to classify individual landmark
+ * instances as chrome (see {@link ./is-chrome-landmark-instance.js |
+ * isChromeLandmarkInstance}).
  * @param perPageInstances
  */
 export function shellQuorum(perPageInstances) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/page-cluster",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Clusters crawled HTML pages by DOM-structure similarity — assigns the same key to pages sharing a template, ignoring text content. CLI-first, with library APIs.",
 	"author": "D-ZERO",
 	"license": "MIT",
@@ -24,6 +24,14 @@
 		"./resolve-page-cluster-keys": {
 			"import": "./dist/resolve-page-cluster-keys.js",
 			"types": "./dist/resolve-page-cluster-keys.d.ts"
+		},
+		"./is-chrome-landmark-instance": {
+			"import": "./dist/is-chrome-landmark-instance.js",
+			"types": "./dist/is-chrome-landmark-instance.d.ts"
+		},
+		"./jaccard-similarity": {
+			"import": "./dist/jaccard-similarity.js",
+			"types": "./dist/jaccard-similarity.d.ts"
 		}
 	},
 	"bin": "./dist/cli.js",
@@ -45,5 +53,5 @@
 		"url": "https://github.com/d-zero-dev/tools.git",
 		"directory": "packages/@d-zero/page-cluster"
 	},
-	"gitHead": "2df2273542928b0bd3e4507c161f80a4fffca9e0"
+	"gitHead": "956fa3488d875756ad57fb391bc4822704570f6b"
 }

package/dist/build-page-landmark-report.d.ts

@@ -1,50 +0,0 @@
-import type { ExtractLandmarksResult, LandmarkPosition } from './extract-landmarks.js';
-import type { TokenizeOptions } from './types.js';
-/**
- * A landmark instance's position plus whether
- * {@link ./is-chrome-landmark-instance.js | isChromeLandmarkInstance} judged
- * it shared site/section chrome (`true`) or page-specific content (`false`),
- * against the unit's {@link ./shell-quorum.js | shellQuorum} shell tokens.
- */
-export type ReportedLandmarkInstance = LandmarkPosition & {
-    readonly isChrome: boolean;
-};
-/**
- * Per-page landmark position report built by
- * {@link ./build-page-landmark-report.js | buildPageLandmarkReport}. `main`
- * carries no `isChrome` verdict — it never participates in chrome/shell
- * discovery (see `extractLandmarks`'s "main handling" note) and is always
- * content.
- */
-export type PageLandmarkReport = {
-    header: ReportedLandmarkInstance[];
-    footer: ReportedLandmarkInstance[];
-    nav: ReportedLandmarkInstance[];
-    aside: ReportedLandmarkInstance[];
-    form: ReportedLandmarkInstance[];
-    search: ReportedLandmarkInstance[];
-    main: LandmarkPosition[];
-};
-/**
- * Builds a page's landmark position report: every landmark instance's
- * location, with `header`/`footer`/`nav`/`aside`/`form`/`search` instances
- * additionally classified as chrome or content against `shellTokens`.
- *
- * Reads `landmarks` directly — the full, non-deduplicated instance list
- * `extractLandmarks` produced — rather than going through
- * {@link ./per-page-landmark-signatures.js | computePerPageLandmarkInstances}'s
- * per-page-deduplicated `PerPageLandmarkInstance[]`: that dedupe collapses
- * same-signature instances to one entry, which would silently drop the
- * position of every duplicate instance a position report needs to include.
- * @param landmarks
- * @param shellTokens The unit-level shell token set from
- * {@link ./shell-quorum.js | shellQuorum}, computed once per final cluster
- * and shared across every member page's report.
- * @param tokenizeOptions
- * @example
- * ```ts
- * const shellTokens = shellQuorum(clusterPerPageInstances);
- * const report = buildPageLandmarkReport(extractLandmarks(page.html), shellTokens);
- * ```
- */
-export declare function buildPageLandmarkReport(landmarks: ExtractLandmarksResult, shellTokens: ReadonlySet<string>, tokenizeOptions?: TokenizeOptions): PageLandmarkReport;

package/dist/build-page-landmark-report.js

@@ -1,67 +0,0 @@
-import { isChromeLandmarkInstance } from './is-chrome-landmark-instance.js';
-import { ALL_LANDMARK_TYPES } from './per-page-landmark-signatures.js';
-import { tokenize } from './tokenize.js';
-/**
- * Strips `html` off a {@link LandmarkInstance}, keeping only its position.
- * `buildPageLandmarkReport`'s output is meant to be serialized per page
- * across a whole corpus (the CLI's JSONL output), so the report
- * deliberately excludes each instance's raw HTML to keep that payload from
- * scaling with markup size — callers who also need the HTML already have
- * `ExtractLandmarksResult` in hand.
- * @param instance
- */
-function toPosition(instance) {
-    return {
-        startOffset: instance.startOffset,
-        endOffset: instance.endOffset,
-        startLine: instance.startLine,
-        startColumn: instance.startColumn,
-        endLine: instance.endLine,
-        endColumn: instance.endColumn,
-    };
-}
-/**
- * Builds a page's landmark position report: every landmark instance's
- * location, with `header`/`footer`/`nav`/`aside`/`form`/`search` instances
- * additionally classified as chrome or content against `shellTokens`.
- *
- * Reads `landmarks` directly — the full, non-deduplicated instance list
- * `extractLandmarks` produced — rather than going through
- * {@link ./per-page-landmark-signatures.js | computePerPageLandmarkInstances}'s
- * per-page-deduplicated `PerPageLandmarkInstance[]`: that dedupe collapses
- * same-signature instances to one entry, which would silently drop the
- * position of every duplicate instance a position report needs to include.
- * @param landmarks
- * @param shellTokens The unit-level shell token set from
- * {@link ./shell-quorum.js | shellQuorum}, computed once per final cluster
- * and shared across every member page's report.
- * @param tokenizeOptions
- * @example
- * ```ts
- * const shellTokens = shellQuorum(clusterPerPageInstances);
- * const report = buildPageLandmarkReport(extractLandmarks(page.html), shellTokens);
- * ```
- */
-export function buildPageLandmarkReport(landmarks, shellTokens, tokenizeOptions) {
-    const report = {
-        header: [],
-        footer: [],
-        nav: [],
-        aside: [],
-        form: [],
-        search: [],
-        main: landmarks.main.map(toPosition),
-    };
-    for (const type of ALL_LANDMARK_TYPES) {
-        for (const instance of landmarks[type]) {
-            const tokens = instance.html
-                ? new Set(tokenize(`<body>${instance.html}</body>`, tokenizeOptions).tokens)
-                : new Set();
-            report[type].push({
-                ...toPosition(instance),
-                isChrome: isChromeLandmarkInstance(tokens, shellTokens),
-            });
-        }
-    }
-    return report;
-}