@nitpicker/archive 0.0.0 → 0.25.1

package/lib/get-failed-page-messages.js

@@ -0,0 +1,146 @@
+/** chunk size for `WHERE … IN (?)` SQLite parameter packing. */
+const CHUNK_SIZE = 500;
+/**
+ * Bulk-resolve a raw error message (plus its timestamp) for each given page
+ * id, using only sources reachable from a {@link Knex} handle. Read order:
+ * `page_errors` (keyed by `pageId`, the most direct signal a scrape attempt
+ * recorded), then `crawl_errors` (keyed by `url`, the crawler-channel
+ * record for failures that happened before a page row was scraped).
+ *
+ * **Known limitation — pre-`crawl_errors` archives**: This helper does NOT
+ * read `error.log`. The `crawl_errors` table is created empty (by
+ * `initSchema` on fresh archives, by `scripts/migrate-to-0.13.mjs` on
+ * migrated ones) and historical lines from `error.log` are never
+ * back-filled, so an archive whose failures live only in `error.log`
+ * will resolve every id to "no message" here. The
+ * downstream `Database.resetFailedPages` treats absence as `unknown` (still
+ * retryable), so legacy archives lose the permanent-kind exclusion until a
+ * fresh crawl run populates `crawl_errors` / `page_errors`. The trade-off
+ * (no error.log parsing in the writer path) keeps the writer dependency
+ * surface narrow and avoids re-implementing the parser already living in
+ * `@nitpicker/query`'s `resolveFailedPageMessages` — which the crawler
+ * package cannot import (reverse-direction dependency). When this matters
+ * in practice, run the archive through one fresh `crawl --retry-failed`
+ * pass first to populate the structured tables.
+ *
+ * Pages with no message in any consulted source are simply absent from the
+ * returned map; callers treat the absence as "unclassifiable, keep retrying"
+ * (i.e. `unknown`).
+ * @param instance - The {@link Knex} handle.
+ * @param ids - Candidate `pages.id` values.
+ * @param urls - The corresponding `pages.url` values, in the same order as
+ *   `ids`. Length and indexing MUST match `ids` so the page → url join can be
+ *   reconstructed without a second `pages` round-trip.
+ * @returns `Map<pageId, FailedPageMessage>` populated only for ids whose
+ *   message was found in one of the consulted tables.
+ * @example
+ * ```ts
+ * const messages = await getFailedPageMessages(
+ *   instance,
+ *   candidates.map(c => c.id),
+ *   candidates.map(c => c.url),
+ * );
+ * ```
+ */
+export async function getFailedPageMessages(instance, ids, urls) {
+    if (ids.length === 0) {
+        return new Map();
+    }
+    if (ids.length !== urls.length) {
+        throw new Error(`getFailedPageMessages: ids.length (${ids.length}) !== urls.length (${urls.length}) — must be 1:1`);
+    }
+    const messageByPageId = new Map();
+    if (await instance.schema.hasTable('page_errors')) {
+        for (let i = 0; i < ids.length; i += CHUNK_SIZE) {
+            const chunk = ids.slice(i, i + CHUNK_SIZE);
+            // `orderBy('id', 'asc')` makes the per-pageId "first row seen"
+            // behavior deterministic regardless of SQLite's natural ROWID
+            // scan order, which is otherwise implementation-defined under
+            // concurrent / migrated archives. Without the explicit order, a
+            // reset that classified a page as `unknown` once could classify
+            // it as `parse-error` on the next run when the rows happen to be
+            // returned in a different order.
+            const rows = (await instance('page_errors')
+                .select('pageId', 'message', 'createdAt')
+                .whereIn('pageId', chunk)
+                .orderBy('id', 'asc'));
+            for (const row of rows) {
+                // Earliest-id wins. Schema permits multiple rows per pageId
+                // (the same scrape can record several phase errors); the
+                // first row inserted is usually the trigger cause, later
+                // rows are follow-on noise from the same failure cascade.
+                //
+                // An empty `message` is treated as "no signal" and ignored
+                // so the crawl_errors lookup can fill it in. Without this,
+                // a page_errors row with `message=''` (recorded by a
+                // scraper phase that fired its trigger but had no error
+                // text) would short-circuit and we'd lose access to the
+                // crawl_errors row that classifies the failure as
+                // `dns` / `tls` / `client-blocked` etc. — defeating
+                // `--retry-failed`'s permanent-kind exclusion.
+                if (row.message !== '' && !messageByPageId.has(row.pageId)) {
+                    messageByPageId.set(row.pageId, {
+                        message: row.message,
+                        createdAt: row.createdAt,
+                    });
+                }
+            }
+        }
+    }
+    const idsMissing = ids.filter((id) => !messageByPageId.has(id));
+    if (idsMissing.length === 0 || !(await instance.schema.hasTable('crawl_errors'))) {
+        // Early-exit short-circuits BOTH the idToUrl Map construction and
+        // the crawl_errors round-trip. On a 1M-page archive where every
+        // failed page already has a `page_errors` row, this avoids walking
+        // the candidate list a second time.
+        return messageByPageId;
+    }
+    const idToUrl = new Map();
+    for (const [i, id] of ids.entries()) {
+        const url = urls[i];
+        if (url !== undefined) {
+            idToUrl.set(id, url);
+        }
+    }
+    const missingUrls = [];
+    for (const id of idsMissing) {
+        const url = idToUrl.get(id);
+        if (url !== undefined) {
+            missingUrls.push(url);
+        }
+    }
+    const urlToMessage = new Map();
+    for (let i = 0; i < missingUrls.length; i += CHUNK_SIZE) {
+        const chunk = missingUrls.slice(i, i + CHUNK_SIZE);
+        const rows = (await instance('crawl_errors')
+            .select('url', 'message', 'createdAt')
+            .whereIn('url', chunk));
+        for (const row of rows) {
+            if (row.url === null) {
+                continue;
+            }
+            // Latest-createdAt wins (fixes a previously-undefined
+            // selection among duplicate URLs — SQLite's natural scan
+            // order is implementation-defined). The most recent message
+            // is the most relevant one for both classification and outage
+            // attribution: an old NXDOMAIN followed by a network-outage
+            // blip should resolve to the outage-era message, not whichever
+            // happened to be inserted first.
+            const existing = urlToMessage.get(row.url);
+            if (existing === undefined || row.createdAt > existing.createdAt) {
+                urlToMessage.set(row.url, { message: row.message, createdAt: row.createdAt });
+            }
+        }
+    }
+    for (const id of idsMissing) {
+        const url = idToUrl.get(id);
+        if (url === undefined) {
+            continue;
+        }
+        const resolved = urlToMessage.get(url);
+        if (resolved !== undefined) {
+            messageByPageId.set(id, resolved);
+        }
+    }
+    return messageByPageId;
+}

package/lib/get-json.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Safely parses a JSON string, returning a fallback value if parsing fails or the input is not a string.
+ * Logs a warning via {@link dbLog} when invalid JSON is detected, including a truncated preview
+ * of the data and the parse error message.
+ * @template T The expected type of the parsed JSON value and the fallback.
+ * @param data - The data to parse. Only string values are parsed; other types return the fallback.
+ * @param fallback - The value to return if parsing fails or the result is falsy.
+ * @returns The parsed JSON value, or the fallback.
+ */
+export declare function getJSON<T>(data: unknown, fallback: T): T;

package/lib/get-json.js

@@ -0,0 +1,25 @@
+import { dbLog } from './debug.js';
+/**
+ * Safely parses a JSON string, returning a fallback value if parsing fails or the input is not a string.
+ * Logs a warning via {@link dbLog} when invalid JSON is detected, including a truncated preview
+ * of the data and the parse error message.
+ * @template T The expected type of the parsed JSON value and the fallback.
+ * @param data - The data to parse. Only string values are parsed; other types return the fallback.
+ * @param fallback - The value to return if parsing fails or the result is falsy.
+ * @returns The parsed JSON value, or the fallback.
+ */
+export function getJSON(data, fallback) {
+    try {
+        if (typeof data === 'string') {
+            const result = JSON.parse(data);
+            if (result) {
+                return result;
+            }
+            return fallback;
+        }
+    }
+    catch (error) {
+        dbLog('Warning: Invalid JSON detected in database field. Using fallback value. Data: %s, Error: %s', String(data).slice(0, 200), error instanceof Error ? error.message : String(error));
+    }
+    return fallback;
+}

package/lib/html-snapshot/match-selector-html.d.ts

@@ -0,0 +1,25 @@
+import type { HtmlMatchOutcome, SelectorPlan } from './types.js';
+/**
+ * Decides whether any element of one stored HTML document matches a planned
+ * selector list, using the cheapest stage that is exact: an ordered-literal
+ * prefilter, then the start tags alone for selectors one tag decides, then
+ * an open-element stack. The matcher itself is native (`@nitpicker/core`).
+ *
+ * The result is a judgement about the stored string read as markup with
+ * balanced tags (the interpretation rules are in `@nitpicker/cli`'s
+ * `docs/query.md`), not a DOM query. Tag and attribute names ignore ASCII
+ * case only.
+ * @param options - The plan and the document.
+ * @param options.plan - The validated selector list.
+ * @param options.html - The stored markup, as a string or as UTF-8 bytes.
+ * @returns The verdict, which stages ran, and how many elements the stack tested.
+ * @throws {Error} With code `InvalidArg` if the plan is malformed.
+ * @example
+ * ```ts
+ * const { matched } = matchSelectorHtml({ plan, html: '<p><img src="a.png"></p>' });
+ * ```
+ */
+export declare function matchSelectorHtml(options: {
+    readonly plan: SelectorPlan;
+    readonly html: string | Uint8Array;
+}): HtmlMatchOutcome;

package/lib/html-snapshot/match-selector-html.js

@@ -0,0 +1,28 @@
+import { matchSelectorHtml as matchSelectorHtmlNatively } from '@nitpicker/core/match-selector-html';
+/**
+ * Decides whether any element of one stored HTML document matches a planned
+ * selector list, using the cheapest stage that is exact: an ordered-literal
+ * prefilter, then the start tags alone for selectors one tag decides, then
+ * an open-element stack. The matcher itself is native (`@nitpicker/core`).
+ *
+ * The result is a judgement about the stored string read as markup with
+ * balanced tags (the interpretation rules are in `@nitpicker/cli`'s
+ * `docs/query.md`), not a DOM query. Tag and attribute names ignore ASCII
+ * case only.
+ * @param options - The plan and the document.
+ * @param options.plan - The validated selector list.
+ * @param options.html - The stored markup, as a string or as UTF-8 bytes.
+ * @returns The verdict, which stages ran, and how many elements the stack tested.
+ * @throws {Error} With code `InvalidArg` if the plan is malformed.
+ * @example
+ * ```ts
+ * const { matched } = matchSelectorHtml({ plan, html: '<p><img src="a.png"></p>' });
+ * ```
+ */
+export function matchSelectorHtml(options) {
+    // Passing archive's types to core's wrapper, and taking its result as
+    // archive's type, is the check that the two still mirror each other: a
+    // drift in either direction fails to compile here.
+    const outcome = matchSelectorHtmlNatively(options);
+    return outcome;
+}

package/lib/html-snapshot/match-selector-snapshots.d.ts

@@ -0,0 +1,33 @@
+import type { SelectorPlan, SnapshotMatchOutcome, StoredHtmlSnapshot } from './types.js';
+/**
+ * Judges a batch of stored HTML snapshots (rows of `page_html_blobs`)
+ * against a planned selector list: each is decompressed, read as UTF-8 and
+ * judged as {@link import('./match-selector-html.js').matchSelectorHtml}
+ * does, in parallel on the native thread pool, one decoded document per
+ * thread at a time.
+ *
+ * A snapshot that cannot be decompressed, or has a codec other than `zstd`
+ * or `none`, fails the whole call; it is never judged "no match".
+ * @param options - The plan and the batch.
+ * @param options.plan - The validated selector list.
+ * @param options.snapshots - The stored snapshots, in the order the verdicts are returned.
+ * @param options.signal - Stops the call at its next snapshot, or within the next mebibyte of a decompression under way; a call still waiting for its turn stops when the turn comes.
+ * @returns One verdict per snapshot, in input order.
+ * @throws {Error} If a codec is not `zstd` or `none`, or the batch takes more than 4 GiB.
+ *   The returned promise rejects (`snapshot <n> could not be decoded`) if a snapshot's
+ *   zstd data is corrupt or decompresses past `MAX_DECODED_SNAPSHOT_BYTES`, or with code
+ *   `InvalidArg` if the plan is malformed, and with the signal's reason if `signal` aborted
+ *   before the call finished.
+ * @example
+ * ```ts
+ * const verdicts = await matchSelectorSnapshots({
+ * 	plan,
+ * 	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+ * });
+ * ```
+ */
+export declare function matchSelectorSnapshots(options: {
+    readonly plan: SelectorPlan;
+    readonly snapshots: readonly StoredHtmlSnapshot[];
+    readonly signal?: AbortSignal;
+}): Promise<SnapshotMatchOutcome[]>;

package/lib/html-snapshot/match-selector-snapshots.js

@@ -0,0 +1,33 @@
+import { matchSelectorSnapshots as matchSelectorSnapshotsNatively } from '@nitpicker/core/match-selector-snapshots';
+/**
+ * Judges a batch of stored HTML snapshots (rows of `page_html_blobs`)
+ * against a planned selector list: each is decompressed, read as UTF-8 and
+ * judged as {@link import('./match-selector-html.js').matchSelectorHtml}
+ * does, in parallel on the native thread pool, one decoded document per
+ * thread at a time.
+ *
+ * A snapshot that cannot be decompressed, or has a codec other than `zstd`
+ * or `none`, fails the whole call; it is never judged "no match".
+ * @param options - The plan and the batch.
+ * @param options.plan - The validated selector list.
+ * @param options.snapshots - The stored snapshots, in the order the verdicts are returned.
+ * @param options.signal - Stops the call at its next snapshot, or within the next mebibyte of a decompression under way; a call still waiting for its turn stops when the turn comes.
+ * @returns One verdict per snapshot, in input order.
+ * @throws {Error} If a codec is not `zstd` or `none`, or the batch takes more than 4 GiB.
+ *   The returned promise rejects (`snapshot <n> could not be decoded`) if a snapshot's
+ *   zstd data is corrupt or decompresses past `MAX_DECODED_SNAPSHOT_BYTES`, or with code
+ *   `InvalidArg` if the plan is malformed, and with the signal's reason if `signal` aborted
+ *   before the call finished.
+ * @example
+ * ```ts
+ * const verdicts = await matchSelectorSnapshots({
+ * 	plan,
+ * 	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+ * });
+ * ```
+ */
+export function matchSelectorSnapshots(options) {
+    // Passing archive's types to core's wrapper, and taking its result as
+    // archive's type, is the check that the two still mirror each other.
+    return matchSelectorSnapshotsNatively(options);
+}

package/lib/html-snapshot/search-html-document.d.ts

@@ -0,0 +1,29 @@
+import type { SearchPattern, SnapshotSearchOutcome } from './types.js';
+/**
+ * Counts the occurrences of a search pattern in one stored HTML document and
+ * cuts a snippet around the first. The document is read as UTF-8 (an invalid
+ * sequence becomes U+FFFD); positions and lengths are in Unicode scalar
+ * values; `matchCount` counts non-overlapping matches; the snippet is a
+ * window of `snippetLength` characters centred on the first match, with
+ * whitespace collapsed and the ends trimmed.
+ * @param options - The pattern and the document.
+ * @param options.pattern - The pattern and its flags.
+ * @param options.html - The stored markup, as a string or as UTF-8 bytes.
+ * @param options.snippetLength - Window size in characters.
+ * @returns The match count and the snippet (empty when nothing matched).
+ * @throws {Error} With code `InvalidArg` if the pattern cannot be compiled.
+ * @example
+ * ```ts
+ * const { matchCount } = searchHtmlDocument({
+ * 	pattern: { source: 'a+', literal: false, ignoreCase: false, multiLine: false, dotAll: false },
+ * 	html: '<p>aa b a</p>',
+ * 	snippetLength: 20,
+ * });
+ * matchCount; // 2
+ * ```
+ */
+export declare function searchHtmlDocument(options: {
+    readonly pattern: SearchPattern;
+    readonly html: string | Uint8Array;
+    readonly snippetLength: number;
+}): SnapshotSearchOutcome;

package/lib/html-snapshot/search-html-document.js

@@ -0,0 +1,27 @@
+import { searchHtmlDocument as searchHtmlDocumentNatively } from '@nitpicker/core/search-html-document';
+/**
+ * Counts the occurrences of a search pattern in one stored HTML document and
+ * cuts a snippet around the first. The document is read as UTF-8 (an invalid
+ * sequence becomes U+FFFD); positions and lengths are in Unicode scalar
+ * values; `matchCount` counts non-overlapping matches; the snippet is a
+ * window of `snippetLength` characters centred on the first match, with
+ * whitespace collapsed and the ends trimmed.
+ * @param options - The pattern and the document.
+ * @param options.pattern - The pattern and its flags.
+ * @param options.html - The stored markup, as a string or as UTF-8 bytes.
+ * @param options.snippetLength - Window size in characters.
+ * @returns The match count and the snippet (empty when nothing matched).
+ * @throws {Error} With code `InvalidArg` if the pattern cannot be compiled.
+ * @example
+ * ```ts
+ * const { matchCount } = searchHtmlDocument({
+ * 	pattern: { source: 'a+', literal: false, ignoreCase: false, multiLine: false, dotAll: false },
+ * 	html: '<p>aa b a</p>',
+ * 	snippetLength: 20,
+ * });
+ * matchCount; // 2
+ * ```
+ */
+export function searchHtmlDocument(options) {
+    return searchHtmlDocumentNatively(options);
+}

package/lib/html-snapshot/search-html-snapshots.d.ts

@@ -0,0 +1,36 @@
+import type { SearchPattern, SnapshotSearchOutcome, StoredHtmlSnapshot } from './types.js';
+/**
+ * Searches a batch of stored HTML snapshots (rows of `page_html_blobs`) for
+ * a pattern: each is decompressed, read as UTF-8 and searched as
+ * {@link import('./search-html-document.js').searchHtmlDocument} does, in
+ * parallel on the native thread pool, one decoded document per thread at a
+ * time.
+ *
+ * A snapshot that cannot be decompressed, or has a codec other than `zstd`
+ * or `none`, fails the whole call; it is never reported as "no match".
+ * @param options - The pattern, the snippet size and the batch.
+ * @param options.pattern - The pattern and its flags.
+ * @param options.snippetLength - Window size in characters.
+ * @param options.snapshots - The stored snapshots, in the order the outcomes are returned.
+ * @param options.signal - Stops the call at its next snapshot, or within the next mebibyte of a decompression under way; a call still waiting for its turn stops when the turn comes.
+ * @returns One outcome per snapshot, in input order; `matchCount` is 0 where nothing matched.
+ * @throws {Error} If a codec is not `zstd` or `none`, or the batch takes more than 4 GiB.
+ *   The returned promise rejects (`snapshot <n> could not be decoded`) if a snapshot's
+ *   zstd data is corrupt or decompresses past `MAX_DECODED_SNAPSHOT_BYTES`, or with code
+ *   `InvalidArg` if the pattern cannot be compiled, and with the signal's reason if `signal`
+ *   aborted before the call finished.
+ * @example
+ * ```ts
+ * const outcomes = await searchHtmlSnapshots({
+ * 	pattern: { source: 'gtag(', literal: true, ignoreCase: false, multiLine: false, dotAll: false },
+ * 	snippetLength: 160,
+ * 	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+ * });
+ * ```
+ */
+export declare function searchHtmlSnapshots(options: {
+    readonly pattern: SearchPattern;
+    readonly snippetLength: number;
+    readonly snapshots: readonly StoredHtmlSnapshot[];
+    readonly signal?: AbortSignal;
+}): Promise<SnapshotSearchOutcome[]>;

package/lib/html-snapshot/search-html-snapshots.js

@@ -0,0 +1,35 @@
+import { searchHtmlSnapshots as searchHtmlSnapshotsNatively } from '@nitpicker/core/search-html-snapshots';
+/**
+ * Searches a batch of stored HTML snapshots (rows of `page_html_blobs`) for
+ * a pattern: each is decompressed, read as UTF-8 and searched as
+ * {@link import('./search-html-document.js').searchHtmlDocument} does, in
+ * parallel on the native thread pool, one decoded document per thread at a
+ * time.
+ *
+ * A snapshot that cannot be decompressed, or has a codec other than `zstd`
+ * or `none`, fails the whole call; it is never reported as "no match".
+ * @param options - The pattern, the snippet size and the batch.
+ * @param options.pattern - The pattern and its flags.
+ * @param options.snippetLength - Window size in characters.
+ * @param options.snapshots - The stored snapshots, in the order the outcomes are returned.
+ * @param options.signal - Stops the call at its next snapshot, or within the next mebibyte of a decompression under way; a call still waiting for its turn stops when the turn comes.
+ * @returns One outcome per snapshot, in input order; `matchCount` is 0 where nothing matched.
+ * @throws {Error} If a codec is not `zstd` or `none`, or the batch takes more than 4 GiB.
+ *   The returned promise rejects (`snapshot <n> could not be decoded`) if a snapshot's
+ *   zstd data is corrupt or decompresses past `MAX_DECODED_SNAPSHOT_BYTES`, or with code
+ *   `InvalidArg` if the pattern cannot be compiled, and with the signal's reason if `signal`
+ *   aborted before the call finished.
+ * @example
+ * ```ts
+ * const outcomes = await searchHtmlSnapshots({
+ * 	pattern: { source: 'gtag(', literal: true, ignoreCase: false, multiLine: false, dotAll: false },
+ * 	snippetLength: 160,
+ * 	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+ * });
+ * ```
+ */
+export function searchHtmlSnapshots(options) {
+    // Passing archive's types to core's wrapper, and taking its result as
+    // archive's type, is the check that the two still mirror each other.
+    return searchHtmlSnapshotsNatively(options);
+}

package/lib/html-snapshot/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Types of the stored-HTML matcher, defined here so `@nitpicker/query` and
+ * the CLI never depend on `@nitpicker/core`'s own types. Each is structurally
+ * identical to its counterpart in core; the wrappers in this directory pass
+ * values across, so a drift fails to compile there.
+ */
+/** 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[];
+    /**
+     * 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.
+     */
+    readonly prefilterLiterals: readonly string[] | null;
+    /**
+     * Whether one start tag decides this alternative: a single compound with
+     * no position test whose attribute values have a single stored form.
+     */
+    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;
+}
+/** 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 SearchPattern {
+    /** 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;
+}

package/lib/html-snapshot/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types of the stored-HTML matcher, defined here so `@nitpicker/query` and
+ * the CLI never depend on `@nitpicker/core`'s own types. Each is structurally
+ * identical to its counterpart in core; the wrappers in this directory pass
+ * values across, so a drift fails to compile there.
+ */
+export {};

package/lib/html-snapshot/validate-search-pattern.d.ts

@@ -0,0 +1,15 @@
+import type { SearchPattern } from './types.js';
+/**
+ * Compiles a `query search-html` pattern and reports whether it matches the
+ * empty string. The pattern is a literal, or a regular expression in the
+ * syntax of Rust's `regex` crate (no backreferences or look-around).
+ * @param pattern - The pattern and its flags.
+ * @returns Whether the pattern matches the empty string, which `search-html` rejects.
+ * @throws {Error} With code `InvalidArg` and the regex engine's message if the
+ *   pattern is not valid, uses an unsupported construct, or is too large.
+ * @example
+ * ```ts
+ * validateSearchPattern({ source: 'a*', literal: false, ignoreCase: false, multiLine: false, dotAll: false }); // true
+ * ```
+ */
+export declare function validateSearchPattern(pattern: SearchPattern): boolean;

package/lib/html-snapshot/validate-search-pattern.js

@@ -0,0 +1,17 @@
+import { validateSearchPattern as validateSearchPatternNatively } from '@nitpicker/core/validate-search-pattern';
+/**
+ * Compiles a `query search-html` pattern and reports whether it matches the
+ * empty string. The pattern is a literal, or a regular expression in the
+ * syntax of Rust's `regex` crate (no backreferences or look-around).
+ * @param pattern - The pattern and its flags.
+ * @returns Whether the pattern matches the empty string, which `search-html` rejects.
+ * @throws {Error} With code `InvalidArg` and the regex engine's message if the
+ *   pattern is not valid, uses an unsupported construct, or is too large.
+ * @example
+ * ```ts
+ * validateSearchPattern({ source: 'a*', literal: false, ignoreCase: false, multiLine: false, dotAll: false }); // true
+ * ```
+ */
+export function validateSearchPattern(pattern) {
+    return validateSearchPatternNatively(pattern);
+}

package/lib/init-schema.d.ts

@@ -0,0 +1,48 @@
+import type { Knex } from 'knex';
+/**
+ * Initializes the archive database schema if tables do not exist.
+ *
+ * The schema is composed of five groups, each owned by a dedicated DDL
+ * function so the migration script (`scripts/migrate-to-0.13.mjs`) can
+ * provision the exact same shapes on archives it upgrades:
+ *
+ * - **`info`** (inline below): single-row crawl configuration.
+ * - **Ref / header dictionary tables** ({@link createRefTables}):
+ *   `url_refs`, `content_type_refs`, `text_refs`, `json_refs`,
+ *   `blob_refs`, `header_name_refs`, `header_value_refs`, `header_sets`,
+ *   `header_set_entries`, `header_flags`. See that file for column-level
+ *   rationale and the reason `blob_refs` uses a regular rowid PK instead
+ *   of WITHOUT ROWID.
+ * - **Entity / edge tables** ({@link createEntityTables}):
+ *   `content_items`, `page_meta`, `resource_items`, `anchor_edges`,
+ *   `resource_ref_edges`, `image_items` — the write-model the crawler
+ *   writes during a crawl and every reader queries. Must run AFTER
+ *   `createRefTables` because most entity tables reference ref-table PKs.
+ * - **Adjunct tables** ({@link createAdjunctTables}): `page_errors`,
+ *   `crawl_errors`, `technology_signals`, `page_technologies`, `page_jsonld`, `list_reconcile_runs`,
+ *   `page_html_blobs` +
+ *   `page_html_ref`. Must run AFTER `createEntityTables` because the
+ *   page-scoped tables FK into `content_items(id)`.
+ * - **Template classification tables** ({@link createTemplateTables}):
+ *   `page_templates`, `page_template_clusters`, `page_template_labels` —
+ *   the crawl-end DOM-structure classification, kept apart from the
+ *   adjunct tables because it has its own producer and write path.
+ *
+ * The legacy flat write-model tables (`pages` / `anchors` / `images` /
+ * `resources` / `resources-referrers`) are deliberately NOT created:
+ * they only exist inside pre-0.13 archives, where they serve as the
+ * populate source for `scripts/migrate-to-0.13.mjs` before that script
+ * drops them.
+ *
+ * **PRAGMA `page_size` and `journal_mode`** are set BEFORE any
+ * `CREATE TABLE` because SQLite only honors `page_size` changes against
+ * an empty database, and `journal_mode = WAL` is persistent. Other
+ * per-connection PRAGMAs live in {@link applyConnectionPragmas}.
+ *
+ * Pre-0.13 migration is intentionally absent. `assertCompatibleVersion`
+ * (called before `initSchema`) rejects older archives with a friendly
+ * error naming the migration scripts to run; `v0.x` policy allows
+ * breaking changes.
+ * @param instance - The Knex query builder instance connected to the database.
+ */
+export declare function initSchema(instance: Knex): Promise<void>;