@toolpath/tool-scraper 0.1.0 → 2.1.0

package/dist/vendors/harvey/scrape.js

@@ -0,0 +1,483 @@
+/**
+ * One Harvey Tool product page -> one row per orderable part.
+ *
+ * The page is server-rendered HTML with its variant data inlined as a
+ * JavaScript literal; `docs/HARVEY_PRODUCT_TABLE.md` records how that was found
+ * and what was tried first. This module is the join between the two halves — a
+ * `<thead>` in the DOM and a `tableData<N>` in a `<script>` — plus the one
+ * structural thing Harvey's table does that no other vendor here does.
+ *
+ * ## One HTML row is up to nine orderable parts
+ *
+ * The table is a matrix. The `a*` cells are the geometry, shared; after them
+ * comes a coating × flute grid where each coating is a `colspan`-ed header and
+ * every non-empty cell under it is a different tool number at the same geometry.
+ * **5,033 HTML rows become 12,799 CSV rows**, and that explosion is the whole
+ * risk in this adapter: a coating or flute count read off the wrong column
+ * produces a CSV that is the right length and wrong throughout.
+ *
+ * ## Harvey checks it for us, 5,033 times per scrape
+ *
+ * Every row carries an `atc` cell whose `j` is the add-to-cart payload, and that
+ * payload independently lists every tool number on the row **in the same order
+ * as the non-empty tool-number cells**:
+ *
+ * ```json
+ * [{"T":"690508","C":"690508","Q":"1"},{"T":"679608","C":"679608","Q":"1"}]
+ * ```
+ *
+ * So the explosion is checked against the vendor's own list on every row rather
+ * than once against a hand count, and a grid that has shifted by one column
+ * cannot pass. That check is {@link checkCartPayload}, and it is the reason the
+ * declared `rows` counts in `families/harvey.ts` being seeded rather than
+ * hand-counted is survivable.
+ *
+ * ## Two columns are synthesised, and neither has a cell to copy
+ *
+ * `Coating` is a fact about which *header* a tool number sits under, and
+ * `FLUTES` is too on the matrix tables. Both are encoded in column position and
+ * nowhere else, which is why they are built here rather than lifted, and why the
+ * coating vocabulary is a closed list in `lexicon.ts`.
+ *
+ * `FLUTES` is one column either way — synthesised from the sub-label on a matrix
+ * table and lifted from the row's own column on a `TOOL #` one — so the vendor's
+ * `FLUTES` column is taken out of the geometry list rather than written twice.
+ *
+ * Everything else in the CSV is the vendor's own display string, verbatim —
+ * `.250 (1/4)` reaches the file as `.250 (1/4)`. `value.ts` is what resolves one
+ * when a record is built.
+ */
+import { CAD_COLUMN, CAD_DXF_COLUMN, DESCRIPTION_COLUMN, dimensionalColumn, } from '../../conventions.js';
+import { VendorResponseError } from '../../errors.js';
+import { consoleWarn } from '../../scrape.js';
+import { flatHeader, isJunkLabel } from './header.js';
+import { readLiteral } from './literal.js';
+import { parseValue } from './value.js';
+import { CART_LABEL, FLUTES_LABEL, PRICE_LABEL, TOOL_NUMBER_LABEL, checkCoating, flutesInLabel, isDimensional, } from './lexicon.js';
+export const BASE = 'https://www.harveytool.com';
+/** `cols1`..`cols10` and `tableData1`..`tableData10` exist on every page. */
+export const MAX_TABLES = 10;
+/** The CSV columns this adapter synthesises or lifts from the page itself. */
+export const TOOL_NUMBER_COLUMN = 'Tool #';
+export const COATING_COLUMN = 'Coating';
+export const FLUTES_COLUMN = 'FLUTES';
+export const PRICE_COLUMN = 'PRICE_USD';
+/**
+ * The suffix an unlabelled annotation column takes, after the column it
+ * annotates.
+ *
+ * Harvey gives these no header at all — see `docs/HARVEY_PRODUCT_TABLE.md` §5.3
+ * — so a name has to be supplied, and naming one for what it annotates is the
+ * only honest option available. Dropping them instead would lose a published
+ * column; leaving them unnamed would collide with the column they follow.
+ */
+export const RATIO_SUFFIX = 'RATIO';
+/**
+ * The suffix an unlabelled column takes when it is *not* a ratio.
+ *
+ * Four such columns exist, on two families, and Harvey renders them in white
+ * text: two carry the badge `LONG` on a handful of rows and two are entirely
+ * empty. Naming them `RATIO` would be a claim about their contents that is
+ * false, so which suffix a column gets is decided from the whole page's data
+ * rather than from its header — see {@link ratioColumnKeys}.
+ */
+export const NOTE_SUFFIX = 'NOTE';
+/** True where the cell carries a link, i.e. where it names a real part. */
+const LINKED = /<a\b[^>]*\bhref\s*=/i;
+/** `<a href="...">14916</a>` -> `14916`. These cells carry no entities. */
+export function cellText(html) {
+    return (html ?? '')
+        .replace(/<[^>]*>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** `$148.40 ` -> `148.40`. The column already says which currency. */
+export function priceOf(html) {
+    return cellText(html).replace(/^\$/, '').trim();
+}
+/**
+ * The CSV column each geometry column is written under.
+ *
+ * Three cases, and the second and third are the ones worth knowing:
+ *
+ * 1. **A label of its own** keeps it.
+ * 2. **A repeated label with distinct meaningful sub-labels** takes the
+ *    sub-label — `Interference Depth At Wall Angle*` is six real columns
+ *    headed `0°` through `4°`, not one column and five annotations.
+ * 3. **A repeated label with a junk sub-label**, or a column whose top label is
+ *    junk outright, is the vendor's ratio annotation of the column before it and
+ *    takes {@link RATIO_SUFFIX}.
+ */
+function geometryColumns(family, keys, header, unit, ratioKeys, warn) {
+    const positions = keys
+        .map((key, index) => ({ key, head: header[index] }))
+        .filter(({ key, head }) => key !== 'atc' && /^a\d+$/.test(key) && head.top !== CART_LABEL)
+        // The flute count leaves the geometry list and comes back as one
+        // synthesised `FLUTES` column, because half these tables state it in a
+        // column and half in a coating group's sub-label. Keeping both would put
+        // two columns called `FLUTES` in one CSV.
+        .filter(({ head }) => head.top !== FLUTES_LABEL);
+    const byLabel = new Map();
+    for (const { head } of positions) {
+        if (isJunkLabel(head.top))
+            continue;
+        byLabel.set(head.top, [...(byLabel.get(head.top) ?? []), head]);
+    }
+    /** True where every occurrence of this label has its own real sub-label. */
+    const subLabelled = new Map();
+    for (const [label, heads] of byLabel) {
+        const subs = heads.map((h) => h.sub ?? '');
+        subLabelled.set(label, heads.length > 1 && subs.every((s) => !isJunkLabel(s)) && new Set(subs).size === subs.length);
+    }
+    const columns = [];
+    const seen = new Set();
+    for (const { key, head } of positions) {
+        let label;
+        let dimensional;
+        if (isJunkLabel(head.top)) {
+            const previous = columns[columns.length - 1];
+            if (previous === undefined) {
+                throw new VendorResponseError(family, `opens with an unlabelled column (${key}) — there is nothing for it to annotate`);
+            }
+            label = `${previous.label} ${ratioKeys.has(key) ? RATIO_SUFFIX : NOTE_SUFFIX}`;
+            dimensional = false;
+            warn(`  WARNING: ${family}: column ${key} has no header of its own; ` +
+                `written as ${JSON.stringify(label)}`);
+        }
+        else if (subLabelled.get(head.top) === true) {
+            label = `${head.top} ${head.sub}`;
+            dimensional = isDimensional(family, head.top);
+        }
+        else if (seen.has(head.top)) {
+            label = `${head.top} ${RATIO_SUFFIX}`;
+            dimensional = false;
+        }
+        else {
+            label = head.top;
+            dimensional = isDimensional(family, head.top);
+        }
+        seen.add(head.top);
+        const column = dimensional ? dimensionalColumn(label, unit) : label;
+        if (columns.some((c) => c.column === column)) {
+            throw new VendorResponseError(family, `has two columns both written as ${JSON.stringify(column)} — the ` +
+                `header no longer tells them apart`);
+        }
+        columns.push({ key, column, label });
+    }
+    return columns;
+}
+/**
+ * The coating groups of one table, with each part column's flute count.
+ *
+ * A group runs from its first tool-number column to its price column. Every
+ * group on all 80 tables has exactly one price and it comes last, so a group
+ * that reaches its end without one is refused rather than given a blank price:
+ * the grid would have shifted, and every part in it would be reading a
+ * neighbour's cell.
+ */
+function coatingGroups(family, keys, header, warn) {
+    const groups = [];
+    let coating = null;
+    let parts = [];
+    for (const [index, key] of keys.entries()) {
+        const head = header[index];
+        const sub = head.sub ?? '';
+        if (/^s\d+$/.test(key)) {
+            if (coating === null) {
+                coating = checkCoating(family, head.top);
+                parts = [];
+            }
+            else if (coating !== head.top) {
+                throw new VendorResponseError(family, `starts coating group ${JSON.stringify(head.top)} before ` +
+                    `${JSON.stringify(coating)} has a ${PRICE_LABEL} column`);
+            }
+            parts.push({ key, flutes: sub === TOOL_NUMBER_LABEL ? null : flutesInLabel(sub) });
+            continue;
+        }
+        if (/^p\d+$/.test(key)) {
+            if (coating === null) {
+                throw new VendorResponseError(family, `has a price column (${key}) under no coating group`);
+            }
+            if (sub !== PRICE_LABEL) {
+                throw new VendorResponseError(family, `has a price column (${key}) sub-headed ${JSON.stringify(sub)} rather ` +
+                    `than ${JSON.stringify(PRICE_LABEL)}`);
+            }
+            groups.push({ coating, parts, priceKey: key });
+            coating = null;
+        }
+    }
+    if (coating !== null) {
+        throw new VendorResponseError(family, `leaves coating group ${JSON.stringify(coating)} without a price column`);
+    }
+    return fillBlankFluteLabels(family, groups, warn);
+}
+/**
+ * Fill a flute sub-label Harvey rendered as `&nbsp;` from a sibling group.
+ *
+ * Two tables in the catalog do this — `EndMill-008` table 2 and `EndMill-018`
+ * table 2 — and in both the neighbouring coating groups label the same slot
+ * correctly. A sibling qualifies only when it is the same width *and* agrees on
+ * every other slot, so the fill is a copy of a row that is demonstrably the same
+ * shape rather than of whichever group happened to be nearby. Two siblings that
+ * disagree is a hard failure: there is no way to pick, and picking would put a
+ * flute count on a real part on no evidence.
+ */
+function fillBlankFluteLabels(family, groups, warn) {
+    return groups.map((group) => {
+        // All stated is the matrix pattern with nothing missing; none stated is the
+        // `TOOL #` pattern, where the row's own FLUTES column is the source and a
+        // null here is not a gap. Only a mixture is a blank label to fill.
+        const stated = group.parts.filter((p) => p.flutes !== null).length;
+        if (stated === 0 || stated === group.parts.length)
+            return group;
+        const parts = group.parts.map((part, slot) => {
+            if (part.flutes !== null)
+                return part;
+            const candidates = new Set();
+            for (const other of groups) {
+                if (other === group || other.parts.length !== group.parts.length)
+                    continue;
+                const agrees = group.parts.every((p, i) => i === slot || p.flutes === null || p.flutes === other.parts[i]?.flutes);
+                const found = other.parts[slot]?.flutes;
+                if (agrees && found != null)
+                    candidates.add(found);
+            }
+            if (candidates.size !== 1) {
+                throw new VendorResponseError(family, `has a blank flute label in the ${JSON.stringify(group.coating)} group ` +
+                    `at slot ${slot}, and ${candidates.size === 0 ? 'no' : 'more than one'} ` +
+                    `sibling group of the same shape states one`);
+            }
+            const flutes = [...candidates][0];
+            warn(`  WARNING: ${family}: the ${JSON.stringify(group.coating)} group's flute ` +
+                `label at slot ${slot} is blank; read as ${flutes} from a sibling group`);
+            return { ...part, flutes };
+        });
+        return { ...group, parts };
+    });
+}
+/** Read one table's plan off its `cols<N>` keys and its flattened header. */
+export function planTable(family, keys, header, unit, options = {}) {
+    const { warn = consoleWarn, ratioKeys = new Set() } = options;
+    if (keys.length !== header.length) {
+        throw new VendorResponseError(family, `declares ${keys.length} data columns but its header flattens to ` +
+            `${header.length} — the two are positional and no longer line up`);
+    }
+    const geometry = geometryColumns(family, keys, header, unit, ratioKeys, warn);
+    const groups = coatingGroups(family, keys, header, warn);
+    if (groups.length === 0) {
+        throw new VendorResponseError(family, 'publishes no coating group — there are no parts to read');
+    }
+    const flutesIndex = keys.findIndex((key, i) => /^a\d+$/.test(key) && header[i].top === FLUTES_LABEL);
+    return {
+        geometry,
+        flutesKey: flutesIndex === -1 ? null : keys[flutesIndex],
+        matrix: groups.some((g) => g.parts.some((p) => p.flutes !== null)),
+        groups,
+    };
+}
+/**
+ * Every part the row's own add-to-cart payload lists, in cell order.
+ *
+ * `T` and `C` differ on the 36 parts whose printed number carries a footnote
+ * marker: `C` keeps it, `T` does not. Both are read, and each does a different
+ * job — `C` is what the cell says and is therefore what the cell can be checked
+ * against, `T` is Harvey's own clean part number and is therefore what the CSV
+ * records. Deriving the second from the first with a regex would work today and
+ * be this package's guess rather than the vendor's statement.
+ *
+ * `Q` is `"1"` on all 12,799 entries and is not read.
+ */
+export function cartEntries(family, row) {
+    const payload = row['atc']?.j;
+    if (typeof payload !== 'string' || payload === '') {
+        throw new VendorResponseError(family, 'has a row with no add-to-cart payload to check against');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch (error) {
+        throw new VendorResponseError(family, `has an unreadable add-to-cart payload: ${error.message}`);
+    }
+    return parsed.map((entry) => ({ number: entry.T ?? '', printed: entry.C ?? entry.T ?? '' }));
+}
+/** Refuse an explosion the vendor's own payload does not agree with. */
+export function checkCartPayload(family, printed, cart) {
+    if (printed.length === cart.length && printed.every((t, i) => t === cart[i].printed))
+        return;
+    throw new VendorResponseError(family, `read [${printed.join(', ')}] off a row whose own add-to-cart payload ` +
+        `lists [${cart.map((entry) => entry.printed).join(', ')}] — the coating ` +
+        `grid has shifted`);
+}
+/**
+ * The unlabelled columns of a page whose cells are all ratio annotations.
+ *
+ * Decided across the whole page rather than per table, because the tables merge
+ * into one CSV and a column cannot be named two things. `EndMill-006` is why: a
+ * column is `LONG` on four rows of its first table and empty throughout its
+ * second.
+ */
+export function ratioColumnKeys(tables) {
+    const unlabelled = new Set();
+    const other = new Set();
+    for (const table of tables) {
+        table.keys.forEach((key, index) => {
+            const head = table.header[index];
+            if (head === undefined || !/^a\d+$/.test(key) || !isJunkLabel(head.top))
+                return;
+            unlabelled.add(key);
+            for (const row of table.rows) {
+                const text = cellText(row[key]?.d);
+                if (text !== '' && parseValue(text).ratio === null)
+                    other.add(key);
+            }
+        });
+    }
+    for (const key of other)
+        unlabelled.delete(key);
+    return unlabelled;
+}
+function readPage(html, what) {
+    const model = readLiteral(html, 'viewModel')?.simFileViewModel;
+    const productCode = model?.productCode;
+    if (!productCode) {
+        throw new VendorResponseError(what, 'has no viewModel.simFileViewModel.productCode');
+    }
+    const cad = new Map();
+    for (const variant of model.variantSimFileViewModel ?? []) {
+        if (variant.variantName)
+            cad.set(variant.variantName, variant);
+    }
+    // Table ids drop the `HT-` the product code carries: `HT-Harvey-EndMill-008`
+    // heads a table with `id="Harvey-EndMill-008_1"`.
+    const prefix = productCode.replace(/^HT-/, '');
+    const tables = [];
+    for (let n = 1; n <= MAX_TABLES; n++) {
+        const keys = (readLiteral(html, `cols${n}`) ?? [])
+            .map((column) => column.data ?? '')
+            .filter(Boolean);
+        if (keys.length === 0)
+            continue;
+        const rows = readLiteral(html, `tableData${n}`) ?? [];
+        tables.push({ keys, rows, header: flatHeader(html, `${prefix}_${n}`) });
+    }
+    if (tables.length === 0) {
+        throw new VendorResponseError(what, 'declares no populated table — the page changed shape');
+    }
+    return { productCode, productTitle: model.productTitle ?? '', cad, tables };
+}
+/**
+ * One product page's HTML -> one row per orderable part.
+ *
+ * Pure, and separate from {@link scrapeProduct} so the whole matrix explosion is
+ * testable from a fixture string with no fetcher anywhere near it.
+ *
+ * A page's tables differ only in published tolerance — which is dropped — so
+ * they merge into one CSV. Their column labels are required to agree, because
+ * two tables that no longer publish the same columns is a page that has been
+ * restructured, and merging them would interleave two different geometries under
+ * one header.
+ */
+export function parseProductPage(html, source, options) {
+    const { unit, warn = consoleWarn } = options;
+    const page = readPage(html, source);
+    const family = page.productCode;
+    const ratioKeys = ratioColumnKeys(page.tables);
+    const plans = page.tables.map((table) => planTable(family, table.keys, table.header, unit, { warn, ratioKeys }));
+    const geometry = plans[0].geometry.map((column) => column.column);
+    for (const plan of plans.slice(1)) {
+        const other = plan.geometry.map((column) => column.column);
+        if (other.length !== geometry.length || other.some((c, i) => c !== geometry[i])) {
+            throw new VendorResponseError(family, `publishes [${geometry.join(', ')}] on one table and [${other.join(', ')}] ` +
+                `on another — the page's tables no longer share a header`);
+        }
+    }
+    const flutes = plans.some((plan) => plan.matrix || plan.flutesKey !== null);
+    const header = [
+        TOOL_NUMBER_COLUMN,
+        DESCRIPTION_COLUMN,
+        COATING_COLUMN,
+        ...(flutes ? [FLUTES_COLUMN] : []),
+        ...geometry,
+        PRICE_COLUMN,
+        CAD_COLUMN,
+        CAD_DXF_COLUMN,
+    ];
+    const rows = [];
+    page.tables.forEach((table, index) => {
+        const plan = plans[index];
+        for (const source_ of table.rows) {
+            const shared = {};
+            for (const column of plan.geometry) {
+                shared[column.column] = cellText(source_[column.key]?.d);
+            }
+            const rowFlutes = plan.flutesKey === null ? '' : cellText(source_[plan.flutesKey]?.d);
+            // Two lists, and the split is the point. `printed` is every non-empty
+            // tool-number cell, in order, and is what the row's own add-to-cart
+            // payload is checked against. `parts` is the subset that is a real part.
+            const printed = [];
+            const parts = [];
+            for (const group of plan.groups) {
+                const price = priceOf(source_[group.priceKey]?.d);
+                for (const part of group.parts) {
+                    const cell = source_[part.key]?.d ?? '';
+                    const text = cellText(cell);
+                    if (text === '')
+                        continue;
+                    const slot = printed.length;
+                    printed.push(text);
+                    if (!LINKED.test(cell)) {
+                        // 26 cells across two families carry the marketing string
+                        // `25x Diameter!` in a tool-number column, rendered in red, with no
+                        // link and no CAD model — and Harvey's own cart payload lists them
+                        // as though they were orderable. The link is the structural
+                        // difference; a rule that matched the text would miss the next one.
+                        warn(`  WARNING: ${family}: the ${JSON.stringify(group.coating)} column ` +
+                            `holds ${JSON.stringify(text)} with no product link — not a part`);
+                        continue;
+                    }
+                    // The sub-label is per part and the FLUTES column is per row, so the
+                    // sub-label wins where both exist. They agree on all four tables that
+                    // publish both; a disagreement is Harvey having changed one of them.
+                    const stated = part.flutes === null ? null : String(part.flutes);
+                    if (stated !== null && rowFlutes !== '' && stated !== rowFlutes) {
+                        warn(`  WARNING: ${family}: ${text} sits under a ${stated}-flute header ` +
+                            `on a row whose FLUTES column says ${rowFlutes}`);
+                    }
+                    parts.push({ slot, coating: group.coating, price, flutes: stated ?? rowFlutes });
+                }
+            }
+            const cart = cartEntries(family, source_);
+            checkCartPayload(family, printed, cart);
+            for (const part of parts) {
+                const toolNumber = cart[part.slot].number;
+                const variant = page.cad.get(toolNumber);
+                rows.push({
+                    ...shared,
+                    [TOOL_NUMBER_COLUMN]: toolNumber,
+                    [DESCRIPTION_COLUMN]: page.productTitle,
+                    [COATING_COLUMN]: part.coating,
+                    ...(flutes ? { [FLUTES_COLUMN]: part.flutes } : {}),
+                    [PRICE_COLUMN]: part.price,
+                    [CAD_COLUMN]: variant?.variantStepFileLink ?? '',
+                    [CAD_DXF_COLUMN]: variant?.variantDxfFileLink ?? '',
+                });
+            }
+        }
+    });
+    return { header, rows, source, familyCode: page.productCode };
+}
+/** One product page's URL. */
+export function productUrl(path) {
+    return BASE + path;
+}
+/**
+ * Scrape one product page.
+ *
+ * The one network call in this module, and the seam every test replaces —
+ * everything below it parses a string.
+ */
+export async function scrapeProduct(fetcher, path, options) {
+    const url = productUrl(path);
+    return parseProductPage(await fetcher.text(url), url, options);
+}

package/dist/vendors/harvey/value.d.ts

@@ -0,0 +1,74 @@
+/**
+ * One display cell -> a number, or an honest reason there is none.
+ *
+ * Harvey publishes values the way a printed catalog does, because the table is
+ * a printed catalog: `.1250 (1/8)` is a decimal with the fraction a machinist
+ * orders by beside it, `1-1/2` is a mixed number, `3 mm` is a metric shank on
+ * an imperial page, and `-` means the column does not apply to that row.
+ *
+ * **One rule covers the whole grammar: the value is the leading token, and
+ * anything in parentheses is Harvey's own equivalent annotation.** Every shape
+ * measured across all 12,799 parts is in `docs/HARVEY_PRODUCT_TABLE.md` §4;
+ * this module is that section as code.
+ *
+ * ## Read `d`, never `v`
+ *
+ * Each cell also carries `v`, which looks pre-parsed and is the wrong field: it
+ * changes unit basis *within a single row*. On the metric ball page, `v` is the
+ * inch equivalent for the cutter diameter and the raw millimetre number for the
+ * length of cut. Anything reading it gets a clean conversion with wrong numbers
+ * in it — the exact failure `conventions.UNIT_SUFFIX` exists to prevent.
+ *
+ * ## A stated unit wins over the column's
+ *
+ * 46 cells across six otherwise-imperial families state a metric value outright
+ * — `3 mm` in a `SHANK DIAMETER` column on an inch page, a metric-shank tool
+ * listed among imperial ones. {@link dimension} converts those into the family's
+ * declared unit and warns, naming the part. It does **not** treat a
+ * parenthesised `(3 mm)` that way: that is an annotation on an inch value, and
+ * converting it would turn `.1181 in` into `3 in`.
+ */
+import type { UnitSystem } from '../../conventions.js';
+import { type Warn } from '../../scrape.js';
+/** What one display cell says. */
+export interface HarveyValue {
+    /** The leading numeric token, in whatever {@link stated} says. */
+    readonly value: number | null;
+    /** The unit the token states outright. Null where it states none. */
+    readonly stated: UnitSystem | null;
+    /** True where the token is an angle in degrees rather than a length. */
+    readonly degrees: boolean;
+    /** Harvey's parenthesised equivalent, verbatim — `1/8`, `3 mm`, `N.P.T.`. */
+    readonly annotation: string | null;
+    /** The multiplier a `(1.5x)` cell states, and nothing else. */
+    readonly ratio: number | null;
+    /** Text with no numeric reading at all: `I`, `II`, `III`, `LONG`. */
+    readonly code: string | null;
+}
+/**
+ * One cell's display text, read.
+ *
+ * An empty cell and a `-` both come back as {@link NOTHING}. They mean slightly
+ * different things to a reader of the catalog — "nothing published" and "does
+ * not apply" — and the same thing to anything building a record, which is that
+ * there is no number here and 0 is not a substitute for one.
+ */
+export declare function parseValue(display: string): HarveyValue;
+/**
+ * One cell as a length in `unit`, or null where it publishes none.
+ *
+ * `measure.asLength` makes both calls — convert-and-warn a cell whose stated
+ * unit disagrees with the family's, refuse an angle in a dimensional column —
+ * because they are the same two calls for every vendor and were a verbatim copy
+ * here and in `vendors/emuge/value.ts` until 2026-09-01. What is Harvey's is
+ * above: that `degrees` is a field of its own rather than a member of
+ * `stated`, and that a parenthesised `(3 mm)` is an annotation on an inch value
+ * and never the value itself.
+ *
+ * The 46 cells this converts are metric-shank tools listed among imperial ones
+ * — real parts somebody can order, which is why they are converted rather than
+ * dropped.
+ */
+export declare function dimension(display: string, unit: UnitSystem, what: string, warn?: Warn): number | null;
+/** One cell as a whole count — a flute or tooth number. Null where blank. */
+export declare function count(display: string): number | null;

package/dist/vendors/harvey/value.js

@@ -0,0 +1,119 @@
+/**
+ * One display cell -> a number, or an honest reason there is none.
+ *
+ * Harvey publishes values the way a printed catalog does, because the table is
+ * a printed catalog: `.1250 (1/8)` is a decimal with the fraction a machinist
+ * orders by beside it, `1-1/2` is a mixed number, `3 mm` is a metric shank on
+ * an imperial page, and `-` means the column does not apply to that row.
+ *
+ * **One rule covers the whole grammar: the value is the leading token, and
+ * anything in parentheses is Harvey's own equivalent annotation.** Every shape
+ * measured across all 12,799 parts is in `docs/HARVEY_PRODUCT_TABLE.md` §4;
+ * this module is that section as code.
+ *
+ * ## Read `d`, never `v`
+ *
+ * Each cell also carries `v`, which looks pre-parsed and is the wrong field: it
+ * changes unit basis *within a single row*. On the metric ball page, `v` is the
+ * inch equivalent for the cutter diameter and the raw millimetre number for the
+ * length of cut. Anything reading it gets a clean conversion with wrong numbers
+ * in it — the exact failure `conventions.UNIT_SUFFIX` exists to prevent.
+ *
+ * ## A stated unit wins over the column's
+ *
+ * 46 cells across six otherwise-imperial families state a metric value outright
+ * — `3 mm` in a `SHANK DIAMETER` column on an inch page, a metric-shank tool
+ * listed among imperial ones. {@link dimension} converts those into the family's
+ * declared unit and warns, naming the part. It does **not** treat a
+ * parenthesised `(3 mm)` that way: that is an annotation on an inch value, and
+ * converting it would turn `.1181 in` into `3 in`.
+ */
+import { asCount, asLength, fractionValue } from '../../measure.js';
+import { consoleWarn } from '../../scrape.js';
+/**
+ * Footnote references Harvey appends to a value or a tool number. 62 cells
+ * carry one; each points at a note printed under the table, and none of them is
+ * part of the number.
+ */
+const FOOTNOTE = /[*!†]+$/;
+/** Harvey's own equivalent, in parentheses at the end: `(1/8)`, `(3 mm)`. */
+const ANNOTATION = /\s*\(([^)]*)\)\s*$/;
+/** `(1.5x)`, `(30x)` — the vendor's reach- or length-to-diameter ratio. */
+const RATIO = /^(\d*\.?\d+)x$/;
+/**
+ * A mixed number, a simple fraction or a decimal, with an optional unit.
+ *
+ * The alternation is ordered longest-first on purpose: `\d*\.?\d+` alone
+ * matches the `3` of `3-3/4` and would leave the rest unread, which parses a
+ * 3.75-inch tool as a 3-inch one.
+ */
+const NUMBER = /^(\d+-\d+\/\d+|\d*\.?\d+\/\d+|\d*\.?\d+)\s*(mm|°)?$/;
+const NOTHING = {
+    value: null,
+    stated: null,
+    degrees: false,
+    annotation: null,
+    ratio: null,
+    code: null,
+};
+/**
+ * One cell's display text, read.
+ *
+ * An empty cell and a `-` both come back as {@link NOTHING}. They mean slightly
+ * different things to a reader of the catalog — "nothing published" and "does
+ * not apply" — and the same thing to anything building a record, which is that
+ * there is no number here and 0 is not a substitute for one.
+ */
+export function parseValue(display) {
+    const text = display.trim().replace(FOOTNOTE, '').trim();
+    if (text === '' || text === '-')
+        return NOTHING;
+    const annotated = ANNOTATION.exec(text);
+    const annotation = annotated?.[1]?.trim() ?? null;
+    const head = annotated ? text.slice(0, annotated.index).trim() : text;
+    if (head === '') {
+        const ratio = annotation === null ? null : RATIO.exec(annotation);
+        if (ratio)
+            return { ...NOTHING, ratio: Number(ratio[1]) };
+        return { ...NOTHING, annotation };
+    }
+    const number = NUMBER.exec(head);
+    // `measure.fractionValue` is stricter than {@link NUMBER} in one place — it
+    // refuses a division by zero — so a token that matched here can still have no
+    // reading, and that is a code cell rather than a number.
+    const value = number === null ? null : fractionValue(number[1]);
+    if (number === null || value === null)
+        return { ...NOTHING, annotation, code: head };
+    const unit = number[2];
+    return {
+        value,
+        stated: unit === 'mm' ? 'millimeters' : null,
+        degrees: unit === '°',
+        annotation,
+        ratio: null,
+        code: null,
+    };
+}
+/**
+ * One cell as a length in `unit`, or null where it publishes none.
+ *
+ * `measure.asLength` makes both calls — convert-and-warn a cell whose stated
+ * unit disagrees with the family's, refuse an angle in a dimensional column —
+ * because they are the same two calls for every vendor and were a verbatim copy
+ * here and in `vendors/emuge/value.ts` until 2026-09-01. What is Harvey's is
+ * above: that `degrees` is a field of its own rather than a member of
+ * `stated`, and that a parenthesised `(3 mm)` is an annotation on an inch value
+ * and never the value itself.
+ *
+ * The 46 cells this converts are metric-shank tools listed among imperial ones
+ * — real parts somebody can order, which is why they are converted rather than
+ * dropped.
+ */
+export function dimension(display, unit, what, warn = consoleWarn) {
+    const { value, stated, degrees } = parseValue(display);
+    return asLength({ value, stated: degrees ? 'degrees' : stated }, display, unit, what, warn);
+}
+/** One cell as a whole count — a flute or tooth number. Null where blank. */
+export function count(display) {
+    return asCount(parseValue(display));
+}