@nitpicker/archive 0.0.0 → 0.25.0

package/lib/meta/extract-tags-for-archive.d.ts

@@ -0,0 +1,17 @@
+import type { TagRowForInsert, TagsMeta } from './types.js';
+/**
+ * Flattens {@link TagsMeta.entries} (per provider × external-id tuple) into
+ * insert-ready rows for the `page_tags` table.
+ *
+ * One Wappalyzer entry → one row. `entry.id` becomes `externalId`. `category`
+ * is the first element of `categories`; the full list is preserved in the
+ * `categories` JSON column. `sources` is preserved verbatim as a JSON column.
+ *
+ * `pageId` is **not** filled here — the database layer injects it because the
+ * page row is `INSERT`-ed in the same transaction and its ID is known only at
+ * insert time.
+ * @param tags - The `meta.tags` object from beholder.
+ * @returns Rows ready for the `page_tags` insert; empty array when no tags
+ *   were detected.
+ */
+export declare function extractTagsForArchive(tags: TagsMeta | undefined): ReadonlyArray<Omit<TagRowForInsert, 'pageId'>>;

package/lib/meta/extract-tags-for-archive.js

@@ -0,0 +1,36 @@
+/**
+ * Flattens {@link TagsMeta.entries} (per provider × external-id tuple) into
+ * insert-ready rows for the `page_tags` table.
+ *
+ * One Wappalyzer entry → one row. `entry.id` becomes `externalId`. `category`
+ * is the first element of `categories`; the full list is preserved in the
+ * `categories` JSON column. `sources` is preserved verbatim as a JSON column.
+ *
+ * `pageId` is **not** filled here — the database layer injects it because the
+ * page row is `INSERT`-ed in the same transaction and its ID is known only at
+ * insert time.
+ * @param tags - The `meta.tags` object from beholder.
+ * @returns Rows ready for the `page_tags` insert; empty array when no tags
+ *   were detected.
+ */
+export function extractTagsForArchive(tags) {
+    // `tags` can be undefined when fed legacy minimal-Meta test fixtures.
+    // Real beholder 3.0.0 always populates this required field.
+    const entries = tags?.entries ?? [];
+    if (entries.length === 0)
+        return [];
+    return entries.map((entry) => ({
+        provider: entry.provider,
+        category: entry.categories[0] ?? null,
+        externalId: entry.id ?? null,
+        version: entry.version ?? null,
+        confidence: entry.confidence ?? null,
+        categories: [...entry.categories],
+        sources: entry.sources.map((s) => ({
+            type: s.type,
+            src: s.src,
+            location: s.location,
+            globalName: s.globalName,
+        })),
+    }));
+}

package/lib/meta/parse-main-content-class-list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Decodes the `page_meta.main_content_class_list` column — the detected
+ * main-content element's CSS classes, stored as a JSON array — shared by
+ * `Page.mainContentClassList` and template classification's page loader so
+ * both read the column the same way.
+ *
+ * The crawler writes the column with `JSON.stringify` on a string array, so
+ * anything else is a corrupt archive; it throws rather than guessing, since
+ * a silently dropped class list would change which template a page lands in.
+ * @param raw - The column value; `null` when no main region was detected.
+ * @returns The class names, or `null` when no main region was detected.
+ * @throws {Error} When the value is not a JSON array of strings.
+ * @example
+ * ```ts
+ * parseMainContentClassList('["spc","wide"]'); // ['spc', 'wide']
+ * parseMainContentClassList(null); // null
+ * ```
+ */
+export declare function parseMainContentClassList(raw: string | null): string[] | null;

package/lib/meta/parse-main-content-class-list.js

@@ -0,0 +1,34 @@
+/**
+ * Decodes the `page_meta.main_content_class_list` column — the detected
+ * main-content element's CSS classes, stored as a JSON array — shared by
+ * `Page.mainContentClassList` and template classification's page loader so
+ * both read the column the same way.
+ *
+ * The crawler writes the column with `JSON.stringify` on a string array, so
+ * anything else is a corrupt archive; it throws rather than guessing, since
+ * a silently dropped class list would change which template a page lands in.
+ * @param raw - The column value; `null` when no main region was detected.
+ * @returns The class names, or `null` when no main region was detected.
+ * @throws {Error} When the value is not a JSON array of strings.
+ * @example
+ * ```ts
+ * parseMainContentClassList('["spc","wide"]'); // ['spc', 'wide']
+ * parseMainContentClassList(null); // null
+ * ```
+ */
+export function parseMainContentClassList(raw) {
+    if (raw === null) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`main_content_class_list is not valid JSON: ${raw}`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((name) => typeof name !== 'string')) {
+        throw new Error(`main_content_class_list is not a JSON array of strings: ${raw}`);
+    }
+    return parsed;
+}

package/lib/meta/summarize-jsonld.d.ts

@@ -0,0 +1,17 @@
+import type { JsonLdRow, JsonLdSummary } from './types.js';
+/**
+ * Builds the {@link JsonLdSummary} object returned by `get-page-detail` from a
+ * page's JSON-LD rows.
+ *
+ * Why summary: the raw payload of a single page's JSON-LD can reach several
+ * MB on e-commerce sites (Amazon product page = 50 schemas × 50KB). Returning
+ * that inline blows up MCP / LLM token budgets. The summary preserves the
+ * shape of the data (counts + unique types + parse error count) so consumers
+ * can decide whether to drill in via `get-page-jsonld(url)`.
+ *
+ * Entries with `type === null` are surfaced as `'(unknown)'` so the type
+ * list is enumerable without sentinel handling on the consumer side.
+ * @param rows - All `page_jsonld` rows for one page.
+ * @returns Summary with `count`, sorted unique `types[]`, and `parseErrorCount`.
+ */
+export declare function summarizeJsonLd(rows: readonly JsonLdRow[]): JsonLdSummary;

package/lib/meta/summarize-jsonld.js

@@ -0,0 +1,29 @@
+/**
+ * Builds the {@link JsonLdSummary} object returned by `get-page-detail` from a
+ * page's JSON-LD rows.
+ *
+ * Why summary: the raw payload of a single page's JSON-LD can reach several
+ * MB on e-commerce sites (Amazon product page = 50 schemas × 50KB). Returning
+ * that inline blows up MCP / LLM token budgets. The summary preserves the
+ * shape of the data (counts + unique types + parse error count) so consumers
+ * can decide whether to drill in via `get-page-jsonld(url)`.
+ *
+ * Entries with `type === null` are surfaced as `'(unknown)'` so the type
+ * list is enumerable without sentinel handling on the consumer side.
+ * @param rows - All `page_jsonld` rows for one page.
+ * @returns Summary with `count`, sorted unique `types[]`, and `parseErrorCount`.
+ */
+export function summarizeJsonLd(rows) {
+    const types = new Set();
+    let parseErrorCount = 0;
+    for (const row of rows) {
+        types.add(row.type ?? '(unknown)');
+        if (row.parseError !== null)
+            parseErrorCount++;
+    }
+    return {
+        count: rows.length,
+        types: [...types].toSorted(),
+        parseErrorCount,
+    };
+}

package/lib/meta/technologies/combine-technology-confidence.d.ts

@@ -0,0 +1,46 @@
+import type { PageTechnologyPartial, TechnologySignalPartial } from './types.js';
+/**
+ * Options for {@link combineTechnologyConfidence}.
+ */
+export interface CombineTechnologyConfidenceOptions {
+    /**
+     * Skip the `TECHNOLOGY_CONFIDENCE_THRESHOLD` drop. Set by the `page_tags`
+     * legacy-migration callers (`migrate-page-tags-to-page-technologies.ts`,
+     * `retarget-legacy-fk-tables.ts`): the threshold exists to filter noisy
+     * NEW detections at crawl time, but migration is converting Wappalyzer
+     * detections the old `page_tags`-based API already returned
+     * unconditionally (including low-confidence ones) — dropping them here
+     * would silently and permanently lose data with no recovery path (v0.x
+     * policy is read-time migration only, no retroactive re-crawl).
+     */
+    skipThreshold?: boolean;
+}
+/**
+ * Combines every signal detected for one technology on one page into a
+ * single confidence score via noisy-OR:
+ *
+ * ```
+ * confidence = round(100 * (1 - Π (1 - weight/100)))
+ * ```
+ *
+ * over each DISTINCT `signalType` present (same signal type appearing
+ * twice — e.g. two different `url-pattern` definitions both matching —
+ * counts once, at its highest weight; compounding only happens ACROSS
+ * signal types, which is what makes this "multiple independent signals
+ * agree" rather than "one noisy signal repeated"). A single signal's
+ * result equals its own weight exactly (`1 - (1 - w/100) = w/100`).
+ *
+ * Technologies whose combined confidence falls below
+ * `TECHNOLOGY_CONFIDENCE_THRESHOLD` are dropped entirely — a lone weak
+ * signal (e.g. `id="app"`, weight 15) is noise, not a detection, and
+ * `page_technologies` has no `isDetected` column to hide it behind; the
+ * row simply is not written. Pass `options.skipThreshold` to keep every
+ * technology regardless of confidence (see its docs for why).
+ * @param signals - Every signal detected for a single page, across all
+ *   technologies (this function groups by `technology` internally).
+ * @param options - See {@link CombineTechnologyConfidenceOptions}.
+ * @returns One {@link PageTechnologyPartial} per technology (filtered by
+ *   the confidence threshold unless `options.skipThreshold` is set), in no
+ *   particular order.
+ */
+export declare function combineTechnologyConfidence(signals: readonly TechnologySignalPartial[], options?: CombineTechnologyConfidenceOptions): PageTechnologyPartial[];

package/lib/meta/technologies/combine-technology-confidence.js

@@ -0,0 +1,93 @@
+import { TECHNOLOGY_CONFIDENCE_THRESHOLD } from './technology-signal-definitions.js';
+/**
+ * Priority order for picking which signal's `category`/`version` wins when
+ * more than one signal for the same technology supplies one. `wappalyzer`
+ * wins first — it is the only source with a real Wappalyzer-reported
+ * `version`; `meta-generator` second — also carries a real version
+ * (`<meta name="generator" content="Astro v4.2.0">`); the rest never
+ * carry a version and are listed only so the `.find()` below terminates
+ * deterministically regardless of definition order.
+ */
+const CATEGORY_VERSION_SOURCE_PRIORITY = [
+    'wappalyzer',
+    'meta-generator',
+    'html-marker',
+    'url-pattern',
+    'scoped-attr',
+    'js-license-comment',
+    'weak-marker',
+];
+/**
+ * Combines every signal detected for one technology on one page into a
+ * single confidence score via noisy-OR:
+ *
+ * ```
+ * confidence = round(100 * (1 - Π (1 - weight/100)))
+ * ```
+ *
+ * over each DISTINCT `signalType` present (same signal type appearing
+ * twice — e.g. two different `url-pattern` definitions both matching —
+ * counts once, at its highest weight; compounding only happens ACROSS
+ * signal types, which is what makes this "multiple independent signals
+ * agree" rather than "one noisy signal repeated"). A single signal's
+ * result equals its own weight exactly (`1 - (1 - w/100) = w/100`).
+ *
+ * Technologies whose combined confidence falls below
+ * `TECHNOLOGY_CONFIDENCE_THRESHOLD` are dropped entirely — a lone weak
+ * signal (e.g. `id="app"`, weight 15) is noise, not a detection, and
+ * `page_technologies` has no `isDetected` column to hide it behind; the
+ * row simply is not written. Pass `options.skipThreshold` to keep every
+ * technology regardless of confidence (see its docs for why).
+ * @param signals - Every signal detected for a single page, across all
+ *   technologies (this function groups by `technology` internally).
+ * @param options - See {@link CombineTechnologyConfidenceOptions}.
+ * @returns One {@link PageTechnologyPartial} per technology (filtered by
+ *   the confidence threshold unless `options.skipThreshold` is set), in no
+ *   particular order.
+ */
+export function combineTechnologyConfidence(signals, options = {}) {
+    const byTechnology = new Map();
+    for (const signal of signals) {
+        const group = byTechnology.get(signal.technology);
+        if (group) {
+            group.push(signal);
+        }
+        else {
+            byTechnology.set(signal.technology, [signal]);
+        }
+    }
+    const results = [];
+    for (const [technology, group] of byTechnology) {
+        const maxWeightByType = new Map();
+        for (const signal of group) {
+            const current = maxWeightByType.get(signal.signalType);
+            if (current === undefined || signal.weight > current) {
+                maxWeightByType.set(signal.signalType, signal.weight);
+            }
+        }
+        const product = [...maxWeightByType.values()].reduce((acc, weight) => acc * (1 - weight / 100), 1);
+        const confidence = Math.round(100 * (1 - product));
+        if (!options.skipThreshold && confidence < TECHNOLOGY_CONFIDENCE_THRESHOLD)
+            continue;
+        let categorySource;
+        let versionSource;
+        for (const type of CATEGORY_VERSION_SOURCE_PRIORITY) {
+            if (!categorySource) {
+                categorySource = group.find((s) => s.signalType === type && s.category != null);
+            }
+            if (!versionSource) {
+                versionSource = group.find((s) => s.signalType === type && s.version != null);
+            }
+            if (categorySource && versionSource)
+                break;
+        }
+        results.push({
+            technology,
+            category: categorySource?.category ?? null,
+            version: versionSource?.version ?? null,
+            confidence,
+            signalCount: maxWeightByType.size,
+        });
+    }
+    return results;
+}

package/lib/meta/technologies/convert-legacy-page-tags-to-inserts.d.ts

@@ -0,0 +1,45 @@
+import type { LegacyTagRowLike } from './convert-tag-row-to-wappalyzer-signal.js';
+/** One `technology_signals` row ready for insertion, `pageId` already resolved. */
+export interface LegacyTechnologySignalInsert {
+    pageId: number;
+    technology: string;
+    signalType: string;
+    evidence: string | null;
+    weight: number;
+}
+/** One `page_technologies` row ready for insertion, `pageId` already resolved. */
+export interface LegacyPageTechnologyInsert {
+    pageId: number;
+    technology: string;
+    category: string | null;
+    version: string | null;
+    confidence: number;
+    signalCount: number;
+}
+/** Result of {@link convertLegacyPageTagsToInserts}. */
+export interface LegacyPageTagsConversion {
+    signalInserts: LegacyTechnologySignalInsert[];
+    technologyInserts: LegacyPageTechnologyInsert[];
+}
+/**
+ * Converts every persisted (legacy) `page_tags` row into the `pageId`-keyed
+ * `technology_signals` + `page_technologies` insert rows for that page's
+ * whole tag set — shared by both `page_tags` migration paths
+ * (`migrate-page-tags-to-page-technologies.ts` for archives already on the
+ * current schema, `retarget-legacy-fk-tables.ts` for the 0.10→0.13 upgrade)
+ * so a `page_tags` row converts identically regardless of which path
+ * produced it, and a future fix to the conversion only needs to change one
+ * place.
+ *
+ * Uses `combineTechnologyConfidence(signals, { skipThreshold: true })` —
+ * migration preserves every historical Wappalyzer detection the old
+ * `page_tags`-based API returned unconditionally, rather than applying the
+ * confidence-noise filter meant for fresh crawl-time detections (see that
+ * option's docs).
+ * @param rows - Every `page_tags` row, in any order (grouped internally by
+ *   `pageId`).
+ * @returns The two insert-ready row sets, empty arrays if `rows` is empty.
+ */
+export declare function convertLegacyPageTagsToInserts(rows: readonly (LegacyTagRowLike & {
+    pageId: number;
+})[]): LegacyPageTagsConversion;

package/lib/meta/technologies/convert-legacy-page-tags-to-inserts.js

@@ -0,0 +1,53 @@
+import { combineTechnologyConfidence } from './combine-technology-confidence.js';
+import { convertTagRowToWappalyzerSignal } from './convert-tag-row-to-wappalyzer-signal.js';
+/**
+ * Converts every persisted (legacy) `page_tags` row into the `pageId`-keyed
+ * `technology_signals` + `page_technologies` insert rows for that page's
+ * whole tag set — shared by both `page_tags` migration paths
+ * (`migrate-page-tags-to-page-technologies.ts` for archives already on the
+ * current schema, `retarget-legacy-fk-tables.ts` for the 0.10→0.13 upgrade)
+ * so a `page_tags` row converts identically regardless of which path
+ * produced it, and a future fix to the conversion only needs to change one
+ * place.
+ *
+ * Uses `combineTechnologyConfidence(signals, { skipThreshold: true })` —
+ * migration preserves every historical Wappalyzer detection the old
+ * `page_tags`-based API returned unconditionally, rather than applying the
+ * confidence-noise filter meant for fresh crawl-time detections (see that
+ * option's docs).
+ * @param rows - Every `page_tags` row, in any order (grouped internally by
+ *   `pageId`).
+ * @returns The two insert-ready row sets, empty arrays if `rows` is empty.
+ */
+export function convertLegacyPageTagsToInserts(rows) {
+    const signalsByPage = new Map();
+    for (const row of rows) {
+        const signal = convertTagRowToWappalyzerSignal(row);
+        const group = signalsByPage.get(row.pageId);
+        if (group) {
+            group.push(signal);
+        }
+        else {
+            signalsByPage.set(row.pageId, [signal]);
+        }
+    }
+    const signalInserts = [];
+    const technologyInserts = [];
+    for (const [pageId, signals] of signalsByPage) {
+        for (const signal of signals) {
+            signalInserts.push({
+                pageId,
+                technology: signal.technology,
+                signalType: signal.signalType,
+                evidence: signal.evidence,
+                weight: signal.weight,
+            });
+        }
+        for (const technology of combineTechnologyConfidence(signals, {
+            skipThreshold: true,
+        })) {
+            technologyInserts.push({ pageId, ...technology });
+        }
+    }
+    return { signalInserts, technologyInserts };
+}

package/lib/meta/technologies/convert-tag-row-to-wappalyzer-signal.d.ts

@@ -0,0 +1,33 @@
+import type { TechnologySignalPartial } from './types.js';
+/**
+ * Minimal shape this function needs from a persisted (legacy) `page_tags`
+ * row. Deliberately narrower than the old `TagRow` — only the columns a
+ * `wappalyzer` signal can use. `categories` accepts `unknown` because
+ * callers read it via two different paths that disagree on whether the
+ * driver already parsed the `json()` column: raw `SELECT` (still a JSON
+ * string) vs. knex's typed row mapping (already an array on some drivers).
+ */
+export interface LegacyTagRowLike {
+    provider: string;
+    version: string | null;
+    confidence: number | null;
+    categories: unknown;
+}
+/**
+ * Converts one persisted (legacy) `page_tags` row into a `wappalyzer`
+ * technology signal — the shared core `migrate-page-tags-to-page-technologies.ts`
+ * (read-time migration for archives already on the current schema) and
+ * `retarget-legacy-fk-tables.ts` (0.10→0.13 upgrade path) both call, so a
+ * `page_tags` row converts identically regardless of which migration path
+ * produced it.
+ *
+ * Mirrors `normalize-wappalyzer-entries.ts`'s live-beholder conversion, but
+ * reads from the OLD persisted row shape (`provider`/`version`/`confidence`/
+ * `categories`) instead of beholder's live `TagEntry` (`provider`/`version`/
+ * `confidence`/`categories`/`id`/`sources`) — structurally similar, but
+ * `page_tags` has no `id` (externalId) to use as `evidence`, so the provider
+ * name is used instead.
+ * @param row - The persisted `page_tags` row (or an equivalent shape).
+ * @returns The equivalent `wappalyzer` signal.
+ */
+export declare function convertTagRowToWappalyzerSignal(row: LegacyTagRowLike): TechnologySignalPartial;

package/lib/meta/technologies/convert-tag-row-to-wappalyzer-signal.js

@@ -0,0 +1,46 @@
+import { WAPPALYZER_PROVIDER_TO_TECHNOLOGY, WAPPALYZER_SIGNAL_WEIGHT, } from './technology-signal-definitions.js';
+/**
+ * Converts one persisted (legacy) `page_tags` row into a `wappalyzer`
+ * technology signal — the shared core `migrate-page-tags-to-page-technologies.ts`
+ * (read-time migration for archives already on the current schema) and
+ * `retarget-legacy-fk-tables.ts` (0.10→0.13 upgrade path) both call, so a
+ * `page_tags` row converts identically regardless of which migration path
+ * produced it.
+ *
+ * Mirrors `normalize-wappalyzer-entries.ts`'s live-beholder conversion, but
+ * reads from the OLD persisted row shape (`provider`/`version`/`confidence`/
+ * `categories`) instead of beholder's live `TagEntry` (`provider`/`version`/
+ * `confidence`/`categories`/`id`/`sources`) — structurally similar, but
+ * `page_tags` has no `id` (externalId) to use as `evidence`, so the provider
+ * name is used instead.
+ * @param row - The persisted `page_tags` row (or an equivalent shape).
+ * @returns The equivalent `wappalyzer` signal.
+ */
+export function convertTagRowToWappalyzerSignal(row) {
+    const categories = parseCategories(row.categories);
+    return {
+        technology: WAPPALYZER_PROVIDER_TO_TECHNOLOGY[row.provider] ?? row.provider,
+        signalType: 'wappalyzer',
+        evidence: row.provider,
+        weight: row.confidence ?? WAPPALYZER_SIGNAL_WEIGHT,
+        category: categories[0] ?? null,
+        version: row.version ?? null,
+    };
+}
+/**
+ * @param raw
+ */
+function parseCategories(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (typeof raw === 'string' && raw.length > 0) {
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}

package/lib/meta/technologies/extract-technologies-for-archive.d.ts

@@ -0,0 +1,33 @@
+import type { PageTechnologyPartial, TechnologySignalPartial } from './types.js';
+import type { PageData } from '../../utils/types/types.js';
+/**
+ * The result of one page's technology-signal extraction: every raw signal
+ * (for `technology_signals`, MCP/query signal-level lookups, and per-page
+ * "why was this detected" drill-down) plus the confidence-combined roll-up
+ * (for `page_technologies`).
+ */
+export interface ExtractedTechnologies {
+    signals: TechnologySignalPartial[];
+    technologies: PageTechnologyPartial[];
+}
+/**
+ * Extracts every technology signal for one page — structural (HTML markers,
+ * URL path fragments, scoped attributes, `<meta name="generator">`) plus
+ * Wappalyzer (beholder's `meta.tags.entries`) — and combines them into
+ * confidence-scored technology rows.
+ *
+ * Crawl-time, synchronous, zero extra network cost — the direct replacement
+ * for `extract-tags-for-archive.ts` in the live crawl write path (that file
+ * itself is untouched; `scripts/migrate-to-0.10.mjs` still depends on it).
+ * JS-license-comment signals from external JS files are NOT produced here —
+ * they require an extra network fetch per JS resource and are added
+ * afterward, once per crawl, by `scan-js-resources-for-technology-signals.ts`
+ * ("JSスキャン・エンリッチメント", a distinct post-crawl category — see
+ * ARCHITECTURE.md). A license banner inside the page's own HTML (an inline
+ * `<script>`) is matched here, since the structural list applies every
+ * definition, `js-license-comment` included, to the HTML.
+ * @param html - The page's raw HTML string.
+ * @param meta - `PageData.meta` (for `generator` and `tags.entries`).
+ * @returns Raw signals and their confidence-combined roll-up.
+ */
+export declare function extractTechnologiesForArchive(html: string, meta: PageData['meta']): ExtractedTechnologies;

package/lib/meta/technologies/extract-technologies-for-archive.js

@@ -0,0 +1,30 @@
+import { combineTechnologyConfidence } from './combine-technology-confidence.js';
+import { matchStructuralTechnologySignals } from './match-structural-technology-signals.js';
+import { normalizeWappalyzerEntries } from './normalize-wappalyzer-entries.js';
+/**
+ * Extracts every technology signal for one page — structural (HTML markers,
+ * URL path fragments, scoped attributes, `<meta name="generator">`) plus
+ * Wappalyzer (beholder's `meta.tags.entries`) — and combines them into
+ * confidence-scored technology rows.
+ *
+ * Crawl-time, synchronous, zero extra network cost — the direct replacement
+ * for `extract-tags-for-archive.ts` in the live crawl write path (that file
+ * itself is untouched; `scripts/migrate-to-0.10.mjs` still depends on it).
+ * JS-license-comment signals from external JS files are NOT produced here —
+ * they require an extra network fetch per JS resource and are added
+ * afterward, once per crawl, by `scan-js-resources-for-technology-signals.ts`
+ * ("JSスキャン・エンリッチメント", a distinct post-crawl category — see
+ * ARCHITECTURE.md). A license banner inside the page's own HTML (an inline
+ * `<script>`) is matched here, since the structural list applies every
+ * definition, `js-license-comment` included, to the HTML.
+ * @param html - The page's raw HTML string.
+ * @param meta - `PageData.meta` (for `generator` and `tags.entries`).
+ * @returns Raw signals and their confidence-combined roll-up.
+ */
+export function extractTechnologiesForArchive(html, meta) {
+    const structuralSignals = matchStructuralTechnologySignals(html, meta.generator);
+    const wappalyzerSignals = normalizeWappalyzerEntries(meta.tags?.entries);
+    const signals = [...structuralSignals, ...wappalyzerSignals];
+    const technologies = combineTechnologyConfidence(signals);
+    return { signals, technologies };
+}

package/lib/meta/technologies/match-js-license-comment-signal.d.ts

@@ -0,0 +1,21 @@
+import type { TechnologySignalPartial } from './types.js';
+/**
+ * Tests a JS resource's leading bytes against the structural fingerprint
+ * list's `js-license-comment` definitions (such as Vue's leading license
+ * banner), returning the first that matches. The same definitions
+ * `matchStructuralTechnologySignals` applies to page HTML; the list lives
+ * in `@nitpicker/core`'s `crates/nitpicker_tech_detect`, and the crawler
+ * reaches it through this function because it does not import the addon
+ * directly.
+ * @param script - The resource's leading bytes as fetched (a byte-capped
+ *   prefix, so possibly cut inside a character — such bytes read as U+FFFD,
+ *   as `Buffer.prototype.toString('utf8')` decodes them).
+ * @returns The first matching signal, or `null` when none matches.
+ * @example
+ * ```ts
+ * matchJsLicenseCommentSignal(Buffer.from('/*!\n * Vue.js v3.4.0\n *\/'));
+ * // { technology: 'Vue', signalType: 'js-license-comment',
+ * //   evidence: '/*!\n * Vue.js v3', weight: 55, category: 'JavaScript frameworks' }
+ * ```
+ */
+export declare function matchJsLicenseCommentSignal(script: Uint8Array): TechnologySignalPartial | null;

package/lib/meta/technologies/match-js-license-comment-signal.js

@@ -0,0 +1,23 @@
+import { matchJsLicenseCommentSignal as matchJsLicenseCommentSignalNative } from '@nitpicker/core/match-js-license-comment-signal';
+/**
+ * Tests a JS resource's leading bytes against the structural fingerprint
+ * list's `js-license-comment` definitions (such as Vue's leading license
+ * banner), returning the first that matches. The same definitions
+ * `matchStructuralTechnologySignals` applies to page HTML; the list lives
+ * in `@nitpicker/core`'s `crates/nitpicker_tech_detect`, and the crawler
+ * reaches it through this function because it does not import the addon
+ * directly.
+ * @param script - The resource's leading bytes as fetched (a byte-capped
+ *   prefix, so possibly cut inside a character — such bytes read as U+FFFD,
+ *   as `Buffer.prototype.toString('utf8')` decodes them).
+ * @returns The first matching signal, or `null` when none matches.
+ * @example
+ * ```ts
+ * matchJsLicenseCommentSignal(Buffer.from('/*!\n * Vue.js v3.4.0\n *\/'));
+ * // { technology: 'Vue', signalType: 'js-license-comment',
+ * //   evidence: '/*!\n * Vue.js v3', weight: 55, category: 'JavaScript frameworks' }
+ * ```
+ */
+export function matchJsLicenseCommentSignal(script) {
+    return matchJsLicenseCommentSignalNative(script);
+}

package/lib/meta/technologies/match-structural-technology-signals.d.ts

@@ -0,0 +1,26 @@
+import type { TechnologySignalPartial } from './types.js';
+/**
+ * Detects the structural fingerprint list (`@nitpicker/core`'s
+ * `crates/nitpicker_tech_detect`) against a page's raw HTML, plus
+ * `<meta name="generator">` prefix matches against the already-extracted
+ * `generator` field. Pure and synchronous — no network I/O, no Wappalyzer
+ * data (see `normalize-wappalyzer-entries.ts` for that source).
+ *
+ * The HTML match runs in the native addon, which scans the page once for
+ * every fingerprint. The JavaScript regular expressions it was ported from
+ * stay in `structural-signal-definitions.ts`, excluded from the build, as
+ * the oracle for `match-structural-technology-signals.parity.spec.ts`.
+ * @param html - The page's raw HTML string (empty for external or
+ *   metadata-only scrapes, which then match nothing).
+ * @param generator - `page_meta.generator` (already extracted by
+ *   `derive-flat-from-meta.ts` from beholder's `Meta`), or `null`/`undefined`.
+ * @returns Un-combined structural signals, one per matched fingerprint in
+ *   the list's order, then one per matched generator prefix.
+ * @example
+ * ```ts
+ * matchStructuralTechnologySignals('<div data-v-1a2b3c4d></div>', 'Nuxt 3.8');
+ * // [{ technology: 'Vue', signalType: 'scoped-attr', ... },
+ * //  { technology: 'Nuxt', signalType: 'meta-generator', version: '3.8', ... }]
+ * ```
+ */
+export declare function matchStructuralTechnologySignals(html: string, generator: string | null | undefined): TechnologySignalPartial[];