@nitpicker/core 0.23.1 → 0.25.0

package/lib/types.d.ts

@@ -1,306 +1,794 @@
-import type { Lanes } from '@d-zero/dealer';
-import type { ExURL as URL } from '@d-zero/shared/parse-url';
-import type { TableValue, Violation } from '@nitpicker/types';
-import type { DOMWindow } from 'jsdom';
 /**
- * Represents a single analyze plugin loaded from the user's configuration.
- *
- * Each plugin corresponds to an npm module that exports a {@link PluginFactory}
- * factory function as its default export. The `settings` object is passed
- * through to that factory at initialization time.
- * @see {@link ./load-plugin-settings.ts} for how plugins are discovered from cosmiconfig
- * @see {@link ./import-modules.ts} for how plugins are dynamically imported
+ * The functions the native addon (`crates/nitpicker_napi`) exports, as seen
+ * from JavaScript. Kept in sync with the `#[napi]` functions by hand — the
+ * addon's own generated typings are not used, so every export goes through a
+ * documented one-function-per-file wrapper instead.
+ */
+export interface NativeBinding {
+    /** See `compute-body-hash.ts`. */
+    computeBodyHash(html: Uint8Array): Buffer;
+    /** See `match-structural-technology-signals.ts`. */
+    matchStructuralTechnologySignals(html: Uint8Array): StructuralTechnologySignal[];
+    /** See `match-js-license-comment-signal.ts`. */
+    matchJsLicenseCommentSignal(script: Uint8Array): StructuralTechnologySignal | null;
+    /** See `match-selector-html.ts`. */
+    matchSelectorHtml(plan: NativeSelectorPlan, html: Uint8Array): HtmlMatchOutcome;
+    /** See `match-selector-snapshots.ts`. */
+    matchSelectorSnapshots(plan: NativeSelectorPlan, bodies: Uint8Array, offsets: Uint32Array, codecs: Uint8Array, maxDecodedBytes: number, cancelToken?: NativeCancelToken): Promise<Uint8Array>;
+    /** See `validate-search-pattern.ts`. */
+    validateSearchPattern(pattern: NativeSearchPattern): boolean;
+    /** See `search-html-document.ts`. */
+    searchHtmlDocument(pattern: NativeSearchPattern, html: Uint8Array, snippetLength: number): SnapshotSearchOutcome;
+    /** See `search-html-snapshots.ts`. */
+    searchHtmlSnapshots(pattern: NativeSearchPattern, snippetLength: number, bodies: Uint8Array, offsets: Uint32Array, codecs: Uint8Array, maxDecodedBytes: number, cancelToken?: NativeCancelToken): Promise<{
+        matchCounts: number[];
+        snippets: string[];
+    }>;
+    /** See `check-native-executor-config.ts`. */
+    checkNativeExecutorConfig(): void;
+    /** See `run-with-signal.ts`. */
+    NativeCancelToken: new () => NativeCancelToken;
+    /** See `compute-url-sort-ranks.ts`. */
+    computeUrlSortRanks(urls: Uint8Array, offsets: Uint32Array): Uint32Array;
+    /** See `compute-alias-keys.ts`. */
+    computeAliasKeys(url: string): {
+        tierA: string;
+        tierB: string;
+    } | null;
+    /** See `group-alias-candidates.ts`. */
+    groupAliasCandidates(input: NativeAliasCandidates): Uint32Array;
+    /** See `create-isolated-cluster-run.ts`. */
+    IsolatedClusterRun: new (candidateIds: Uint32Array, redirects: Uint32Array) => NativeIsolatedClusterRun;
+    /** See `create-template-classification-run.ts`. */
+    TemplateClassificationRun: new (onProgress?: (event: NativeTemplateClassificationProgress) => void, memoryBudget?: number) => NativeTemplateClassificationRun;
+    /** See `template-block-sample-size.ts`. */
+    TEMPLATE_BLOCK_SAMPLE_SIZE: number;
+    /** See `template-memory-budget.ts`. */
+    TEMPLATE_MEMORY_BUDGET: number;
+    /** See `template-exact-page-limit.ts`. */
+    TEMPLATE_EXACT_PAGE_LIMIT: number;
+    /** See `max-decoded-snapshot-bytes.ts`. */
+    MAX_DECODED_SNAPSHOT_BYTES: number;
+}
+/**
+ * Stops the asynchronous native calls it was passed to. Raising it is one-way;
+ * a call that sees it raised rejects with code `Cancelled`.
  */
-export interface Plugin {
+export interface NativeCancelToken {
+    /** Raises the token. */
+    cancel(): void;
+}
+/** How two adjacent compounds of a complex selector are joined. */
+export type SelectorCombinator = 'descendant' | 'child';
+/** The attribute selector operators the matcher evaluates. */
+export type SelectorAttributeOperator = 'exists' | 'equals' | 'includes' | 'dash' | 'prefix' | 'suffix' | 'substring';
+/** One attribute condition of a compound (`[a]`, `[a^=v]`, `.cls`, `#id`, ...). */
+export interface SelectorAttributeTest {
+    /** Lower-cased attribute name. */
+    readonly name: string;
+    readonly operator: SelectorAttributeOperator;
+    /** The selector's literal value (empty for `exists`). */
+    readonly value: string;
+    /** Whether values compare ignoring ASCII case. */
+    readonly ignoreCase: boolean;
+}
+/** An `An+B` position test (`:nth-child`, `:nth-of-type`, `:first-*`). */
+export interface SelectorNthTest {
+    readonly kind: 'child' | 'of-type';
+    readonly a: number;
+    readonly b: number;
+}
+/** The compound inside `:not(...)` — a compound without negations of its own. */
+export interface SelectorNegatedCompound {
+    /** Lower-cased tag name, or `null` for any element. */
+    readonly tag: string | null;
+    readonly attributes: readonly SelectorAttributeTest[];
+    readonly nth: readonly SelectorNthTest[];
+}
+/** A compound selector: every condition must hold on one element. */
+export interface SelectorCompound extends SelectorNegatedCompound {
+    readonly negations: readonly SelectorNegatedCompound[];
+}
+/** One comma alternative of a selector list. */
+export interface SelectorAlternative {
+    /** Compounds in source (ancestor-first) order; between 1 and 30. */
+    readonly compounds: readonly SelectorCompound[];
+    /** `combinators[j - 1]` joins `compounds[j - 1]` and `compounds[j]`. */
+    readonly combinators: readonly SelectorCombinator[];
     /**
-     * Human-readable plugin name. Currently unused at runtime but kept
-     * for backward compatibility with older config formats.
-     * @deprecated Use `module` to identify plugins instead.
+     * Lower-cased printable-ASCII literals that must occur in the document in
+     * this order for the alternative to match, or `null` when none can be derived.
      */
-    name: string;
+    readonly prefilterLiterals: readonly string[] | null;
     /**
-     * The npm module specifier to `import()` (e.g. `"@nitpicker/analyze-axe"`).
+     * Whether one start tag decides this alternative: a single compound with
+     * no position test whose attribute values have a single stored form.
      */
-    module: string;
+    readonly direct: boolean;
+}
+/** A validated selector list as the matcher evaluates it. */
+export interface SelectorPlan {
+    readonly alternatives: readonly SelectorAlternative[];
+    /** Whether any alternative tests `:nth-child` / `:first-child`. */
+    readonly needsChildIndex: boolean;
+    /** Whether any alternative tests `:nth-of-type` / `:first-of-type`. */
+    readonly needsTypeIndex: boolean;
+}
+/** {@link SelectorNegatedCompound} as the native conversion reads it: no tag is absent, not `null`. */
+export interface NativeSelectorConditions {
+    readonly tag?: string;
+    readonly attributes: readonly SelectorAttributeTest[];
+    readonly nth: readonly SelectorNthTest[];
+}
+/** {@link SelectorPlan} as the native conversion reads it (see `to-native-selector-plan.ts`). */
+export interface NativeSelectorPlan {
+    readonly alternatives: readonly {
+        readonly compounds: readonly (NativeSelectorConditions & {
+            readonly negations: readonly NativeSelectorConditions[];
+        })[];
+        readonly combinators: readonly SelectorCombinator[];
+        readonly prefilterLiterals?: readonly string[];
+        readonly direct: boolean;
+    }[];
+    readonly needsChildIndex: boolean;
+    readonly needsTypeIndex: boolean;
+}
+/** The verdict on one document and which stages produced it. */
+export interface HtmlMatchOutcome {
+    /** Whether an element of the document matches the selector list. */
+    readonly matched: boolean;
+    /** The ordered-literal prefilter rejected the document; its markup was never read. */
+    readonly prefiltered: boolean;
+    /** The open-element stack ran over the document. */
+    readonly tokenized: boolean;
+    /** Elements the stack tested (zero when it did not run). */
+    readonly elementsVisited: number;
+}
+/** One stored HTML snapshot as it sits in `page_html_blobs`. */
+export interface StoredHtmlSnapshot {
+    /** The stored bytes. */
+    readonly body: Uint8Array;
+    /** `page_html_blobs.codec`: `zstd` or `none`; anything else is rejected. */
+    readonly codec: string;
+}
+/**
+ * What `query search-html` looks for: a literal substring or a regular
+ * expression (Rust `regex` syntax) with its flags.
+ */
+export interface NativeSearchPattern {
+    /** The literal text, or the regular expression's source. */
+    readonly source: string;
+    /** Match `source` as plain text; the flags are then ignored. */
+    readonly literal: boolean;
+    /** `i`. */
+    readonly ignoreCase: boolean;
+    /** `m`: `^` and `$` match at every `\n`. */
+    readonly multiLine: boolean;
+    /** `s`: `.` matches `\n` too. */
+    readonly dotAll: boolean;
+}
+/** What a search found in one document. */
+export interface SnapshotSearchOutcome {
+    /** Non-overlapping matches; 0 when the document does not match. */
+    readonly matchCount: number;
+    /** Whitespace-collapsed window around the first match; empty when there is none. */
+    readonly snippet: string;
+}
+/** The verdict on one snapshot of a batch. */
+export interface SnapshotMatchOutcome {
+    readonly matched: boolean;
+    /** The ordered-literal prefilter rejected the document; its markup was never read. */
+    readonly prefiltered: boolean;
+    /** The open-element stack ran over the document. */
+    readonly tokenized: boolean;
+}
+/**
+ * How a structural technology signal was found: a marker element or
+ * attribute in the HTML, a framework's URL path fragment, a scoped-style
+ * attribute convention, a marker too generic to count for much on its own,
+ * or a license banner at the top of a JS file.
+ */
+export type StructuralTechnologySignalType = 'html-marker' | 'url-pattern' | 'scoped-attr' | 'weak-marker' | 'js-license-comment';
+/**
+ * One structural fingerprint definition (in `crates/nitpicker_tech_detect`)
+ * that matched, with the evidence cut from its first match.
+ */
+export interface StructuralTechnologySignal {
+    /** Normalized technology name (`'Next.js'`, `'Vue'`, ...). */
+    readonly technology: string;
+    readonly signalType: StructuralTechnologySignalType;
+    /** The first match, cut to 200 UTF-16 code units. */
+    readonly evidence: string;
+    /** The definition's confidence in isolation, 0-100. */
+    readonly weight: number;
+    /** The category attached to the technology when only this signal fired. */
+    readonly category: string;
+}
+/**
+ * The addon's run, which `createTemplateClassificationRun` wraps into a
+ * {@link TemplateClassificationRun}; use that instead. Each computing call
+ * resolves with the number of progress events it sent, which may still be on
+ * their way to the callback (the wrapper waits for them). A panic in the
+ * addon or a poisoned lock rejects the call with a generic failure; neither
+ * can be provoked from JavaScript, so no test exercises them.
+ * @example
+ * ```ts
+ * const native = new nativeBinding.TemplateClassificationRun();
+ * native.pushSignals([{ paths: ['a'], stylesheetHrefs: [], stylesheetHosts: [] }]);
+ * const sent = await native.block(); // 0
+ * ```
+ */
+export interface NativeTemplateClassificationRun {
     /**
-     * Absolute path to the configuration file where this plugin was declared.
-     * Passed to the plugin so it can resolve relative paths in its own config.
+     * {@link TemplateClassificationRun.pushSignals}, each stylesheet href's
+     * `new URL(href).host` (`null` where it throws) given alongside.
      */
-    configFilePath: string;
+    pushSignals(signals: readonly NativeTemplatePageSignals[]): void;
+    /** {@link TemplateClassificationRun.block}, resolving with the events sent. */
+    block(): Promise<number>;
+    /** {@link TemplateClassificationRun.pushPages}, resolving with the events sent. */
+    pushPages(pages: readonly TemplatePageHtml[]): Promise<number>;
+    /** {@link TemplateClassificationRun.finishPages}, resolving with the events sent. */
+    finishPages(): Promise<number>;
+    /** {@link TemplateClassificationRun.pageMask}; throws while a call runs. */
+    pageMask(): Uint8Array;
+    /** {@link TemplateClassificationRun.needsAssignment}; throws while a call runs. */
+    needsAssignment(): boolean;
+    /** {@link TemplateClassificationRun.pushAssignmentPages}, resolving with the events sent. */
+    pushAssignmentPages(pages: readonly TemplatePageHtml[]): Promise<number>;
+    /** {@link TemplateClassificationRun.takeOutput}, with the events sent. */
+    takeOutput(): Promise<{
+        readonly output: NativeTemplateClassificationOutput;
+        readonly sent: number;
+    }>;
+    /** {@link TemplateClassificationRun.cancel}. */
+    cancel(): void;
+}
+/**
+ * {@link TemplatePageSignals} as the addon takes it.
+ * @example
+ * ```ts
+ * const signals: NativeTemplatePageSignals = {
+ * 	paths: ['news', '1'],
+ * 	stylesheetHrefs: ['https://example.com/a.css', 'not a url'],
+ * 	stylesheetHosts: ['example.com', null],
+ * };
+ * ```
+ */
+export interface NativeTemplatePageSignals {
+    readonly paths: readonly string[];
+    readonly stylesheetHrefs: readonly string[];
+    /** `new URL(href).host` of each of `stylesheetHrefs`, `null` where it throws. */
+    readonly stylesheetHosts: readonly (string | null)[];
+    readonly host?: string;
+}
+/**
+ * {@link TemplateClassificationProgress} as the addon reports it, every
+ * field optional; `createTemplateClassificationRun` narrows it.
+ * @example
+ * ```ts
+ * const event: NativeTemplateClassificationProgress = { phase: 'stage-b-start', unitCount: 42 };
+ * ```
+ */
+export interface NativeTemplateClassificationProgress {
+    readonly phase: string;
+    readonly blockKey?: string;
+    readonly blocksProcessed?: number;
+    readonly totalBlocks?: number;
+    readonly pagesAssigned?: number;
+    readonly pagesToAssign?: number;
+    readonly unitCount?: number;
+    readonly pageCount?: number;
+    readonly pairBytes?: number;
+    readonly budget?: number;
+    readonly reason?: string;
+}
+/**
+ * {@link TemplateClassificationOutput} as the addon returns it: the reasons
+ * flattened, which `createTemplateClassificationRun` turns into
+ * {@link TemplateClusterReason}s.
+ * @example
+ * ```ts
+ * const { keys, keyOfPage, reasons } = (await native.takeOutput()).output;
+ * ```
+ */
+export interface NativeTemplateClassificationOutput {
+    readonly keys: string[];
+    readonly keyOfPage: Uint32Array;
+    readonly reasons: readonly {
+        readonly clusterKey: string;
+        readonly memberCount: number;
+        readonly blocking: readonly {
+            readonly blockKey: string;
+            readonly kind: string;
+            readonly distinctiveStylesheetHrefs?: readonly string[];
+            readonly pathKey?: string;
+        }[];
+        readonly structuralCoreTokens: readonly string[];
+        readonly landmarks: readonly ({
+            readonly type: string;
+        } & TemplateLandmarkProfile)[];
+        readonly siblingClusterKeys: readonly string[];
+    }[];
+    readonly sampledBlocks: readonly {
+        readonly blockKey: string;
+        readonly pageCount: number;
+        readonly pairBytes: number;
+        readonly reason: string;
+    }[];
+}
+/**
+ * The element a crawler reported as a page's main content: the element whose
+ * subtree holds the page-specific content and under which the classifier
+ * caps the nesting depth it compares. Every given field must match the same
+ * element; empty strings and lists count as not given, and a hint with
+ * nothing given matches nothing (otherwise the shallowest element of the
+ * page would win and the cap would silently apply to the wrong node).
+ *
+ * A structured object rather than a CSS selector string: nothing has to be
+ * parsed (the HTML parser already exposes `id`/`class`/`role`), it maps 1:1
+ * onto the columns a crawler records for its detected main-content element,
+ * and a crawler's own selector string is diagnostic (tag + id + classes) and
+ * not guaranteed to be unique, so it is the wrong thing to re-parse.
+ * @example
+ * ```ts
+ * const hint: ContentRootHint = { tagName: 'DIV', id: 'content', classList: ['l-main'] };
+ * ```
+ */
+export interface ContentRootHint {
+    /** Compared case-insensitively. */
+    readonly tagName?: string;
+    readonly id?: string;
+    readonly role?: string;
+    /** Every listed class must be on the element. */
+    readonly classList?: readonly string[];
+}
+/**
+ * What Pass 0 reads of one page handed to a
+ * {@link TemplateClassificationRun}: no HTML, a few hundred bytes.
+ * @example
+ * ```ts
+ * const signals: TemplatePageSignals = {
+ * 	paths: ['news', '1'],
+ * 	stylesheetHrefs: ['https://example.com/a.css'],
+ * 	host: 'example.com',
+ * };
+ * ```
+ */
+export interface TemplatePageSignals {
+    /** The page URL's path segments; a directory-style URL ends in `''`. */
+    readonly paths: readonly string[];
+    /** Absolute hrefs of the page's stylesheets, in document order. */
+    readonly stylesheetHrefs: readonly string[];
     /**
-     * Plugin-specific settings object parsed from the config file.
-     * The shape is determined by the plugin itself (e.g. `{ lang: "ja" }` for axe).
+     * The page URL's host (`new URL(pageUrl).host`). Stylesheets on other
+     * hosts are left out of blocking; a page without it is judged against
+     * the host most pages load stylesheets from.
      */
-    settings?: unknown;
+    readonly host?: string;
 }
 /**
- * Options for {@link ../nitpicker.ts!Nitpicker.analyze}.
- *
- * Allows callers to provide an external {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}
- * instance for rich progress display, and a verbose flag for non-TTY environments.
+ * One page's HTML handed to a {@link TemplateClassificationRun}.
+ * @example
+ * ```ts
+ * const page: TemplatePageHtml = { html: '<body><main>…</main></body>', contentRoot: { tagName: 'main' } };
+ * ```
  */
-export interface AnalyzeOptions {
-    /** Lanes instance for per-plugin progress display. If omitted, no progress is shown. */
-    readonly lanes?: Lanes;
-    /** When `true`, outputs plain-text progress lines instead of animated Lanes. */
-    readonly verbose?: boolean;
+export interface TemplatePageHtml {
+    readonly html: string;
+    readonly contentRoot?: ContentRootHint;
 }
 /**
- * CLI-specified overrides for individual plugin settings.
- *
- * These values are provided via CLI flags (e.g. `--search-keywords`,
- * `--axe-lang`) and take precedence over settings loaded from the
- * configuration file. Each key maps to a known `@nitpicker/analyze-*`
- * plugin module name, and the value is a partial settings object that
- * will be shallow-merged into the plugin's config-file settings.
- *
- * ## Adding CLI overrides for a new plugin
- *
- * 1. Add a property to this interface with the plugin module name as key
- * 2. Add corresponding CLI flag(s) to `commandDef.flags` in `@nitpicker/cli/src/commands/analyze.ts`
- * 3. Add flag-to-override mapping in `@nitpicker/cli/src/analyze/build-plugin-overrides.ts`
- * 4. Update `README.md` analyze options table
- * @see {@link ./load-plugin-settings.ts!loadPluginSettings} for the merge logic
+ * Progress of a {@link TemplateClassificationRun}: a block will be clustered
+ * from a sample (over the memory budget, or among the largest when the
+ * blocks clustered whole would hold too many pages), a block's clusters are done,
+ * another thousand pages outside the samples were assigned, or the merge
+ * across blocks began.
+ * @example
+ * ```ts
+ * const onProgress = (event: TemplateClassificationProgress) => {
+ * 	if (event.phase === 'pass1-block-complete') {
+ * 		console.log(`${event.blocksProcessed}/${event.totalBlocks} blocks`);
+ * 	}
+ * };
+ * ```
  */
-export interface PluginOverrides {
-    /** Overrides for `@nitpicker/analyze-search` plugin settings. */
-    '@nitpicker/analyze-search'?: {
-        /** Keywords to search for in page content. */
-        keywords?: string[];
-        /** CSS selector to narrow the search scope. */
-        scope?: string;
-    };
-    /** Overrides for `@nitpicker/analyze-axe` plugin settings. */
-    '@nitpicker/analyze-axe'?: {
-        /** BCP 47 language tag for locale. */
-        lang?: string;
+export type TemplateClassificationProgress = {
+    readonly phase: 'block-sampled';
+    readonly blockKey: string;
+    readonly pageCount: number;
+    readonly pairBytes: number;
+    readonly budget: number;
+    readonly reason: TemplateSampleReason;
+} | {
+    readonly phase: 'pass1-block-complete';
+    readonly blockKey: string;
+    readonly blocksProcessed: number;
+    readonly totalBlocks: number;
+} | {
+    readonly phase: 'pass1b-assign';
+    readonly pagesAssigned: number;
+    readonly pagesToAssign: number;
+} | {
+    readonly phase: 'stage-b-start';
+    readonly unitCount: number;
+};
+/**
+ * Why Pass 0 formed a block: its pages share a distinctive set of
+ * stylesheets (`css`), or fall back to their URL section (`path`), or are
+ * pages without stylesheets gathered into their section's stylesheet block
+ * (`orphanMerge`).
+ * @example
+ * ```ts
+ * const reason: TemplateBlockingReason = { kind: 'path', pathKey: 'news' };
+ * ```
+ */
+export type TemplateBlockingReason = {
+    readonly kind: 'css';
+    readonly distinctiveStylesheetHrefs: readonly string[];
+} | {
+    readonly kind: 'path';
+    readonly pathKey: string;
+} | {
+    readonly kind: 'orphanMerge';
+    readonly pathKey: string;
+};
+/**
+ * A page region the classifier treats as chrome: HTML5 sectioning elements
+ * and their ARIA landmark roles (`<header>` / `banner`, `<footer>` /
+ * `contentinfo`, `<nav>` / `navigation`, `<aside>` / `complementary`,
+ * `role="form"`, `<search>` / `search`). `main` is content and never one.
+ * @example
+ * ```ts
+ * const type: TemplateLandmarkType = 'footer';
+ * ```
+ */
+export type TemplateLandmarkType = 'header' | 'footer' | 'nav' | 'aside' | 'form' | 'search';
+/**
+ * What `createTemplateClassificationRun`'s progress callback shares with the
+ * run: the delivery counts, the waiting call, the run's failure, and the
+ * addon's run only through a `WeakRef`. Kept apart from the run's methods so
+ * the callback, which the addon holds while the run lives, does not hold the
+ * run strongly.
+ * @example
+ * ```ts
+ * const state: TemplateClassificationProgressState = {
+ * 	delivered: 0,
+ * 	expected: 0,
+ * 	onDelivered: undefined,
+ * 	failure: undefined,
+ * 	nativeRef: undefined,
+ * };
+ * ```
+ */
+export interface TemplateClassificationProgressState {
+    /** Events the callback received. */
+    delivered: number;
+    /** Events the finished calls said they sent. */
+    expected: number;
+    /** Wakes the call waiting for its events, if one is. */
+    onDelivered: (() => void) | undefined;
+    /** The error that failed the run, once one did. */
+    failure: {
+        readonly error: unknown;
+    } | undefined;
+    /** The addon's run, to cancel when the caller's callback throws. */
+    nativeRef: WeakRef<NativeTemplateClassificationRun> | undefined;
+}
+/**
+ * How common one landmark type is across a cluster's member pages.
+ * @example
+ * ```ts
+ * const footer: TemplateLandmarkProfile = {
+ * 	presenceRate: 1,
+ * 	chromeRate: 1,
+ * 	shellTokens: ['footer>p'],
+ * 	memberCountWithInstance: 12,
+ * };
+ * ```
+ */
+export interface TemplateLandmarkProfile {
+    /** Fraction of the member pages carrying the type. */
+    readonly presenceRate: number;
+    /** Fraction of the type's instances that match the cluster's shell for it. */
+    readonly chromeRate: number;
+    /** The cluster's shell tokens for the type, in UTF-16 order. */
+    readonly shellTokens: readonly string[];
+    /** Member pages carrying the type. */
+    readonly memberCountWithInstance: number;
+}
+/**
+ * Why a final cluster's pages sit together: evidence, no verdicts. Its
+ * shape — key order included — is what `@nitpicker/archive` stores as JSON,
+ * so the stored bytes follow from it.
+ * @example
+ * ```ts
+ * const reason: TemplateClusterReason = {
+ * 	memberCount: 2,
+ * 	blocking: [{ blockKey: 'path:news', reason: { kind: 'path', pathKey: 'news' } }],
+ * 	structuralCoreTokens: ['article', 'body'],
+ * 	landmarks: {},
+ * 	siblingClusterKeys: [],
+ * };
+ * ```
+ */
+export interface TemplateClusterReason {
+    /** Its member pages (the sampled ones, for a block clustered from a sample). */
+    readonly memberCount: number;
+    /** Each Pass-0 block it came from, with the reason the block was formed. */
+    readonly blocking: readonly {
+        readonly blockKey: string;
+        readonly reason: TemplateBlockingReason;
+    }[];
+    /** The structure most of its pages share, in UTF-16 order. */
+    readonly structuralCoreTokens: readonly string[];
+    /** Per landmark type its members carry; absent types are left out. */
+    readonly landmarks: {
+        readonly [Type in TemplateLandmarkType]?: TemplateLandmarkProfile;
     };
+    /** The other final clusters of its blocks, in UTF-16 order. */
+    readonly siblingClusterKeys: readonly string[];
 }
 /**
- * Internal configuration model used by {@link ../nitpicker.ts!Nitpicker}.
- *
- * Built by {@link ./load-plugin-settings.ts!loadPluginSettings} from the
- * user's cosmiconfig file (e.g. `.nitpickerrc.json`). The external config
- * format (`ConfigJSON` from `@nitpicker/types`) uses a `plugins.analyze`
- * object keyed by module name; this internal type normalizes it into an
- * ordered array of fully-resolved {@link Plugin} entries.
+ * Why a block is clustered from a sample of its pages: its Stage A
+ * similarity table would exceed the memory budget (`table-over-budget`), or
+ * the blocks clustered whole would hold more than
+ * `TEMPLATE_EXACT_PAGE_LIMIT` pages and this one is among the largest
+ * (`pages-over-limit`).
+ * @example
+ * ```ts
+ * const reason: TemplateSampleReason = 'pages-over-limit';
+ * ```
+ */
+export type TemplateSampleReason = 'table-over-budget' | 'pages-over-limit';
+/**
+ * A block clustered from a sample of its pages; see
+ * {@link TemplateSampleReason} for why.
+ * @example
+ * ```ts
+ * const block: TemplateSampledBlock = {
+ * 	blockKey: 'path:news',
+ * 	pageCount: 30_000,
+ * 	pairBytes: 3_599_880_000,
+ * 	reason: 'table-over-budget',
+ * };
+ * ```
  */
-export interface Config {
-    /** Ordered list of analyze plugins to execute. */
-    analyze: Plugin[];
+export interface TemplateSampledBlock {
+    /** The block's key. */
+    readonly blockKey: string;
+    /** Its pages. */
+    readonly pageCount: number;
+    /** Bytes its similarity table would have taken. */
+    readonly pairBytes: number;
+    /** Why it was sampled. */
+    readonly reason: TemplateSampleReason;
 }
 /**
- * The runtime interface that every analyze plugin must satisfy after
- * its factory function ({@link PluginFactory}) has been invoked.
- *
- * A plugin may implement one or both callback methods:
- *
- * - **`eachPage`** - Runs inside a Worker thread with full JSDOM access.
- *   Best for DOM-dependent analysis (markup validation, text linting,
- *   accessibility checks). Each invocation receives a parsed `DOMWindow`,
- *   so plugins can use standard DOM APIs without additional parsing.
+ * What a {@link TemplateClassificationRun} produces.
+ * @example
+ * ```ts
+ * const { keys, keyOfPage, reasons } = await run.takeOutput();
+ * const keyOfFirstPage = keys[keyOfPage[0]!]!; // '["path:news","cluster:0"]'
+ * reasons.get(keyOfFirstPage)?.memberCount;
+ * ```
+ */
+export interface TemplateClassificationOutput {
+    /** Every final cluster key (`JSON.stringify([blockKey, "cluster:N"])`). */
+    readonly keys: string[];
+    /** Each page's key, as an index into `keys`. */
+    readonly keyOfPage: Uint32Array;
+    /** Each final cluster's reason, by key. */
+    readonly reasons: ReadonlyMap<string, TemplateClusterReason>;
+    /** The blocks clustered from a sample, in block order; empty when none was. */
+    readonly sampledBlocks: readonly TemplateSampledBlock[];
+}
+/**
+ * One template classification run, executing on the addon's thread pool.
+ * The caller reads the corpus: every page's signals (`pushSignals`), then
+ * `block()`, then every page's HTML in the same order (`pushPages`,
+ * `finishPages`), and, when `needsAssignment()`, once more
+ * (`pushAssignmentPages`); `takeOutput()` merges and returns the result.
  *
- * - **`eachUrl`** - Runs in the main thread, receives only the URL and
- *   external/internal flag. Suited for lightweight, network-based checks
- *   (e.g. link validation, SEO URL pattern checks).
- * @template T - String literal union of the column keys this plugin
- *   contributes to the report table (e.g. `'title' | 'description'`).
- * @see {@link ./page-analysis-worker.ts} for how `eachPage` is called inside the worker
- * @see {@link ./nitpicker.ts} for how `eachUrl` is called from the main thread
+ * Calls must not overlap: await each before the next (an overlapping call
+ * rejects and leaves the running one alone). A promise resolves only after
+ * every progress event of its call was delivered. A call that rejects —
+ * cancelled, a protocol error, or `onProgress` threw (which also cancels the
+ * run) — fails the run: every later call rejects with the same error, and no
+ * further progress is reported.
+ * @example
+ * ```ts
+ * const run = createTemplateClassificationRun();
+ * run.pushSignals([{ paths: ['a'], stylesheetHrefs: [] }]);
+ * await run.block();
+ * await run.pushPages([{ html: '<body></body>' }]);
+ * await run.finishPages();
+ * const output = await run.takeOutput();
+ * ```
  */
-export interface AnalyzePlugin<T extends string = string> {
-    /**
-     * Human-readable display label for interactive prompts.
-     * Shown instead of the raw package name (e.g. `"axe: アクセシビリティチェック"`).
-     */
-    label?: string;
+export interface TemplateClassificationRun {
+    /** Adds the next pages' signals, in corpus order. */
+    pushSignals(signals: readonly TemplatePageSignals[]): void;
+    /** Splits the pages into blocks (Pass 0); the HTML reads follow. */
+    block(): Promise<void>;
+    /** Reads the next pages' HTML, in corpus order. */
+    pushPages(pages: readonly TemplatePageHtml[]): Promise<void>;
+    /** Ends the first read; the blocks clustered whole are clustered here. */
+    finishPages(): Promise<void>;
     /**
-     * Maximum number of pages this plugin processes in parallel.
-     *
-     * Each plugin is allocated its own {@link ../worker/worker-pool.ts!WorkerPool}
-     * sized to this value. Heavy plugins (e.g. one that spawns a
-     * full Chrome instance per page) should set a small number; lightweight
-     * DOM-only plugins can leave it unset.
-     *
-     * When omitted, the orchestrator falls back to `os.cpus().length`.
+     * Which pages the current read uses (`1`): on the first read every page of
+     * a block clustered whole and the sampled pages of a sampled block, on the
+     * assignment read the other pages of the sampled blocks. Every page must
+     * still be pushed, in order; the others may carry empty HTML.
      */
-    concurrency?: number;
+    pageMask(): Uint8Array;
     /**
-     * Column header definitions contributed by this plugin.
-     * Keys are column identifiers (`T`), values are human-readable labels
-     * shown in the report header row.
+     * Whether the run expects the assignment read: true once the first
+     * read has ended with pages outside the samples of a sampled block, until
+     * the assignment read has ended; false otherwise.
      */
-    headers?: TableHeaders<T>;
+    needsAssignment(): boolean;
+    /** Assigns the next pages of the second read, in corpus order. */
+    pushAssignmentPages(pages: readonly TemplatePageHtml[]): Promise<void>;
+    /** Merges the clusters across blocks; the run cannot be used afterwards. */
+    takeOutput(): Promise<TemplateClassificationOutput>;
     /**
-     * Per-page analysis callback executed in a Worker thread.
-     * @param page - Context for the current page, including the raw HTML,
-     *   a live JSDOM window, the page URL, and progress counters.
-     * @param page.url - Parsed URL of the page being analyzed.
-     * @param page.html - Raw HTML string of the page.
-     * @param page.window - JSDOM window with the page's DOM tree. Closed after the callback returns.
-     * @param page.num - Zero-based index of the current page in the batch.
-     * @param page.total - Total number of pages in the batch.
-     * @returns Report data for this page, or `null` to skip.
+     * Makes the running call, and every later one, reject at its next page or
+     * block. A call already finished but waiting on its progress events
+     * resolves without them.
      */
-    eachPage?(page: {
-        /** Parsed URL of the page being analyzed. */
-        url: URL;
-        /** Raw HTML string of the page. */
-        html: string;
-        /** JSDOM window with the page's DOM tree. Closed after the callback returns. */
-        window: DOMWindow;
-        /** Zero-based index of the current page in the batch. */
-        num: number;
-        /** Total number of pages in the batch. */
-        total: number;
-    }): Promise<ReportPage<T> | null> | ReportPage<T> | null;
+    cancel(): void;
+}
+/**
+ * Inputs to `createTemplateClassificationRun`.
+ * @example
+ * ```ts
+ * const options: CreateTemplateClassificationRunOptions = {
+ * 	onProgress: (event) => console.log(event.phase),
+ * };
+ * ```
+ */
+export interface CreateTemplateClassificationRunOptions {
     /**
-     * Per-URL analysis callback executed in the main thread.
-     *
-     * Unlike `eachPage`, this callback does **not** receive HTML or a DOM
-     * window. It is designed for checks that depend only on URL metadata
-     * (e.g. checking URL patterns, external link policies).
-     * @param page - URL context including external/internal classification.
-     * @param page.url - Parsed URL being analyzed.
-     * @param page.isExternal - Whether this URL is external to the crawled site.
-     * @returns Report data for this URL, or `null` to skip.
+     * Bytes a block's Stage A similarity table (`n * (n - 1) / 2 * 8` for `n`
+     * pages) may take before the block is clustered from a sample instead.
+     * Defaults to `TEMPLATE_MEMORY_BUDGET`; `0` samples every block.
      */
-    eachUrl?(page: {
-        /** Parsed URL being analyzed. */
-        url: URL;
-        /** Whether this URL is external to the crawled site. */
-        isExternal: boolean;
-    }): Promise<ReportPage<T> | null> | ReportPage<T> | null;
+    readonly memoryBudget?: number;
+    /** Receives progress events. */
+    readonly onProgress?: (event: TemplateClassificationProgress) => void;
 }
 /**
- * The return value of a single {@link AnalyzePlugin.eachPage} or {@link AnalyzePlugin.eachUrl}
- * invocation for one page/URL.
- *
- * A plugin can contribute tabular data (displayed in spreadsheet columns)
- * and/or violation records (displayed in a dedicated violations sheet).
- * @template T - Column key union matching the plugin's `headers`.
+ * The addon's isolated-cluster run, which `createIsolatedClusterRun` wraps
+ * into an {@link IsolatedClusterRun}; use that instead.
+ * @example
+ * ```ts
+ * const native = new nativeBinding.IsolatedClusterRun(Uint32Array.of(1, 2), new Uint32Array());
+ * native.unionEdges(Uint32Array.of(1, 2));
+ * native.labels(); // Uint32Array [0, 0]
+ * ```
  */
-export interface ReportPage<T extends string> {
-    /** Column data for this page. Keys must be a subset of `T`. */
-    page?: TableData<T>;
-    /** Violations detected on this page (e.g. a11y issues, lint errors). */
-    violations?: Violation[];
+export interface NativeIsolatedClusterRun {
+    /** {@link IsolatedClusterRun.unionEdges}, the pairs flattened. */
+    unionEdges(edges: Uint32Array): void;
+    /** {@link IsolatedClusterRun.labels}. */
+    labels(): Uint32Array;
 }
 /**
- * Aggregated report data from a Worker thread, keyed by page URL.
- *
- * This is the message payload returned from the Worker to the main thread
- * via the `'finish'` message. It aggregates results from all plugins that
- * ran `eachPage` for a single page.
- * @template T - Column key union.
- * @see {@link ./page-analysis-worker.ts} for the Worker entry point that produces this
- * @see {@link ./worker/worker-pool.ts!WorkerPool} for the main-thread consumer
+ * The candidates {@link groupAliasCandidates} hands the addon, column by
+ * column.
+ * @example
+ * ```ts
+ * const columns: NativeAliasCandidates = {
+ * 	urls: Buffer.from('https://example.com/'),
+ * 	urlOffsets: Uint32Array.of(0, 20),
+ * 	urlIds: Uint32Array.of(1),
+ * 	titleTextIds: Uint32Array.of(1),
+ * 	canonicalUrlIds: Uint32Array.of(4_294_967_295),
+ * 	bodyHashes: new Uint8Array(),
+ * 	hashOffsets: Uint32Array.of(0, 0),
+ * 	hashPresent: Uint8Array.of(0),
+ * };
+ * ```
  */
-export interface ReportPages<T extends string> {
-    /** Per-URL table data from all plugins. */
-    pages?: TablePages<T>;
-    /** Combined violations from all plugins. */
-    violations?: Violation[];
+export interface NativeAliasCandidates {
+    /** The URLs back to back as UTF-8. */
+    readonly urls: Uint8Array;
+    /** `n + 1` positions cutting `urls` into the `n` URLs. */
+    readonly urlOffsets: Uint32Array;
+    readonly urlIds: Uint32Array;
+    readonly titleTextIds: Uint32Array;
+    /** `4294967295` for a page without a canonical. */
+    readonly canonicalUrlIds: Uint32Array;
+    /** The body hashes back to back. */
+    readonly bodyHashes: Uint8Array;
+    /** `n + 1` positions cutting `bodyHashes` into `n` pieces. */
+    readonly hashOffsets: Uint32Array;
+    /** `0` for a page without a body hash (its piece is empty). */
+    readonly hashPresent: Uint8Array;
 }
 /**
- * Factory function signature that every analyze plugin module must
- * export as its default export.
- *
- * The factory receives the user's settings object (`O`) and returns
- * an {@link AnalyzePlugin} instance (or a Promise thereof). This two-phase
- * pattern allows plugins to perform async initialization (e.g.
- * loading locale files, compiling lint configs) once, then reuse
- * the resulting plugin for every page.
- *
- * Use {@link ./hooks/define-plugin.ts!definePlugin} to define a
- * plugin with full type inference.
- * @template O - Shape of the plugin's settings from the config file.
- * @template T - String literal union of column keys the plugin contributes.
+ * The two keys under which pages are grouped as the same page under another
+ * URL; see `computeAliasKeys`.
  * @example
  * ```ts
- * // In @nitpicker/analyze-search/src/index.ts
- * import { definePlugin } from '@nitpicker/core';
- *
- * type Options = { keywords: string[] };
- *
- * export default definePlugin(async (options: Options) => {
- *   return {
- *     headers: { found: 'Keywords Found' },
- *     async eachPage({ html }) {
- *       const count = options.keywords.filter(k => html.includes(k)).length;
- *       return { page: { found: { value: count } } };
- *     },
- *   };
- * });
+ * const keys: AliasKeys = { tierA: 'example.com/about/', tierB: 'example.com/about' };
  * ```
- * @see {@link AnalyzePlugin} for the runtime interface
- * @see {@link ./hooks/define-plugin.ts!definePlugin} for the type-safe wrapper
  */
-export type PluginFactory<O, T extends string = string> = (options: O, configFilePath: string) => Promise<AnalyzePlugin<T>> | AnalyzePlugin<T>;
+export interface AliasKeys {
+    /** Folds the scheme, the host's case and a trailing `/index.{ext}`. */
+    readonly tierA: string;
+    /** Tier A with one trailing `/` of the path dropped. */
+    readonly tierB: string;
+}
 /**
- * Column header definitions: maps column key to display label.
+ * One page that may be the same page as another under a different URL.
  * @example
  * ```ts
- * const headers: TableHeaders<'title' | 'desc'> = {
- *   title: 'Page Title',
- *   desc: 'Meta Description',
+ * const page: AliasCandidate = {
+ * 	url: 'https://example.com/about/',
+ * 	urlId: 7,
+ * 	titleTextId: 3,
+ * 	canonicalUrlId: null,
+ * 	bodyHash: null,
  * };
  * ```
  */
-export type TableHeaders<K extends string> = Record<K, string>;
-/** Internal Map representation of {@link TableHeaders}, used by {@link ../table.ts!Table}. */
-export type TableHeaderMap<K extends string> = Map<K, string>;
-/** A single row of cell values keyed by column identifier. */
-export type TableData<K extends string> = Record<K, TableValue>;
-/**
- * Multiple rows of table data keyed by page URL.
- * This is the serialized form used in Worker message payloads and JSON output.
- */
-export type TablePages<K extends string> = Record<string, TableData<K>>;
-/**
- * Internal Map representation of page-keyed table data.
- * Used by {@link ../table.ts!Table} for efficient merge operations.
- */
-export type TableRow<K extends string> = Map<string, TableData<K>>;
-/**
- * Payload for starting an analyze action.
- * @internal
- */
-export interface PluginExecutionContext {
-    /** Human-readable name of the plugin module. */
-    pluginModuleName: string;
-    /** Resolved file system path to the plugin module. */
-    pluginModulePath: string;
-    /** Plugin-specific settings to pass to the hook factory. */
-    settings: unknown;
-    /** Path to the config file where this action was declared. */
-    configFilePath: string;
-    /** Temporary directory where the archive is extracted. */
-    archiveTempDir: string;
-    /** Full resolved configuration. */
-    config: Config;
+export interface AliasCandidate {
+    /** The page's URL. */
+    readonly url: string;
+    /** `url_refs.id` of that URL. */
+    readonly urlId: number;
+    /** The id of the page's title text; pages with different titles never group. */
+    readonly titleTextId: number;
+    /** `url_refs.id` of the URL the page's `<link rel="canonical">` points at. */
+    readonly canonicalUrlId: number | null;
+    /** The page's body hash; without one the page groups by URL form only. */
+    readonly bodyHash: Uint8Array | null;
 }
 /**
- * Event map for the {@link ../nitpicker.ts!Nitpicker} event emitter.
- *
- * Consumers can listen to these events via `nitpicker.on('writeFile', ...)`.
- * @see {@link ../nitpicker.ts!Nitpicker} which extends `TypedAwaitEventEmitter<NitpickerEvent>`
+ * The connected components of the isolated pages, built from the pages' link
+ * edges as they are read. Created by `createIsolatedClusterRun`.
+ * @example
+ * ```ts
+ * const run = createIsolatedClusterRun([10, 20, 30], []);
+ * run.unionEdges([10, 20]);
+ * run.labels(); // Uint32Array [0, 0, 1]
+ * ```
  */
-export interface NitpickerEvent {
+export interface IsolatedClusterRun {
     /**
-     * Emitted after the archive file has been successfully written to disk.
+     * Joins the pages of a batch of link edges, `[page, href, page, href, ...]`
+     * by page id, in any order and batch size. An edge counts when `page` is a
+     * candidate and `href`, once redirects and aliases are followed, is a
+     * different one.
      */
-    writeFile: {
-        /** Absolute path to the written `.nitpicker` archive file. */
-        filePath: string;
-    };
+    unionEdges(edges: ArrayLike<number>): void;
     /**
-     * Emitted when a non-fatal error occurs during analysis.
+     * For each candidate, in the order given, the number of its component,
+     * counted in order of first appearance.
      */
-    error: {
-        /** Human-readable error description. */
-        message: string;
-        /** Original Error object, or `null` if unavailable. */
-        error: Error | null;
-    };
+    labels(): Uint32Array;
+}
+/**
+ * Inputs to `loadNativeBinding`. Every field defaults to the running
+ * process; tests override them to exercise other platforms.
+ */
+export interface LoadNativeBindingOptions {
+    /** `process.platform` of the host. */
+    readonly platform: NodeJS.Platform;
+    /** `process.arch` of the host. */
+    readonly arch: NodeJS.Architecture;
+    /**
+     * glibc version of the running process (e.g. `"2.35"`), or `null` when the
+     * C library is not glibc (musl). Consulted only when `platform` is
+     * `linux`; when omitted there, it is read from Node's diagnostic report.
+     */
+    readonly glibcVersion: string | null;
+    /** Absolute path of the `@nitpicker/core` package directory. */
+    readonly packageDir: string;
+    /** Whether a file exists (`fs.existsSync`). */
+    readonly fileExists: (filePath: string) => boolean;
+    /** Loads a `.node` file or a package by specifier (`require`). */
+    readonly requireModule: (specifier: string) => unknown;
 }