@toolpath/tool-scraper 0.1.0 → 2.1.0

package/README.md

@@ -17,26 +17,41 @@ pnpm add @toolpath/tool-scraper
 
 ## Vendors
 
-| Vendor             | Transport                                        | What it publishes     |
-| ------------------ | ------------------------------------------------ | --------------------- |
-| Kennametal / WIDIA | AEM variant-table GET, parsed with `htmlparser2` | tools and toolholding |
-| REGO-FIX           | Elasticsearch proxy POST + per-part DIN 4000 XML | toolholding           |
-| Destiny Tool       | Firestore REST, paginated                        | solid end mills       |
+| Vendor             | Transport                                               | What it publishes                    |
+| ------------------ | ------------------------------------------------------- | ------------------------------------ |
+| Kennametal / WIDIA | AEM variant-table GET, parsed with `htmlparser2`        | tools and toolholding                |
+| REGO-FIX           | Elasticsearch proxy POST + per-part DIN 4000 XML        | toolholding                          |
+| Destiny Tool       | Firestore REST, paginated                               | solid end mills                      |
+| Harvey Tool        | inline JS literal on a product page, plus its `<thead>` | miniature end mills, keyseat cutters |
+| MariTool           | osCommerce category listings, then one page per part    | toolholding                          |
+| EMUGE-FRANKEN      | SAP Commerce JSON API: grouped, variant, batched detail | end mills, twist drills, taps        |
 
 ## Two entry points
 
-**`@toolpath/tool-scraper` returns records.** Every scrape hands back rows and enough provenance to
-say where they came from; nothing in it touches the filesystem, so a backend can embed it and do
-what it likes with the result.
+**`@toolpath/tool-scraper` returns records.** Every scrape hands back the vendor's own rows and
+enough provenance to say where they came from; `toRecords` turns one family's scrape into
+`ToolRecord[]` — canonical ISO 13399 geometry, one shape whatever the vendor. Nothing in either
+touches the filesystem, so a backend can embed it and do what it likes with the result.
 
 ```ts
-import { createFetcher } from '@toolpath/tool-scraper'
+import { createFetcher, type ToolRecord } from '@toolpath/tool-scraper'
+import { toRecords } from '@toolpath/tool-scraper/registry'
 import { scrapeFamily } from '@toolpath/tool-scraper/vendors/kennametal'
 
 const fetcher = createFetcher() // or your own: retries, proxy, rate limits
-const { header, rows, source } = await scrapeFamily(fetcher, '100003658')
+const scrape = await scrapeFamily(fetcher, '100003658')
+
+const records: ToolRecord[] = toRecords('godrill_3xd_metric.csv', scrape)
+// { brand: 'kennametal', guid: '…', geometry: { DC: 10, OAL: 89, … },
+//   materialGroups: ['P', 'N'], materialGroupsSource: 'vendor-stated', … }
 ```
 
+`toRecords` is on the `./registry` subpath because it is the one place that knows both the family
+table and the vendor adapters; the main entry point deliberately imports no vendor. It checks the
+scrape's header for the identity and mapped columns before it maps a single row, so a re-scrape
+whose part-number column was renamed fails by name instead of minting every guid off an empty
+string.
+
 The transport is a parameter, not a module global. Supply your own `Fetcher` and the vendor
 adapters read through it — which is also how every test in this package runs without a network.
 
@@ -57,6 +72,11 @@ toolpath-scrape kennametal 100003658 "$TOOLPATH_SCRAPE_ROOT/kennametal/csv/godri
 toolpath-scrape materials godrill_3xd_metric.csv
 toolpath-scrape regofix holders "$TOOLPATH_SCRAPE_ROOT/regofix/csv/regofix_bt30_pg_holders.csv"
 toolpath-scrape destinytool "$TOOLPATH_SCRAPE_ROOT/destinytool/csv/destinytool_end_mills_inch.csv"
+toolpath-scrape harvey harvey_endmill_008.csv     # the page and the unit come from its config
+toolpath-scrape harvey --catalog                  # what the four category trees link to today
+toolpath-scrape maritool maritool_cat40_holders.csv  # its leaf categories come from its config
+toolpath-scrape maritool --catalog                # what the five taper trees hold today
+toolpath-scrape emuge emuge_drills.csv            # its category and unit come from its config
 ```
 
 `toolpath-scrape --help` lists the rest.
@@ -71,6 +91,14 @@ definition and names the three that are Autodesk's rather than the standard's.
 Vendor CSVs keep the **vendor's** own column labels. Nothing reads a vendor's CSV but that vendor's
 adapter, and `conventions.ts` holds the short list of rules that do hold across all of them.
 
+`materialGroups` has three states, and they are different claims: `null` labelled `unspecified` is
+"we do not know what this tool is for" — not indexed, not published, or not swept — `[]` is a vendor
+index that rates the part for nothing, and a non-empty list is a rating. `materialGroupsSource` is
+never absent: it is `unspecified`, or it says whether the rating was `vendor-stated` or `derived`
+here. Every Harvey record is `unspecified`: Harvey's material index is published per part rather
+than in a variant table, and a scrape cannot reach it — see
+[`docs/HARVEY_PRODUCT_TABLE.md`](docs/HARVEY_PRODUCT_TABLE.md) §1.5.1.
+
 Every per-family constant no vendor table states carries its provenance — whether it was
 vendor-stated, derived or assumed, and by whom on what date. The types enforce it: an assumed fact
 without a note, a date and initials does not compile.
@@ -80,7 +108,9 @@ without a note, a date and initials does not compile.
 - [`docs/ADDING-A-VENDOR.md`](docs/ADDING-A-VENDOR.md) — the runbook.
 - [`docs/KENNAMETAL_CAD_API.md`](docs/KENNAMETAL_CAD_API.md),
   [`docs/KENNAMETAL_SPEEDFEED_API.md`](docs/KENNAMETAL_SPEEDFEED_API.md),
-  [`docs/REGOFIX_PRODUCTFINDER_API.md`](docs/REGOFIX_PRODUCTFINDER_API.md) — how each endpoint was
+  [`docs/REGOFIX_PRODUCTFINDER_API.md`](docs/REGOFIX_PRODUCTFINDER_API.md),
+  [`docs/HARVEY_PRODUCT_TABLE.md`](docs/HARVEY_PRODUCT_TABLE.md),
+  [`docs/MARITOOL_CATALOG.md`](docs/MARITOOL_CATALOG.md) — how each endpoint or table was
   found, and the dead ends tried first.
 - [`../../docs/TOOL-SCRAPER-PLAN.md`](../../docs/TOOL-SCRAPER-PLAN.md) — the structure, the evidence
   behind it, and what has landed.

package/dist/columns.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Reading one canonical field out of a scraped row, for every vendor whose CSV
+ * holds display strings rather than numbers.
+ *
+ * Two vendors publish a receipt of the vendor's own text — Harvey Tool and
+ * EMUGE-FRANKEN — and a mapper for either one needs the same three steps
+ * between a `GeometryName` and a number: ask the family's `ColumnMap` which
+ * column that field is in, read the cell, and decide what an unreadable one
+ * costs. Those three were a verbatim copy in both mappers, down to the wording
+ * of the refusal, which is the same argument `measure.ts` makes one level down:
+ * two copies of four lines is cheap and two copies of the **decision** is not.
+ *
+ * ## What is shared and what is not
+ *
+ * The vendor supplies the grammar, as a {@link LengthReader} — Harvey's
+ * `dimension` reads `.250 (1/4)` and a `-` that means "does not apply", EMUGE's
+ * `measureIn` reads `1 1/2 "` and refuses a range. What this module owns is
+ * everything either side of that call:
+ *
+ * - a column the family maps to nothing is `undefined`, not an error — a family
+ *   with no neck column is a plain tool, and that is the mapper's fallback to
+ *   make;
+ * - a **required** field with no reading refuses the row with an
+ *   `errors.IncompletePartError`, naming the canonical field and quoting the
+ *   cell, because a tool with no cutting diameter is not a part — and that is
+ *   the one refusal `registry.toRecords` skips past rather than failing the
+ *   whole family on;
+ * - an **optional** one answers null and lets the mapper decide.
+ *
+ * `vendors/destinytool/records.ts` keeps its own `required` and is not wired
+ * through here: it reads a dimension out of free text rather than out of a
+ * cell, throws `RangeError` from its own parser rather than answering null, and
+ * has no `optional` at all. Forcing it into this shape would change how it
+ * refuses, which is the one thing `measure.ts` says is a vendor's own call.
+ */
+import type { UnitSystem } from './conventions.js';
+import type { ColumnMap, GeometryName } from './records.js';
+import type { MapperOptions, ScrapedRow, Warn } from './scrape.js';
+/**
+ * How one vendor turns its own display cell into a length in `unit`.
+ *
+ * The signature `vendors/harvey/value.ts`'s `dimension` and
+ * `vendors/emuge/value.ts`'s `measureIn` already have.
+ */
+export type LengthReader = (display: string, unit: UnitSystem, what: string, warn?: Warn) => number | null;
+/** The three readers a display-string mapper needs, bound to one grammar. */
+export interface ColumnReaders {
+    /** One canonical field's cell, or undefined where the family maps none. */
+    cell(row: ScrapedRow, columns: ColumnMap, canonical: GeometryName, unit: UnitSystem): string | undefined;
+    /** A dimension the kind requires, refusing a row the vendor left blank. */
+    required(row: ScrapedRow, columns: ColumnMap, canonical: GeometryName, unit: UnitSystem, what: string, options: MapperOptions): number;
+    /** A dimension the contract does not require. Null where there is none. */
+    optional(row: ScrapedRow, columns: ColumnMap, canonical: GeometryName, unit: UnitSystem, what: string, options: MapperOptions): number | null;
+}
+/**
+ * The three readers, over one vendor's `read`.
+ *
+ * `columns` is the caller's map and not `family.columns`. They are the same
+ * object through `registry.toRecords` — but `RecordMapper` passes one as an
+ * argument, `registry` validates *that* one with `checkColumnsExist`, and a
+ * mapper reading a different reference is validating one map and reading
+ * another.
+ */
+export declare function columnReaders(read: LengthReader): ColumnReaders;

package/dist/columns.js

@@ -0,0 +1,68 @@
+/**
+ * Reading one canonical field out of a scraped row, for every vendor whose CSV
+ * holds display strings rather than numbers.
+ *
+ * Two vendors publish a receipt of the vendor's own text — Harvey Tool and
+ * EMUGE-FRANKEN — and a mapper for either one needs the same three steps
+ * between a `GeometryName` and a number: ask the family's `ColumnMap` which
+ * column that field is in, read the cell, and decide what an unreadable one
+ * costs. Those three were a verbatim copy in both mappers, down to the wording
+ * of the refusal, which is the same argument `measure.ts` makes one level down:
+ * two copies of four lines is cheap and two copies of the **decision** is not.
+ *
+ * ## What is shared and what is not
+ *
+ * The vendor supplies the grammar, as a {@link LengthReader} — Harvey's
+ * `dimension` reads `.250 (1/4)` and a `-` that means "does not apply", EMUGE's
+ * `measureIn` reads `1 1/2 "` and refuses a range. What this module owns is
+ * everything either side of that call:
+ *
+ * - a column the family maps to nothing is `undefined`, not an error — a family
+ *   with no neck column is a plain tool, and that is the mapper's fallback to
+ *   make;
+ * - a **required** field with no reading refuses the row with an
+ *   `errors.IncompletePartError`, naming the canonical field and quoting the
+ *   cell, because a tool with no cutting diameter is not a part — and that is
+ *   the one refusal `registry.toRecords` skips past rather than failing the
+ *   whole family on;
+ * - an **optional** one answers null and lets the mapper decide.
+ *
+ * `vendors/destinytool/records.ts` keeps its own `required` and is not wired
+ * through here: it reads a dimension out of free text rather than out of a
+ * cell, throws `RangeError` from its own parser rather than answering null, and
+ * has no `optional` at all. Forcing it into this shape would change how it
+ * refuses, which is the one thing `measure.ts` says is a vendor's own call.
+ */
+import { IncompletePartError } from './errors.js';
+/**
+ * The three readers, over one vendor's `read`.
+ *
+ * `columns` is the caller's map and not `family.columns`. They are the same
+ * object through `registry.toRecords` — but `RecordMapper` passes one as an
+ * argument, `registry` validates *that* one with `checkColumnsExist`, and a
+ * mapper reading a different reference is validating one map and reading
+ * another.
+ */
+export function columnReaders(read) {
+    const cell = (row, columns, canonical, unit) => {
+        const column = columns.column(canonical, unit);
+        return column === null ? undefined : row[column];
+    };
+    const optional = (row, columns, canonical, unit, what, options) => {
+        const raw = cell(row, columns, canonical, unit);
+        return raw === undefined ? null : read(raw, unit, what, options.warn);
+    };
+    const required = (row, columns, canonical, unit, what, options) => {
+        const raw = cell(row, columns, canonical, unit);
+        const value = raw === undefined ? null : read(raw, unit, what, options.warn);
+        if (value === null) {
+            // `IncompletePartError` and not the general vendor fault: this is the
+            // one refusal `registry.toRecords` skips past, because a single part the
+            // vendor left a cell blank on must not end a family's conversion. See
+            // that type for why the others still must not be skipped.
+            throw new IncompletePartError(what, `publishes no ${canonical} — its cell is ${JSON.stringify(raw ?? '')}`);
+        }
+        return value;
+    };
+    return { cell, required, optional };
+}

package/dist/conventions.d.ts

@@ -12,14 +12,19 @@
  * *across* the CSVs anyway, and the reason to make them explicit is that
  * vendor #3 already drifted from one:
  *
- * | Convention                                        | Held by                   |
- * | ------------------------------------------------- | ------------------------- |
- * | `_mm`/`_in` carries the unit on a dimension       | all three                 |
- * | Multi-value cells are space-separated             | all three                 |
- * | One row per orderable part                        | all three                 |
- * | `CAD_STEP_URL` names a CAD model where one exists | Kennametal, REGO-FIX      |
- * | Unmapped vendor codes keep a `DIN_` prefix        | REGO-FIX; rule is general |
- * | The identity columns                              | **broken** — see below    |
+ * | Convention                                         | Held by                   |
+ * | -------------------------------------------------- | ------------------------- |
+ * | `_mm`/`_in` carries the unit on a dimension        | all five                  |
+ * | Multi-value cells are space-separated              | all five                  |
+ * | One row per orderable part                         | all five                  |
+ * | `CAD_STEP_URL` names a CAD model where one exists  | Kennametal, REGO-FIX      |
+ * | `CAD_DXF_URL` names a 2D profile where one exists  | Harvey, MariTool          |
+ * | `Description` carries the vendor's own free text   | Harvey, MariTool          |
+ * | `contact` says how a holder seats                  | REGO-FIX, MariTool        |
+ * | `CST` names the collet series a holder takes       | REGO-FIX, MariTool        |
+ * | `L1_in`/`L1_mm` carry a holder's gage length       | REGO-FIX, MariTool        |
+ * | Unmapped vendor codes keep a `DIN_` prefix         | REGO-FIX; rule is general |
+ * | The identity columns                               | **broken** — see below    |
  *
  * Identity and units are the two worth enforcing; the rest are advisory, and
  * are here so that "advisory" is a decision on the page rather than an
@@ -63,6 +68,87 @@ export declare const UNIT_SUFFIX: Record<UnitSystem, string>;
  * neither owns it — the leak the vendor-boundary test exists to catch.
  */
 export declare const CAD_COLUMN = "CAD_STEP_URL";
+/**
+ * The CSV column holding a part's downloadable 2D DXF profile.
+ *
+ * A second column rather than a second thing written into {@link CAD_COLUMN},
+ * because a DXF is not a STEP model: one is a flat profile a machinist prints
+ * or traces, the other is the solid a CAM system imports. Harvey Tool publishes
+ * a DXF for 12,773 of its 12,799 parts and a STEP for none of them, so writing
+ * its link into `CAD_STEP_URL` would repeat exactly the mistake the
+ * `CAD_STP_LWM` -> `CAD_STEP_URL` rename fixed on 2026-08-08 — a column name
+ * that is a claim about the data, and false.
+ *
+ * Vendor-neutral and beside `CAD_COLUMN` for the same reason that one is: a
+ * format is not one manufacturer's fact, and the second vendor to publish a DXF
+ * must write it into this column rather than inventing another.
+ */
+export declare const CAD_DXF_COLUMN = "CAD_DXF_URL";
+/**
+ * The CSV column holding the vendor's own free text about one part.
+ *
+ * Harvey Tool writes a product title here and MariTool a product name; both are
+ * the vendor's own prose rather than a designation this package composed. It is
+ * here and not in either adapter for the reason {@link CAD_COLUMN} is: two of
+ * them write it and neither owns it.
+ *
+ * **Not every vendor publishes one, and `''` is the answer where none does** —
+ * a description that restates the catalog number is not a description. See
+ * `records.ToolRecord.description`, which states the same rule for the record.
+ */
+export declare const DESCRIPTION_COLUMN = "Description";
+/**
+ * The CSV column holding the vendor's own full name for the family a part is
+ * in — `KenCut™ FF • HPFT • Square End • 6 Flutes • Plain Shank • Inch`.
+ *
+ * Constant down a family's whole table, and that is what makes it a *family*
+ * title rather than a {@link DESCRIPTION_COLUMN}: it names the group, not the
+ * part. Kennametal and WIDIA publish one as the `h1` of a family page and it
+ * reaches the CSV whole, while `records.ToolRecord.productLine` keeps only its
+ * leading segment — the rest is the vendor's own wording for the shape, the
+ * flute count, the shank and the unit, and a receipt that dropped it would be
+ * throwing away published text to save a column.
+ *
+ * Vendor-neutral and here rather than in the Kennametal adapter for the reason
+ * {@link CAD_COLUMN} is: a second vendor that publishes a family title writes
+ * this column rather than inventing another. Nothing forces one to — a vendor
+ * whose parts carry no family title simply has no such column.
+ */
+export declare const FAMILY_TITLE_COLUMN = "Family Title";
+/**
+ * The CSV column saying how a holder seats in the spindle: `taper` or `face`.
+ *
+ * `face` is dual contact — the flange face seats at the same time as the cone.
+ * REGO-FIX resolves it from its own `form_name` and MariTool from its `Taper`
+ * cell, which is the right shape: **how** a vendor states it is that vendor's
+ * business, and what the column is called is not.
+ */
+export declare const CONTACT_COLUMN = "contact";
+/**
+ * The CSV column naming the collet series a holder accepts — `ER16`, `PG25`.
+ *
+ * The join key between a holder family and a collet family, which is exactly
+ * why it cannot be spelled twice: `families/kennametal.ts` states the join
+ * against this column, and two spellings of it join to nothing. Both vendors
+ * that publish it close the vendor's own spacing before writing it here, for
+ * the same reason.
+ */
+export declare const COLLET_SERIES_COLUMN = "CST";
+/**
+ * The CSV columns carrying a holder's gage length, one per unit system.
+ *
+ * A **pair** with exactly one cell filled, rather than one column and a unit
+ * tag, because a single catalog page can publish both: MariTool gages
+ * `HSK40E-ER11-40` in millimetres and `HSK40E-ER16-3.0M` in inches on one
+ * listing. Nothing is converted between them — the vendor's own imperial
+ * conversion is unusable and computing one here would put a number in the file
+ * the vendor never published.
+ *
+ * REGO-FIX fills only the millimetre cell, because its DIN 4000 documents are
+ * metric throughout; the pair is still the shape, so the two vendors' holder
+ * CSVs answer the same question with the same columns.
+ */
+export declare const GAGE_COLUMNS: Record<UnitSystem, string>;
 /**
  * The prefix an unmapped vendor code keeps, so it cannot read as a dimension.
  *
@@ -85,13 +171,19 @@ export declare const IDENTITY_COLUMNS: readonly ["Material Number", "ISO Catalog
  * Where a vendor's CSV does not use {@link IDENTITY_COLUMNS}, and what it uses
  * instead.
  *
- * **One entry, and it is a record of drift rather than a licence.** REGO-FIX
- * adopted Kennametal's identity labels; Destiny Tool passes Firestore's own
- * `itemNumber` straight through and publishes no catalog designation at all —
- * the convention was real but informal, and it eroded the first time a vendor
- * did not resemble the first two. Writing the deviation down is what makes the
- * fourth vendor's drift a decision somebody made rather than a thing that
- * happened.
+ * **Three entries, and they are a record of drift rather than a licence.**
+ * REGO-FIX adopted Kennametal's identity labels; Destiny Tool passes
+ * Firestore's own `itemNumber` straight through and publishes no catalog
+ * designation at all — the convention was real but informal, and it eroded the
+ * first time a vendor did not resemble the first two. Writing the deviation
+ * down is what makes the next vendor's drift a decision somebody made rather
+ * than a thing that happened.
+ *
+ * Harvey Tool and MariTool are the honest kind, and they are now the majority:
+ * both genuinely publish one identifier per part, so their entries record a
+ * fact about the vendor rather than a shortcut taken here. Two of the two
+ * vendors added since the convention was written have needed one, which says
+ * the two-column shape is Kennametal's rather than the industry's.
  */
 export declare const IDENTITY_DEVIATIONS: Partial<Record<BrandName, readonly string[]>>;
 /**

package/dist/conventions.js

@@ -12,14 +12,19 @@
  * *across* the CSVs anyway, and the reason to make them explicit is that
  * vendor #3 already drifted from one:
  *
- * | Convention                                        | Held by                   |
- * | ------------------------------------------------- | ------------------------- |
- * | `_mm`/`_in` carries the unit on a dimension       | all three                 |
- * | Multi-value cells are space-separated             | all three                 |
- * | One row per orderable part                        | all three                 |
- * | `CAD_STEP_URL` names a CAD model where one exists | Kennametal, REGO-FIX      |
- * | Unmapped vendor codes keep a `DIN_` prefix        | REGO-FIX; rule is general |
- * | The identity columns                              | **broken** — see below    |
+ * | Convention                                         | Held by                   |
+ * | -------------------------------------------------- | ------------------------- |
+ * | `_mm`/`_in` carries the unit on a dimension        | all five                  |
+ * | Multi-value cells are space-separated              | all five                  |
+ * | One row per orderable part                         | all five                  |
+ * | `CAD_STEP_URL` names a CAD model where one exists  | Kennametal, REGO-FIX      |
+ * | `CAD_DXF_URL` names a 2D profile where one exists  | Harvey, MariTool          |
+ * | `Description` carries the vendor's own free text   | Harvey, MariTool          |
+ * | `contact` says how a holder seats                  | REGO-FIX, MariTool        |
+ * | `CST` names the collet series a holder takes       | REGO-FIX, MariTool        |
+ * | `L1_in`/`L1_mm` carry a holder's gage length       | REGO-FIX, MariTool        |
+ * | Unmapped vendor codes keep a `DIN_` prefix         | REGO-FIX; rule is general |
+ * | The identity columns                               | **broken** — see below    |
  *
  * Identity and units are the two worth enforcing; the rest are advisory, and
  * are here so that "advisory" is a decision on the page rather than an
@@ -64,6 +69,90 @@ export const UNIT_SUFFIX = {
  * neither owns it — the leak the vendor-boundary test exists to catch.
  */
 export const CAD_COLUMN = 'CAD_STEP_URL';
+/**
+ * The CSV column holding a part's downloadable 2D DXF profile.
+ *
+ * A second column rather than a second thing written into {@link CAD_COLUMN},
+ * because a DXF is not a STEP model: one is a flat profile a machinist prints
+ * or traces, the other is the solid a CAM system imports. Harvey Tool publishes
+ * a DXF for 12,773 of its 12,799 parts and a STEP for none of them, so writing
+ * its link into `CAD_STEP_URL` would repeat exactly the mistake the
+ * `CAD_STP_LWM` -> `CAD_STEP_URL` rename fixed on 2026-08-08 — a column name
+ * that is a claim about the data, and false.
+ *
+ * Vendor-neutral and beside `CAD_COLUMN` for the same reason that one is: a
+ * format is not one manufacturer's fact, and the second vendor to publish a DXF
+ * must write it into this column rather than inventing another.
+ */
+export const CAD_DXF_COLUMN = 'CAD_DXF_URL';
+/**
+ * The CSV column holding the vendor's own free text about one part.
+ *
+ * Harvey Tool writes a product title here and MariTool a product name; both are
+ * the vendor's own prose rather than a designation this package composed. It is
+ * here and not in either adapter for the reason {@link CAD_COLUMN} is: two of
+ * them write it and neither owns it.
+ *
+ * **Not every vendor publishes one, and `''` is the answer where none does** —
+ * a description that restates the catalog number is not a description. See
+ * `records.ToolRecord.description`, which states the same rule for the record.
+ */
+export const DESCRIPTION_COLUMN = 'Description';
+/**
+ * The CSV column holding the vendor's own full name for the family a part is
+ * in — `KenCut™ FF • HPFT • Square End • 6 Flutes • Plain Shank • Inch`.
+ *
+ * Constant down a family's whole table, and that is what makes it a *family*
+ * title rather than a {@link DESCRIPTION_COLUMN}: it names the group, not the
+ * part. Kennametal and WIDIA publish one as the `h1` of a family page and it
+ * reaches the CSV whole, while `records.ToolRecord.productLine` keeps only its
+ * leading segment — the rest is the vendor's own wording for the shape, the
+ * flute count, the shank and the unit, and a receipt that dropped it would be
+ * throwing away published text to save a column.
+ *
+ * Vendor-neutral and here rather than in the Kennametal adapter for the reason
+ * {@link CAD_COLUMN} is: a second vendor that publishes a family title writes
+ * this column rather than inventing another. Nothing forces one to — a vendor
+ * whose parts carry no family title simply has no such column.
+ */
+export const FAMILY_TITLE_COLUMN = 'Family Title';
+/**
+ * The CSV column saying how a holder seats in the spindle: `taper` or `face`.
+ *
+ * `face` is dual contact — the flange face seats at the same time as the cone.
+ * REGO-FIX resolves it from its own `form_name` and MariTool from its `Taper`
+ * cell, which is the right shape: **how** a vendor states it is that vendor's
+ * business, and what the column is called is not.
+ */
+export const CONTACT_COLUMN = 'contact';
+/**
+ * The CSV column naming the collet series a holder accepts — `ER16`, `PG25`.
+ *
+ * The join key between a holder family and a collet family, which is exactly
+ * why it cannot be spelled twice: `families/kennametal.ts` states the join
+ * against this column, and two spellings of it join to nothing. Both vendors
+ * that publish it close the vendor's own spacing before writing it here, for
+ * the same reason.
+ */
+export const COLLET_SERIES_COLUMN = 'CST';
+/**
+ * The CSV columns carrying a holder's gage length, one per unit system.
+ *
+ * A **pair** with exactly one cell filled, rather than one column and a unit
+ * tag, because a single catalog page can publish both: MariTool gages
+ * `HSK40E-ER11-40` in millimetres and `HSK40E-ER16-3.0M` in inches on one
+ * listing. Nothing is converted between them — the vendor's own imperial
+ * conversion is unusable and computing one here would put a number in the file
+ * the vendor never published.
+ *
+ * REGO-FIX fills only the millimetre cell, because its DIN 4000 documents are
+ * metric throughout; the pair is still the shape, so the two vendors' holder
+ * CSVs answer the same question with the same columns.
+ */
+export const GAGE_COLUMNS = {
+    inches: 'L1_in',
+    millimeters: 'L1_mm',
+};
 /**
  * The prefix an unmapped vendor code keeps, so it cannot read as a dimension.
  *
@@ -86,16 +175,38 @@ export const IDENTITY_COLUMNS = ['Material Number', 'ISO Catalog Number'];
  * Where a vendor's CSV does not use {@link IDENTITY_COLUMNS}, and what it uses
  * instead.
  *
- * **One entry, and it is a record of drift rather than a licence.** REGO-FIX
- * adopted Kennametal's identity labels; Destiny Tool passes Firestore's own
- * `itemNumber` straight through and publishes no catalog designation at all —
- * the convention was real but informal, and it eroded the first time a vendor
- * did not resemble the first two. Writing the deviation down is what makes the
- * fourth vendor's drift a decision somebody made rather than a thing that
- * happened.
+ * **Three entries, and they are a record of drift rather than a licence.**
+ * REGO-FIX adopted Kennametal's identity labels; Destiny Tool passes
+ * Firestore's own `itemNumber` straight through and publishes no catalog
+ * designation at all — the convention was real but informal, and it eroded the
+ * first time a vendor did not resemble the first two. Writing the deviation
+ * down is what makes the next vendor's drift a decision somebody made rather
+ * than a thing that happened.
+ *
+ * Harvey Tool and MariTool are the honest kind, and they are now the majority:
+ * both genuinely publish one identifier per part, so their entries record a
+ * fact about the vendor rather than a shortcut taken here. Two of the two
+ * vendors added since the convention was written have needed one, which says
+ * the two-column shape is Kennametal's rather than the industry's.
  */
 export const IDENTITY_DEVIATIONS = {
     destinytool: ['itemNumber'],
+    // Harvey Tool publishes exactly one number per part — the `Tool #` its own
+    // table column is headed with, which is also the segment of its per-part URL
+    // — and no second catalog designation anywhere on a product page or a part
+    // page. Inventing an `ISO Catalog Number` to satisfy the convention would put
+    // a column in the CSV that the vendor does not publish, which is the one
+    // thing a receipt must not do.
+    harvey: ['Tool #'],
+    // MariTool publishes one number per part — the `Part#` line its own listing
+    // rows are headed with, which is also what its `Available Downloads for …`
+    // header restates and what its search endpoint matches on — and no second
+    // catalog designation anywhere on a category page or a product page. The
+    // store's `products_id` is not that second number: it is an internal id a
+    // re-created product would change, and every guid minted off it with it.
+    // Same call as Harvey's, and the honest kind: the entry records a fact about
+    // the vendor rather than a shortcut taken here.
+    maritool: ['Material Number'],
 };
 /**
  * A vendor's bare column label, suffixed for `unit`.

package/dist/errors.d.ts

@@ -10,6 +10,9 @@
  *   cannot read.** The variants endpoint changed shape, a scrape's row count
  *   disagrees with the declared one, a DIN 4000 code that should be pinned is
  *   absent. The catalog is fine; the world moved.
+ * - {@link IncompletePartError} — **one part is missing a measurement it
+ *   cannot be a part without.** A narrower case of the second, and the only
+ *   one `registry.toRecords` may skip past: see below.
  *
  * They throw rather than exiting the process: a Node backend imports this, and
  * a mapped column that moved must not take down somebody's request handler.
@@ -43,4 +46,31 @@ export declare class ScraperConfigError extends ScraperError {
  */
 export declare class VendorResponseError extends ScraperError {
 }
+/**
+ * One part does not publish a dimension its kind requires.
+ *
+ * **The only failure a whole family survives.** `registry.toRecords` maps a
+ * family's rows together, so before this type existed every refusal was
+ * equally fatal: one part with an unpublished cell ended the conversion and
+ * took every other row with it. EMUGE-FRANKEN omits `overall length l₁` on
+ * roughly 175 of its 7,021 end mill variants, and both end mill families
+ * produced nothing at all because of them.
+ *
+ * It is a distinct type rather than a flag on {@link VendorResponseError}
+ * because the two must not be skipped alike. A cutting material this package
+ * has no word for, a point-angle column a family stopped mapping, a variants
+ * table that changed shape — those are the vendor's vocabulary or this
+ * package's map having moved, and skipping past them quietly is how a scraper
+ * starts publishing a catalog nobody checked. Only `columns.required` raises
+ * this one, and only for a cell the vendor left unpublished.
+ *
+ * **It is not a licence to relax a kind's contract.** `records.RECORD_GEOMETRY`
+ * still says an end mill always has an `OAL`, and that stays true of every
+ * record this package emits: a part without one does not become a record with
+ * a hole in it, it becomes no record and a warning. Where a *vendor* genuinely
+ * never publishes a field, the answer is still `sometimes` — that is what a
+ * drill's `SIG` is, and why one is a contract decision and the other is not.
+ */
+export declare class IncompletePartError extends VendorResponseError {
+}
 export {};

package/dist/errors.js

@@ -10,6 +10,9 @@
  *   cannot read.** The variants endpoint changed shape, a scrape's row count
  *   disagrees with the declared one, a DIN 4000 code that should be pinned is
  *   absent. The catalog is fine; the world moved.
+ * - {@link IncompletePartError} — **one part is missing a measurement it
+ *   cannot be a part without.** A narrower case of the second, and the only
+ *   one `registry.toRecords` may skip past: see below.
  *
  * They throw rather than exiting the process: a Node backend imports this, and
  * a mapped column that moved must not take down somebody's request handler.
@@ -51,3 +54,30 @@ export class ScraperConfigError extends ScraperError {
  */
 export class VendorResponseError extends ScraperError {
 }
+/**
+ * One part does not publish a dimension its kind requires.
+ *
+ * **The only failure a whole family survives.** `registry.toRecords` maps a
+ * family's rows together, so before this type existed every refusal was
+ * equally fatal: one part with an unpublished cell ended the conversion and
+ * took every other row with it. EMUGE-FRANKEN omits `overall length l₁` on
+ * roughly 175 of its 7,021 end mill variants, and both end mill families
+ * produced nothing at all because of them.
+ *
+ * It is a distinct type rather than a flag on {@link VendorResponseError}
+ * because the two must not be skipped alike. A cutting material this package
+ * has no word for, a point-angle column a family stopped mapping, a variants
+ * table that changed shape — those are the vendor's vocabulary or this
+ * package's map having moved, and skipping past them quietly is how a scraper
+ * starts publishing a catalog nobody checked. Only `columns.required` raises
+ * this one, and only for a cell the vendor left unpublished.
+ *
+ * **It is not a licence to relax a kind's contract.** `records.RECORD_GEOMETRY`
+ * still says an end mill always has an `OAL`, and that stays true of every
+ * record this package emits: a part without one does not become a record with
+ * a hole in it, it becomes no record and a warning. Where a *vendor* genuinely
+ * never publishes a field, the answer is still `sometimes` — that is what a
+ * drill's `SIG` is, and why one is a contract decision and the other is not.
+ */
+export class IncompletePartError extends VendorResponseError {
+}