@nitpicker/core 0.24.0 → 0.25.1

package/README.md

@@ -1,47 +1,177 @@
 # @nitpicker/core
 
-`.nitpicker` アーカイブ内のページに対して analyze プラグインを実行する内部パッケージです。
-
-プラグインの読み込み、実行、結果の書き戻しを担当します。通常は [@nitpicker/cli](../cli/README.md) の `analyze` コマンドから利用します。
-
-## プラグイン作者向けAPI
-
-analyze プラグインは `definePlugin()` で定義します。
-
-```ts
-import { definePlugin } from '@nitpicker/core';
-
-type Options = {
-	keywords: string[];
-};
-
-export default definePlugin((options: Options) => {
-	return {
-		label: 'キーワード検索',
-		// 並列度を宣言できる。省略時は os.cpus().length
-		// 重いプラグインは小さく設定する
-		concurrency: 4,
-		headers: {
-			found: 'Keywords Found',
-		},
-		async eachPage({ window }) {
-			const text = window.document.body.textContent ?? '';
-			const count = options.keywords.filter((keyword) => text.includes(keyword)).length;
-			return {
-				page: { found: { value: count } },
-			};
-		},
-	};
+Nitpicker の計算コアを Rust（Node-API、[napi-rs](https://napi.rs/)）で実装したネイティブアドオンです。重い計算をここに集め、[@nitpicker/archive](../archive/README.md)などの TypeScript パッケージから呼び出します。現在は、ページ本文の内容ハッシュ（`page_meta.body_hash`）、HTML の構造シグナルによる技術検出、URL の自然順の順位付け、alias の判定、リンクの連結成分、テンプレート分類（ページのシグナルと HTML から、ページごとのテンプレートキーとクラスタごとの reason まで）、保存済み HTML スナップショットに対する CSS セレクタの照合（`query match-selector`）と文字列・正規表現の検索（`query search-html`）を提供しています。
+
+## 対応プラットフォーム
+
+ビルド済みバイナリだけを配布し、JavaScript のフォールバックはありません。対応しているのは次の 2 つです。
+
+| プラットフォーム                      | バイナリを含むパッケージ                                         |
+| ------------------------------------- | ---------------------------------------------------------------- |
+| macOS（Apple silicon）                | [@nitpicker/core-darwin-arm64](../core-darwin-arm64/README.md)   |
+| Linux x64・glibc 2.28 以上（WSL2 可） | [@nitpicker/core-linux-x64-gnu](../core-linux-x64-gnu/README.md) |
+
+glibc 2.28 は Node.js 24 自体の Linux バイナリと同じ下限です。上記以外（Intel Mac、linux-arm64、musl、Windows ネイティブ）では、読み込んだ時点で対応表を含むエラーを出して終了します。プラットフォーム別パッケージは`optionalDependencies`で入るため、`--omit=optional`/`--no-optional`を付けてインストールすると読み込めません。
+
+## 使い方
+
+公開 API は 1 関数 1 サブパスで export しています。
+
+```ts
+import { computeBodyHash } from '@nitpicker/core/compute-body-hash';
+
+const a = computeBodyHash(Buffer.from('<body><a href="/p/a1b2c3d4">x</a></body>'));
+const b = computeBodyHash(Buffer.from('<body><a href="/p/z9y8x7w6">x</a></body>'));
+a.equals(b); // true — 動的 ID はマスクしてからハッシュする
+```
+
+フロントエンドフレームワークの構造シグナル（Next.js の`__NEXT_DATA__`、Vue の`data-v-*`など）は、`matchStructuralTechnologySignals`がページの HTML を 1 回走査して検出します。JS リソースの先頭にあるライセンスコメントは`matchJsLicenseCommentSignal`で照合します。フィンガープリントの一覧は`crates/nitpicker_tech_detect`が正です。
+
+```ts
+import { matchStructuralTechnologySignals } from '@nitpicker/core/match-structural-technology-signals';
+
+matchStructuralTechnologySignals(Buffer.from('<div data-v-1a2b3c4d></div>'));
+// [{ technology: 'Vue', signalType: 'scoped-attr', evidence: ' data-v-1a2b3c4d', weight: 40, category: 'JavaScript frameworks' }]
+```
+
+URL の自然順（`page2`が`page10`の前、大文字小文字・パーセントエンコードで順序が割れない、ホストが先でパスが後）は、`computeUrlSortRanks`が全件まとめて順位にします。URL は 1 回だけパースし、結果は入力順に依存しない全順序です（同じ URL は入力順）。順序の定義は`crates/nitpicker_url_key`の doc が正です。
+
+```ts
+import { computeUrlSortRanks } from '@nitpicker/core/compute-url-sort-ranks';
+
+computeUrlSortRanks([
+	'https://example.com/page10',
+	'https://example.com/page2',
+	'https://example.com/',
+]); // Uint32Array [2, 1, 0]
+```
+
+同じページが別の URL で現れている組（`content_items.alias_of_id`）の判定には、URL からスキーム・ホストの大文字小文字・`/index.{ext}`をたたんだ Tier A キーと、さらに末尾スラッシュを落とした Tier B キーを使います。`computeAliasKeys`が 1 回のパースで両方を返し、`groupAliasCandidates`がキー・タイトル・本文ハッシュで連結成分にまとめて代表を選びます（グループ内を指す canonical が最多 → 最短 URL → UTF-16 の昇順）。
+
+```ts
+import { computeAliasKeys } from '@nitpicker/core/compute-alias-keys';
+
+computeAliasKeys('http://Example.com/about/index.html');
+// { tierA: 'example.com/about/', tierB: 'example.com/about' }
+```
+
+リンクでつながったページの連結成分は、`createIsolatedClusterRun`で求めます。辺は SQLite から読んだ分ずつ`unionEdges`に渡して捨てるので、メモリはページ数に比例し、辺の数には比例しません。リダイレクト先・alias の先に解決してから結び、終わりのない連鎖（ループ、ループに合流する尾）の辺は捨てます。成分の番号は候補の並び順で振られ、辺の順序や分け方に依存しません。
+
+```ts
+import { createIsolatedClusterRun } from '@nitpicker/core/create-isolated-cluster-run';
+
+// 候補 10, 20, 30。ページ 40 は 30 へのリダイレクト元で候補ではない
+const run = createIsolatedClusterRun([10, 20, 30], [40, 30]);
+run.unionEdges([10, 20, 20, 40]);
+run.labels(); // Uint32Array [0, 0, 0]
+```
+
+保存済み HTML スナップショットのセレクタ照合は、`matchSelectorSnapshots`がバッチ（`page_html_blobs`の行）を受け取り、zstd の展開から判定までをスレッドプールで並列に行って、スナップショットごとの判定を返します。同時に展開済みの文書を持つのは、スレッド数ぶんだけです。zstd のスナップショット 1 件の展開後は`MAX_DECODED_SNAPSHOT_BYTES`（`@nitpicker/core/max-decoded-snapshot-bytes`、約 1.5 GiB）までで、超えると「不一致」にせず、`snapshot <n> could not be decoded`で呼び出し全体を reject します。zstd のフレームヘッダが述べる展開後サイズは省略も偽りもできるので、展開しながら出てきたバイト数を数えて止めます。上限はクローラーが保存できる最大（V8 の文字列の最大長 2^29 − 24 code unit × UTF-8 の最大 3 バイト）なので、クローラーが保存したスナップショットが上限で弾かれることはありません。圧縮せずに保存されたスナップショットには掛けません（`searchHtmlSnapshots`も同じ）。1 文書だけを同期で判定する`matchSelectorHtml`は、テストとベンチの段階比較のために出しています。判定は、必要なリテラルが順に現れるかの事前判定、開始タグだけで決まるセレクタの開始タグ走査、結合子と`:nth-*`のための開タグスタックの順で、最も安い厳密な手段を使います。タグ名と属性名は ASCII の大文字小文字だけを無視します。計画（`SelectorPlan`）の作り方と解釈規則は`@nitpicker/cli`の`docs/query.md`が正です。
+
+```ts
+import { matchSelectorSnapshots } from '@nitpicker/core/match-selector-snapshots';
+
+const verdicts = await matchSelectorSnapshots({
+	plan,
+	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+});
+verdicts[0]; // { matched: true, prefiltered: false, tokenized: false }
+```
+
+保存済み HTML スナップショットの文字列・正規表現検索は、`searchHtmlSnapshots`がバッチを受け取り、展開から照合までを同じようにスレッドプールで並列に行って、スナップショットごとの`matchCount`（0 なら不一致）とスニペットを返します。パターンはスナップショットごとではなく 1 回だけコンパイルし、アドオンは直前にコンパイルしたパターンを保持して次のバッチでも使い回します（保持は 1 件だけなので、別のパターンの検索が並行すると入れ替わり、そのぶん再コンパイルします）。1 文書だけを同期で検索する`searchHtmlDocument`はテスト用、アーカイブを開く前にパターンを検証する`validateSearchPattern`は空文字列に一致するかを返し、構文エラーは`InvalidArg`で投げます。パターンは Rust の`regex` crate の構文（後方参照・先読み・後読みなし。照合時間は文書長に比例）で、マッチの単位は Unicode スカラー値、`\d` `\w` `\s` `\b`は Unicode の定義、`.`は`\r`と`\n`に一致せず、`m`の`^` `$`は CRLF を 1 つの行末として扱います。スニペットは、文書全体の空白を畳んでから窓を切ります。バッチの`bodies`は JS のバッファをコピーせず読むので、呼び出し側は promise が決着するまで書き換えないでください。永続化される値ではないので`(?-u)`は使わず、契約は`@nitpicker/cli`の`docs/query.md`（パターンの契約）が正です。
+
+```ts
+import { searchHtmlSnapshots } from '@nitpicker/core/search-html-snapshots';
+
+const outcomes = await searchHtmlSnapshots({
+	pattern: {
+		source: 'fonts.example.org',
+		literal: true,
+		ignoreCase: false,
+		multiLine: false,
+		dotAll: false,
+	},
+	snippetLength: 160,
+	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
 });
+outcomes[0]; // { matchCount: 2, snippet: '…fonts.example.org…' }
 ```
 
-`concurrency` を省略するとCPUコア数が使われます。ChromeやPuppeteerなど重いプロセスを起動するプラグインでは、2〜4程度に絞ることを推奨します。
+テンプレート分類は、呼び出し側（`@nitpicker/archive`の`resolvePageClusterKeys`）がコーパスを読んで順に渡して実行します。全ページのシグナル（URL パス・スタイルシート・ホスト）を渡してブロック分け（Pass 0）し、続けて全ページの HTML をコーパス順に渡します。計算する呼び出しはアドオン内のスレッドプールで動き、Promise を返します。呼び出しは重ねず、1 つずつ await します。
+
+```ts
+import { createTemplateClassificationRun } from '@nitpicker/core/create-template-classification-run';
+
+const run = createTemplateClassificationRun();
+run.pushSignals([
+	{ paths: ['news', '1'], stylesheetHrefs: [] },
+	{ paths: ['news', '2'], stylesheetHrefs: [] },
+]);
+await run.block();
+await run.pushPages([
+	{ html: '<body><main><p>a</p></main></body>' },
+	{ html: '<body><main><p>b</p></main></body>' },
+]);
+await run.finishPages();
+const { keys, keyOfPage, reasons } = await run.takeOutput();
+keys[keyOfPage[0]!]; // '["path:news","cluster:0"]'
+```
+
+ブロックは既定で全ページをクラスタリングします。次の 2 つの場合だけ、そのブロックを`TEMPLATE_BLOCK_SAMPLE_SIZE`（`@nitpicker/core/template-block-sample-size`）ページのサンプルでクラスタリングします。
+
+- Stage A の類似度表（`n * (n - 1) / 2 * 8`バイト、`n`はブロックのページ数）が`memoryBudget`を超える。`memoryBudget`は`createTemplateClassificationRun`のオプションで、既定は`TEMPLATE_MEMORY_BUDGET`（`@nitpicker/core/template-memory-budget`、512 MiB）、0 なら全ブロックが対象になる。
+- 全ページで計算するブロックの合計が`TEMPLATE_EXACT_PAGE_LIMIT`（`@nitpicker/core/template-exact-page-limit`、20,000 ページ）を超える。この場合は、標本より大きい（100 ページを超える）ブロックを、ページ数が多い順（同数なら出現順）に、収まるまで対象にする。100 ページ以下のブロックはサンプルにしても保持ページが減らないので対象にならず、それだけで上限を超えるときは超えたまま保持する。上限は固定で、利用者は変えられない。
+
+既定の 512 MiB は、約 11,500 ページのブロックまでの類似度表に当たります。1 ページの解析結果は最大で約 60 KB です。同じ切り取りの深さはトークンを共有し、本文は圧縮して持つので、通常はこれより小さくなります。20,000 ページなら最大で約 1.2 GB を、ブロックの計算が終わるまで抱えます。どのブロックが落ちるかで保存される`templateKey`が決まるので、メモリ上限を変えると結果が変わります。既存のアーカイブは、`viewer-build`で再分類するまで以前のキーのままです。
+
+サンプルに落としたブロックの残りのページは、2 回目の読み込み（`needsAssignment()`が true のときの`pushAssignmentPages`）で最も近いクラスタに割り当てます。落としたブロックは、`block()`の間に`block-sampled`の進捗イベントで 1 つずつ通知され、`takeOutput()`の`sampledBlocks`にも、理由（`table-over-budget`か`pages-over-limit`）つきで残ります。どちらの読み込みでも全ページをコーパス順に渡しますが、`pageMask()`が 0 のページは HTML を空文字にして構いません（HTML を読み出す必要もありません）。
+
+### スレッドプール・同時実行数・キャンセル
+
+非同期のネイティブ呼び出し（`matchSelectorSnapshots`・`searchHtmlSnapshots`・テンプレート分類の各呼び出し）は、アドオンが持つ専用のスレッドプールで動きます。次の 2 つの環境変数で調整できます。値は正の整数で、プロセスで最初にプールを使うときに 1 回だけ読みます。正の整数でない値は、既定値に置き換えずにエラーにします。
+
+| 環境変数                       | 既定                                                    | 内容                                                                                                                                                                                    |
+| ------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NITPICKER_NATIVE_THREADS`     | rayon の既定（`RAYON_NUM_THREADS`、なければ論理コア数） | プールのスレッド数。同期の`computeUrlSortRanks`もこのプールで動く                                                                                                                       |
+| `NITPICKER_NATIVE_CONCURRENCY` | 1                                                       | 同時に走らせる非同期呼び出しの数。1 つの呼び出しがすでに全スレッドを使うので、増やしても合計の処理量は増えない。同期の`computeUrlSortRanks`はこの上限に数えず、待たずに専用プールを使う |
+
+上限を超えた呼び出しは、拒否せず、受け付けた順（FIFO）に待ちます。待っている間はスレッドを占有しません。`checkNativeExecutorConfig`は、環境変数の誤りを最初のネイティブ呼び出しではなく作業の開始前に検出します。
+
+```ts
+import { checkNativeExecutorConfig } from '@nitpicker/core/check-native-executor-config';
+
+checkNativeExecutorConfig(); // NITPICKER_NATIVE_THREADS="lots" なら InvalidArg で投げる
+```
+
+`matchSelectorSnapshots`と`searchHtmlSnapshots`は`signal`（`AbortSignal`）を受け取ります。abort すると、実行中の呼び出しは次のスナップショットの前か展開中のスナップショットの次の 1 MiB を読む前で止まり、待機中の呼び出しは順番が来た時点で終わります。どちらも`signal.reason`で reject します。すでに abort 済みの signal は、アドオンを呼ばずに reject します。同じバッチに展開に失敗したスナップショットがあっても、abort を見たスナップショットが 1 つでもあれば abort（`signal.reason`）を返します。展開のエラーを返すのは、どのスナップショットも abort を見る前に失敗したときだけです。テンプレート分類は、これまでどおり`run.cancel()`で止めます。
+
+```ts
+const controller = new AbortController();
+const pending = matchSelectorSnapshots({ plan, snapshots, signal: controller.signal });
+controller.abort(new Error('client went away'));
+await pending; // rejects with the Error above
+```
+
+## 開発
+
+Rust ツールチェーンが必要です（バージョンはリポジトリルートの`rust-toolchain.toml`で固定。セットアップは[CONTRIBUTING.md](../../../CONTRIBUTING.md)を参照）。`yarn build`を実行すると、`scripts/build-native.mjs`がホスト向けのアドオンをビルドしてパッケージ直下に`core.<platform>.node`として置きます。ローダーはこのローカルビルドを先に探し、なければプラットフォーム別パッケージを読み込みます。
+
+- Rust のコードは`crates/`配下の Cargo workspace にあります。napi に依存するのは`nitpicker_napi`（公開関数だけの薄い層）だけで、計算本体の crate は`cargo test`だけでテストできます
+- `yarn test:rust`で Rust のテスト、`yarn lint`で rustfmt と clippy も実行します
+- body hash は既存アーカイブに保存済みの値と byte 単位で一致させています（例外は、本物の body より前に`<bodyguard>`のような`<body`で始まるカスタム要素があるページで、body の開始位置が変わるため値が変わります。#434）。`crates/nitpicker_html_scan/tests/fixtures/body-hash-golden.json`は`@nitpicker/archive`の`src/body-hash/`にある JavaScript 段階実装（parity テストの oracle）から生成した golden fixture です。Rust 側は正規化とマスクを 1 パスにまとめていて、段階版の Rust 関数と一致することを`tests/fused_body_hash_properties.rs`で確かめています
+- 構造シグナルの技術検出（`crates/nitpicker_tech_detect`）は、既存アーカイブの`technology_signals`を書いた JavaScript 正規表現と同じシグナル・同じ順序・同じ evidence を返します。正規表現は JS の`u`フラグなしの意味論に合わせ、`\s`は JS が含める非 ASCII の空白（U+00A0・U+FEFF など）まで並べています。走査は、定義ごとの必須リテラルを Aho-Corasick で 1 回探し、見つかった定義だけを正規表現で確かめます。`tests/fixtures/technology-signals-golden.json`は`@nitpicker/archive`の`src/meta/technologies/structural-signal-definitions.ts`（parity テストの oracle）から`scripts/generate-technology-signals-golden.mjs`で生成した golden fixture です
+- テンプレート分類（`crates/nitpicker_template_cluster`）も、既存アーカイブの`templateKey`と reason に一致させています。HTML は htmlparser2 12.0.0 の挙動を移植した`crates/nitpicker_html_parser`で読み、スタイルシートのホストは呼び出し側の`new URL(href).host`を使います。一致の確認は`@nitpicker/archive`の golden（`src/template-classification/golden/`）で行います
+- URL の順序（`crates/nitpicker_url_key`）は、文字列から数値を取り出して 2 件ずつ比べる方式を採りません。その方式は推移律が崩れる（`a9`は`a10`より前、`a10`は`a1x`より前、`a1x`は`a9`より前になる）ためで、順序はバイト列キーの全順序として定義します。基準は、`tests/order_spec.rs`（期待順序の表）と`tests/order_properties.rs`（入力順不変・キーが同じ URL は生の URL 文字列の順・数値順などのプロパティテスト）です。順位は viewer の read model に保存されるので、順序の定義を変えるときは read model の schema version を上げます
+- alias キー（`crates/nitpicker_url_key`の`alias_keys`）は、既存アーカイブの`content_items.alias_of_id`を作った JavaScript 実装のキーと一致させています。`tests/fixtures/alias-keys-golden.json`は`@nitpicker/archive`の`src/url-alias/`にある JavaScript 実装（parity テストの oracle）から`scripts/generate-alias-keys-golden.mjs`で生成した golden fixture で、キーは URL を書かれたまま（WHATWG URL の`pathname`と`search`）読むので、並べ替え用のキーとは別の読み方です。グルーピングと代表選定は、JavaScript の参照実装と突き合わせる parity テスト（`@nitpicker/archive`の`group-alias-candidates.parity.spec.ts`）で固めています
+- 連結成分（`crates/nitpicker_union_find`）の成分は、辺の順序とバッチ分割に依存しません（`tests/components_properties.rs`）。成分の番号は候補の並び順だけで決まり、read model の`component_id`になるので、候補は page id の昇順で渡します
+- セレクタ照合（`crates/nitpicker_html_scan`の`html_matches_selector`と`scan_snapshots`）の結果は永続化されないので、`docs/query.md`の解釈規則を正解にして書いています。`tag_tokenizer.rs`がタグを読み、direct 段（`run_direct_match.rs`）と開タグスタック（`run_selector_state_machine.rs`）が同じトークナイザを使います。開始タグの属性は、ブラウザのシリアライザの出力を読み戻せるよう HTML のトークナイザと同じ規則で読みます（`start_tag_attributes.rs`。ソースの引用符が欠けたページは属性名に`"`を含んで直列化されるため、引用符の対応だけでは開始タグの終わりを見失います）。正解は`@nitpicker/query`の oracle spec（直列化前の DOM の`querySelector`）です
+- `crates/nitpicker_html_parser`には生成した固定データが 2 つあります。どちらも、リポジトリが依存していない固定版のパッケージを scratch ディレクトリに入れ、そのディレクトリを引数に渡して生成します（手順と理由は各スクリプトの冒頭）
+  - エンティティの表`src/html_decode_tree.rs`: `node scripts/generate-html-decode-tree.mjs <entities@8.0.0 のディレクトリ>`。デコードを意図して変えるときだけ再生成します
+  - パーサーの比較基準`tests/htmlparser2-fixture-events.tsv`: `node scripts/record-htmlparser2-events.mjs <htmlparser2@12.0.0 のディレクトリ>`。`@nitpicker/archive`の`page-cluster/__fixtures__/`を変えたときに取り直します
 
 ## 関連リンク
 
 - [Nitpicker README](../../../README.md)
-- [CLI analyze docs](../cli/docs/analyze.md)
-- [CONTRIBUTING.md](../../../CONTRIBUTING.md)
 - [ARCHITECTURE.md](../../../ARCHITECTURE.md)
 
 ## ライセンス

package/lib/assert-u32-id.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Checks that a row id survives being stored in a `u32` array: a typed array
+ * wraps `2**32` to `0` and truncates `1.5` to `1`, which here would join the
+ * wrong pages without any error.
+ * @param value - The id (a database row id).
+ * @param what - What the id is, for the error message.
+ * @returns `value`, unchanged.
+ * @throws {RangeError} When `value` is not an integer in `0..=4294967294`.
+ * @example
+ * ```ts
+ * assertU32Id(7, 'candidate id'); // 7
+ * assertU32Id(2 ** 32, 'candidate id'); // throws RangeError
+ * ```
+ */
+export declare function assertU32Id(value: number, what: string): number;

package/lib/assert-u32-id.js

@@ -0,0 +1,22 @@
+/** The addon reads `4294967295` as "none", so no id may take that value. */
+const MAX_ID = 4_294_967_294;
+/**
+ * Checks that a row id survives being stored in a `u32` array: a typed array
+ * wraps `2**32` to `0` and truncates `1.5` to `1`, which here would join the
+ * wrong pages without any error.
+ * @param value - The id (a database row id).
+ * @param what - What the id is, for the error message.
+ * @returns `value`, unchanged.
+ * @throws {RangeError} When `value` is not an integer in `0..=4294967294`.
+ * @example
+ * ```ts
+ * assertU32Id(7, 'candidate id'); // 7
+ * assertU32Id(2 ** 32, 'candidate id'); // throws RangeError
+ * ```
+ */
+export function assertU32Id(value, what) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_ID) {
+        throw new RangeError(`${what}: ${value} is not an integer in 0..=${MAX_ID}`);
+    }
+    return value;
+}

package/lib/check-native-executor-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Builds the addon's thread pool from its environment settings now, so an
+ * invalid value fails before any work starts instead of at the first native
+ * call that needs the pool.
+ *
+ * - `NITPICKER_NATIVE_THREADS`: threads of the pool. Unset: rayon's default
+ *   (`RAYON_NUM_THREADS`, else the number of logical cores).
+ * - `NITPICKER_NATIVE_CONCURRENCY`: asynchronous native calls (match-selector,
+ *   search-html, template classification) that run at once. Unset: 1. A call
+ *   over the limit waits its turn; it is never refused.
+ *
+ * Both are read once, when the pool is first built; changing them afterwards
+ * has no effect in that process.
+ * @throws {Error} With code `InvalidArg`, naming the variable and its value,
+ *   when a setting is not a positive integer.
+ * @example
+ * ```ts
+ * checkNativeExecutorConfig(); // throws before the crawl starts if the env is wrong
+ * ```
+ */
+export declare function checkNativeExecutorConfig(): void;

package/lib/check-native-executor-config.js

@@ -0,0 +1,24 @@
+import { nativeBinding } from './native-binding.js';
+/**
+ * Builds the addon's thread pool from its environment settings now, so an
+ * invalid value fails before any work starts instead of at the first native
+ * call that needs the pool.
+ *
+ * - `NITPICKER_NATIVE_THREADS`: threads of the pool. Unset: rayon's default
+ *   (`RAYON_NUM_THREADS`, else the number of logical cores).
+ * - `NITPICKER_NATIVE_CONCURRENCY`: asynchronous native calls (match-selector,
+ *   search-html, template classification) that run at once. Unset: 1. A call
+ *   over the limit waits its turn; it is never refused.
+ *
+ * Both are read once, when the pool is first built; changing them afterwards
+ * has no effect in that process.
+ * @throws {Error} With code `InvalidArg`, naming the variable and its value,
+ *   when a setting is not a positive integer.
+ * @example
+ * ```ts
+ * checkNativeExecutorConfig(); // throws before the crawl starts if the env is wrong
+ * ```
+ */
+export function checkNativeExecutorConfig() {
+    nativeBinding.checkNativeExecutorConfig();
+}

package/lib/compute-alias-keys.d.ts

@@ -0,0 +1,28 @@
+import type { AliasKeys } from './types.js';
+/**
+ * Computes the two keys under which pages are grouped as the same page under
+ * another URL, parsing `url` once.
+ *
+ * Both keys read the URL as written (`pathname` and `search` as the WHATWG
+ * URL serializes them) and are `host[:port]path[?query]`:
+ *
+ * - **Tier A** folds what is safe to treat as one resource from the URL
+ *   alone: the scheme (a default port is left out, so `http` and `https`
+ *   share a key), the host's case, and a trailing `/index.{ext}`.
+ * - **Tier B** is Tier A with one trailing `/` of the path dropped (the path
+ *   `/` stays): a weaker signal, so a caller confirms it by comparing the
+ *   page content.
+ *
+ * The fragment is never part of a key, and an empty query is no query.
+ * @param url - The URL string.
+ * @returns Both keys, or `null` for a string that does not parse and for a
+ *   URL that is not `http` or `https` (such a URL is left out of alias
+ *   grouping).
+ * @example
+ * ```ts
+ * computeAliasKeys('http://Example.com/about/index.html');
+ * // { tierA: 'example.com/about/', tierB: 'example.com/about' }
+ * computeAliasKeys('mailto:a@example.com'); // null
+ * ```
+ */
+export declare function computeAliasKeys(url: string): AliasKeys | null;

package/lib/compute-alias-keys.js

@@ -0,0 +1,30 @@
+import { nativeBinding } from './native-binding.js';
+/**
+ * Computes the two keys under which pages are grouped as the same page under
+ * another URL, parsing `url` once.
+ *
+ * Both keys read the URL as written (`pathname` and `search` as the WHATWG
+ * URL serializes them) and are `host[:port]path[?query]`:
+ *
+ * - **Tier A** folds what is safe to treat as one resource from the URL
+ *   alone: the scheme (a default port is left out, so `http` and `https`
+ *   share a key), the host's case, and a trailing `/index.{ext}`.
+ * - **Tier B** is Tier A with one trailing `/` of the path dropped (the path
+ *   `/` stays): a weaker signal, so a caller confirms it by comparing the
+ *   page content.
+ *
+ * The fragment is never part of a key, and an empty query is no query.
+ * @param url - The URL string.
+ * @returns Both keys, or `null` for a string that does not parse and for a
+ *   URL that is not `http` or `https` (such a URL is left out of alias
+ *   grouping).
+ * @example
+ * ```ts
+ * computeAliasKeys('http://Example.com/about/index.html');
+ * // { tierA: 'example.com/about/', tierB: 'example.com/about' }
+ * computeAliasKeys('mailto:a@example.com'); // null
+ * ```
+ */
+export function computeAliasKeys(url) {
+    return nativeBinding.computeAliasKeys(url);
+}

package/lib/compute-body-hash.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Computes the content hash stored as `page_meta.body_hash`: SHA-256 of the
+ * page's `<body>` content after collapsing `/index.{ext}` URL forms to `/`
+ * and masking mixed letter-and-digit tokens of 8+ characters (cache-busting
+ * hashes, session ids, CSS-module suffixes).
+ *
+ * Takes UTF-8 bytes rather than a string so the native side never builds a
+ * UTF-16 copy. The result is byte-identical to the hashes already stored in
+ * existing archives, which JavaScript computed (golden fixture in
+ * `crates/nitpicker_html_scan/tests/fixtures/`), so old and new crawls stay
+ * comparable.
+ * @param html - The full HTML document (or a fragment) as UTF-8 bytes —
+ *   `Buffer.from(html, 'utf8')`.
+ * @returns The 32-byte hash, ready to insert into a `BLOB` column.
+ * @example
+ * ```ts
+ * const a = computeBodyHash(Buffer.from('<body><a href="/p/a1b2c3d4">x</a></body>'));
+ * const b = computeBodyHash(Buffer.from('<body><a href="/p/z9y8x7w6">x</a></body>'));
+ * a.equals(b); // true — the differing token is masked before hashing
+ * ```
+ */
+export declare function computeBodyHash(html: Uint8Array): Buffer;

package/lib/compute-body-hash.js

@@ -0,0 +1,25 @@
+import { nativeBinding } from './native-binding.js';
+/**
+ * Computes the content hash stored as `page_meta.body_hash`: SHA-256 of the
+ * page's `<body>` content after collapsing `/index.{ext}` URL forms to `/`
+ * and masking mixed letter-and-digit tokens of 8+ characters (cache-busting
+ * hashes, session ids, CSS-module suffixes).
+ *
+ * Takes UTF-8 bytes rather than a string so the native side never builds a
+ * UTF-16 copy. The result is byte-identical to the hashes already stored in
+ * existing archives, which JavaScript computed (golden fixture in
+ * `crates/nitpicker_html_scan/tests/fixtures/`), so old and new crawls stay
+ * comparable.
+ * @param html - The full HTML document (or a fragment) as UTF-8 bytes —
+ *   `Buffer.from(html, 'utf8')`.
+ * @returns The 32-byte hash, ready to insert into a `BLOB` column.
+ * @example
+ * ```ts
+ * const a = computeBodyHash(Buffer.from('<body><a href="/p/a1b2c3d4">x</a></body>'));
+ * const b = computeBodyHash(Buffer.from('<body><a href="/p/z9y8x7w6">x</a></body>'));
+ * a.equals(b); // true — the differing token is masked before hashing
+ * ```
+ */
+export function computeBodyHash(html) {
+    return nativeBinding.computeBodyHash(html);
+}

package/lib/compute-url-sort-ranks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ranks URLs in the natural order the viewer lists them in: numbers inside
+ * a path compare by value (`page2` before `page10`), letter case and
+ * percent-escapes do not split the order, a directory's own page comes
+ * before its index pages and its children, and the host decides before the
+ * path. The full definition is the `nitpicker_url_key` crate's docs.
+ *
+ * The order is a total order: the same URLs in any input order get the same
+ * ranking, and identical URLs rank in input order. It is persisted (the
+ * viewer read model stores each page's rank), so a change to it needs a read
+ * model schema version bump.
+ *
+ * Parses each URL once, natively, and sorts on the native thread pool; only
+ * two buffers cross the boundary however many URLs there are.
+ * @param urls - The URLs to rank. Each must be a well-formed string (a lone
+ *   surrogate is written as U+FFFD).
+ * @returns For each input position, the rank (zero-based position in the
+ *   sorted list) of that URL — a permutation of `0..urls.length`.
+ * @example
+ * ```ts
+ * computeUrlSortRanks([
+ * 	'https://example.com/page10',
+ * 	'https://example.com/page2',
+ * 	'https://example.com/',
+ * ]); // Uint32Array [2, 1, 0]
+ * ```
+ */
+export declare function computeUrlSortRanks(urls: readonly string[]): Uint32Array;

package/lib/compute-url-sort-ranks.js

@@ -0,0 +1,49 @@
+import { nativeBinding } from './native-binding.js';
+/** The native call addresses the URL bytes with `u32` offsets. */
+const MAX_URL_BYTES = 4_294_967_295;
+/**
+ * Ranks URLs in the natural order the viewer lists them in: numbers inside
+ * a path compare by value (`page2` before `page10`), letter case and
+ * percent-escapes do not split the order, a directory's own page comes
+ * before its index pages and its children, and the host decides before the
+ * path. The full definition is the `nitpicker_url_key` crate's docs.
+ *
+ * The order is a total order: the same URLs in any input order get the same
+ * ranking, and identical URLs rank in input order. It is persisted (the
+ * viewer read model stores each page's rank), so a change to it needs a read
+ * model schema version bump.
+ *
+ * Parses each URL once, natively, and sorts on the native thread pool; only
+ * two buffers cross the boundary however many URLs there are.
+ * @param urls - The URLs to rank. Each must be a well-formed string (a lone
+ *   surrogate is written as U+FFFD).
+ * @returns For each input position, the rank (zero-based position in the
+ *   sorted list) of that URL — a permutation of `0..urls.length`.
+ * @example
+ * ```ts
+ * computeUrlSortRanks([
+ * 	'https://example.com/page10',
+ * 	'https://example.com/page2',
+ * 	'https://example.com/',
+ * ]); // Uint32Array [2, 1, 0]
+ * ```
+ */
+export function computeUrlSortRanks(urls) {
+    // One encoding pass into a buffer sized for the worst case (3 UTF-8 bytes
+    // per UTF-16 unit), rather than measuring every URL and encoding it again.
+    let capacity = 0;
+    for (const url of urls) {
+        capacity += url.length * 3;
+    }
+    const bytes = Buffer.allocUnsafe(capacity);
+    const offsets = new Uint32Array(urls.length + 1);
+    let total = 0;
+    for (const [index, url] of urls.entries()) {
+        total += bytes.write(url, total, 'utf8');
+        if (total > MAX_URL_BYTES) {
+            throw new RangeError(`The URLs take more than ${MAX_URL_BYTES} bytes (4 GiB), which the native call cannot address.`);
+        }
+        offsets[index + 1] = total;
+    }
+    return nativeBinding.computeUrlSortRanks(bytes.subarray(0, total), offsets);
+}

package/lib/create-isolated-cluster-run.d.ts

@@ -0,0 +1,35 @@
+import type { IsolatedClusterRun } from './types.js';
+/**
+ * Starts the computation of the connected components of the isolated pages:
+ * the inventory pages that are linked to only from other inventory pages.
+ *
+ * The caller reads the link edges (`anchor_edges`) from SQLite batch by batch
+ * and hands each batch to {@link IsolatedClusterRun.unionEdges} as it
+ * arrives, so the edges are never held: the memory follows the number of pages,
+ * not the number of links. An edge to a redirect source or an alias member
+ * counts as an edge to the page it finally lands on; a chain that never ends
+ * (it loops, or leads into a loop) drops the edge. The components do not
+ * depend on the order of the edges or how they were batched.
+ *
+ * The components are numbered in the order of the candidates: the first
+ * candidate's component is `0`, and each later component takes the next
+ * number the first time one of its candidates appears. Hand the candidates
+ * over in ascending page id, which is the numbering the viewer read model
+ * stores as `component_id`.
+ * @param candidateIds - The candidate page ids, in the order the components
+ *   are numbered in; each an integer in `0..=4294967294`.
+ * @param redirects - The redirect and alias hops of the whole archive,
+ *   `[source, destination, source, destination, ...]` by page id. A source
+ *   listed twice keeps its last hop.
+ * @returns The run.
+ * @throws {RangeError} When an id is not an integer in `0..=4294967294`
+ *   (`Uint32Array` would otherwise wrap it silently).
+ * @example
+ * ```ts
+ * // Candidates 10, 20, 30; page 40 redirects to 30 and is not a candidate.
+ * const run = createIsolatedClusterRun([10, 20, 30], [40, 30]);
+ * run.unionEdges([10, 20, 20, 40]);
+ * run.labels(); // Uint32Array [0, 0, 0]
+ * ```
+ */
+export declare function createIsolatedClusterRun(candidateIds: ArrayLike<number>, redirects: ArrayLike<number>): IsolatedClusterRun;

package/lib/create-isolated-cluster-run.js

@@ -0,0 +1,52 @@
+import { nativeBinding } from './native-binding.js';
+import { toU32Ids } from './to-u32-ids.js';
+/**
+ * Starts the computation of the connected components of the isolated pages:
+ * the inventory pages that are linked to only from other inventory pages.
+ *
+ * The caller reads the link edges (`anchor_edges`) from SQLite batch by batch
+ * and hands each batch to {@link IsolatedClusterRun.unionEdges} as it
+ * arrives, so the edges are never held: the memory follows the number of pages,
+ * not the number of links. An edge to a redirect source or an alias member
+ * counts as an edge to the page it finally lands on; a chain that never ends
+ * (it loops, or leads into a loop) drops the edge. The components do not
+ * depend on the order of the edges or how they were batched.
+ *
+ * The components are numbered in the order of the candidates: the first
+ * candidate's component is `0`, and each later component takes the next
+ * number the first time one of its candidates appears. Hand the candidates
+ * over in ascending page id, which is the numbering the viewer read model
+ * stores as `component_id`.
+ * @param candidateIds - The candidate page ids, in the order the components
+ *   are numbered in; each an integer in `0..=4294967294`.
+ * @param redirects - The redirect and alias hops of the whole archive,
+ *   `[source, destination, source, destination, ...]` by page id. A source
+ *   listed twice keeps its last hop.
+ * @returns The run.
+ * @throws {RangeError} When an id is not an integer in `0..=4294967294`
+ *   (`Uint32Array` would otherwise wrap it silently).
+ * @example
+ * ```ts
+ * // Candidates 10, 20, 30; page 40 redirects to 30 and is not a candidate.
+ * const run = createIsolatedClusterRun([10, 20, 30], [40, 30]);
+ * run.unionEdges([10, 20, 20, 40]);
+ * run.labels(); // Uint32Array [0, 0, 0]
+ * ```
+ */
+export function createIsolatedClusterRun(candidateIds, redirects) {
+    if (redirects.length % 2 !== 0) {
+        throw new RangeError('redirects must hold an even number of ids');
+    }
+    const native = new nativeBinding.IsolatedClusterRun(toU32Ids(candidateIds, 'candidate ids'), toU32Ids(redirects, 'redirects'));
+    return {
+        unionEdges(edges) {
+            if (edges.length % 2 !== 0) {
+                throw new RangeError('edges must hold an even number of ids');
+            }
+            native.unionEdges(toU32Ids(edges, 'edges'));
+        },
+        labels() {
+            return native.labels();
+        },
+    };
+}