@toolpath/tool-scraper 2.0.0 → 2.2.0

package/dist/vendors/maritool/scrape.js

@@ -26,11 +26,16 @@
  *
  * ## What the vendor gets wrong
  *
- * Four faults found on 2026-08-29, all reported as warnings rather than
+ * Four faults found on 2026-08-29. Three are reported as warnings rather than
  * fixed — two disagreeing vendor cells cannot say which one is wrong, and a
  * scraper that corrects one becomes a place tool data is authored by hand.
  * This is the same call `vendors/regofix/scrape.ts` made on its three.
  *
+ * The fourth is resolved rather than reported, and the difference is where the
+ * answer came from: `docs/ADDING-A-VENDOR.md` says that when a vendor label is
+ * unclear you **ask**, and record the answer and its date. That is what
+ * happened — see fault 2.
+ *
  * 1. **`BT40-ER32-60` publishes no `Taper` row at all**, alone among the 529
  *    parts in scope. Its row is kept with `taper` and `contact` empty rather
  *    than dropped or filled in from its part number: the CSV is a receipt, and
@@ -38,10 +43,21 @@
  * 2. **`Collet Size` carries a collet *nut* designation on two parts.**
  *    `CAT40-ER25-3.0MD` and `BT30-ER25-60M` both state `ER25M`, and `ER25M` is
  *    not a collet series — `HSK40E-ER16-3.0M` puts exactly that shape of value
- *    in its own `Collet Nut` cell, which is the column it belongs in. The
- *    string is written into `CST` as designated, so it joins to no collet
- *    family, and it is warned about. Widening it to `ER25` would offer a
- *    machinist a collet that may not seat.
+ *    in its own `Collet Nut` cell, which is the column it belongs in.
+ *
+ *    **`ER25M` is the mini collet nut series, and the collet it closes is a
+ *    plain ER25** (JG 2026-09-02). So {@link colletSeries} resolves the cell to
+ *    the collet the holder actually takes, and the two parts join to the ER25
+ *    collets they fit. Until that answer existed the string was written through
+ *    as designated and warned about, because widening a series on a guess is
+ *    how a machinist is offered a collet that does not seat — and the cost of
+ *    being wrong the other way was one option, not a purchase.
+ *
+ *    **Nothing is lost by resolving it.** `Collet Size` is one of the vendor's
+ *    own labels and is carried into the CSV verbatim, so the receipt still says
+ *    `ER25M` and still says which of the two parts has a mini nut. What changes
+ *    is only `CST`, which is a derived join key rather than a record of what the
+ *    vendor published — the same thing the spacing rule below does to it.
  * 3. **`Collet Size` is spaced inconsistently within one style** — `ER 11`
  *    and `ER11` are both published. {@link colletSeries} closes the space,
  *    because `CST` is a join key and two spellings of one series join to
@@ -444,21 +460,44 @@ export function parseGageLength(cell) {
     const unit = (parsed?.[2] ?? '').toLowerCase() === 'mm' ? 'millimeters' : 'inches';
     return { value, unit };
 }
+/**
+ * A `Collet Size` cell that names the **nut** rather than the collet.
+ *
+ * `M` is MariTool's mini collet nut, and the collet a mini nut closes is the
+ * plain one of that series (JG 2026-09-02). The vendor's own `Collet Nut`
+ * column carries `ER11M`, `ER16M`, `ER20M` and `ER25M` beside a `Collet Size`
+ * of plain `ER 11`, `ER 16`, `ER 20` and `ER 25` on 57 parts, which is the
+ * column those values belong in.
+ *
+ * Anchored on `ER\d+` rather than stripping a trailing letter, so a suffix that
+ * turns out to designate something else still reaches {@link holderRow}'s
+ * warning instead of being quietly shortened into a series that fits nothing.
+ */
+const NUT_DESIGNATION = /^(ER\d+)M$/;
 /**
  * A `Collet Size` cell as the series `CST` joins a collet family on.
  *
- * Only the spacing is closed. MariTool publishes `ER 11` and `ER11` within one
- * style, and two spellings of one series join to nothing — `CST` is the key
- * `families/kennametal.ts` states the holder-to-collet join against, and the
- * collet side of it spells the series without a space.
+ * **Derived, not a receipt.** `CST` is the key `families/kennametal.ts` states
+ * the holder-to-collet join against, so what belongs in it is the series of the
+ * collet the holder takes. The vendor's own cell is carried into the CSV under
+ * its own label and untouched, which is where the two normalisations below are
+ * still visible.
+ *
+ * Two things are closed, and both exist because two spellings of one series
+ * join to nothing:
+ *
+ * - **Spacing.** MariTool publishes `ER 11` and `ER11` within one style, and
+ *   the collet side of the join spells the series without a space.
+ * - **A nut designation.** `ER25M` names a mini nut, not a collet series — see
+ *   {@link NUT_DESIGNATION} and this module's docstring.
  *
- * Nothing else is normalised. `ER25M` is written through as designated even
- * though no such collet series exists, because the alternative is to decide on
- * the vendor's behalf that its `M` is the mini nut its `Collet Nut` column
- * carries elsewhere — see this module's docstring. {@link holderRow} warns.
+ * Nothing else is. A cell this leaves as neither `ER<n>` nor a nut designation
+ * is written through as the vendor designated it, and {@link holderRow} warns
+ * that it joins to no collet.
  */
 export function colletSeries(cell) {
-    return cell.replace(/\s+/g, '');
+    const closed = cell.replace(/\s+/g, '');
+    return NUT_DESIGNATION.exec(closed)?.[1] ?? closed;
 }
 /**
  * One listing row plus its spec table -> one CSV row.

package/dist/vendors/regofix/holding.d.ts

@@ -0,0 +1,35 @@
+/**
+ * REGO-FIX's toolholding column vocabulary, and nothing else.
+ *
+ * Two things about this vendor decide the shape of what is below, and both are
+ * the reverse of Kennametal's:
+ *
+ * - **`contact` is a column, not a family fact.** REGO-FIX publishes plain and
+ *   dual-contact powRgrip in one product group — `BT 30 / PG 25 x 080 H` and
+ *   `BT+ 30 / PG 25 x 080 H` are two rows of one table — so `scrape.holderRow`
+ *   resolves it from the vendor's own `form_name` and writes
+ *   `conventions.CONTACT_COLUMN`. `families/regofix.ts` deliberately declares no
+ *   `contact` fact, and reading one here would silently mask a scrape that lost
+ *   the column.
+ * - **`unit` is a column on a collet.** Every one of the twelve PG groups holds
+ *   metric and fractional-inch collets side by side, so there is no
+ *   family-level answer to declare, and none of the collet families declares
+ *   one.
+ *
+ * ## What a powRgrip holder does not publish
+ *
+ * No `D1`. A powRgrip holder clamps through a PG collet, and a collet-clamping
+ * holder that also carried a bore would be claiming two ways of gripping one
+ * tool — `scrape.holderRow` says so, and `holding.checkHolder` refuses it.
+ *
+ * No `L2`, `L9`, `V` or `D11` either: the DIN 4000 documents publish `A2`, `B1`
+ * and `B2`, whose meaning is not stated anywhere this package has been able to
+ * check, and they stay behind `conventions.DIN_PREFIX` rather than being guessed
+ * at. `B3`, the projection length, *is* pinned and understood — it is the
+ * `x 050` of the designation — and it is still not on the record, under
+ * `records.ToolRecord`'s standing rule that a field arrives when something
+ * displays it.
+ */
+import { type HoldingMappers } from '../../holding.js';
+/** The toolholding half of the adapter contract `registry` looks up by brand. */
+export declare const HOLDING_MAPPERS: HoldingMappers;

package/dist/vendors/regofix/holding.js

@@ -0,0 +1,108 @@
+/**
+ * REGO-FIX's toolholding column vocabulary, and nothing else.
+ *
+ * Two things about this vendor decide the shape of what is below, and both are
+ * the reverse of Kennametal's:
+ *
+ * - **`contact` is a column, not a family fact.** REGO-FIX publishes plain and
+ *   dual-contact powRgrip in one product group — `BT 30 / PG 25 x 080 H` and
+ *   `BT+ 30 / PG 25 x 080 H` are two rows of one table — so `scrape.holderRow`
+ *   resolves it from the vendor's own `form_name` and writes
+ *   `conventions.CONTACT_COLUMN`. `families/regofix.ts` deliberately declares no
+ *   `contact` fact, and reading one here would silently mask a scrape that lost
+ *   the column.
+ * - **`unit` is a column on a collet.** Every one of the twelve PG groups holds
+ *   metric and fractional-inch collets side by side, so there is no
+ *   family-level answer to declare, and none of the collet families declares
+ *   one.
+ *
+ * ## What a powRgrip holder does not publish
+ *
+ * No `D1`. A powRgrip holder clamps through a PG collet, and a collet-clamping
+ * holder that also carried a bore would be claiming two ways of gripping one
+ * tool — `scrape.holderRow` says so, and `holding.checkHolder` refuses it.
+ *
+ * No `L2`, `L9`, `V` or `D11` either: the DIN 4000 documents publish `A2`, `B1`
+ * and `B2`, whose meaning is not stated anywhere this package has been able to
+ * check, and they stay behind `conventions.DIN_PREFIX` rather than being guessed
+ * at. `B3`, the projection length, *is* pinned and understood — it is the
+ * `x 050` of the designation — and it is still not on the record, under
+ * `records.ToolRecord`'s standing rule that a field arrives when something
+ * displays it.
+ */
+import { CAD_COLUMN, COLLET_DESIGNATION_COLUMN, COLLET_SERIES_COLUMN, CONTACT_COLUMN, } from '../../conventions.js';
+import { familyBrand } from '../../family.js';
+import { checkUnitAgreement, clampingMode, colletRecord, contactMode, dim, holderRecord, holdingFact, published, unitSystem, } from '../../holding.js';
+import { consoleWarn } from '../../scrape.js';
+/** The identity columns this vendor adopted from Kennametal, being second. */
+const MATERIAL_NUMBER = 'Material Number';
+const CATALOG_NUMBER = 'ISO Catalog Number';
+/**
+ * The column `scrape.colletRow` writes the system it read off a designation to.
+ *
+ * REGO-FIX's own, and not a convention: it is the only vendor here that states
+ * a unit per row, so there is no second writer for the name to be shared with.
+ */
+const UNIT_COLUMN = 'unit';
+/** How a part names itself in a warning or a refusal. */
+function subject(row) {
+    return `${row[CATALOG_NUMBER] ?? ''} (${row[MATERIAL_NUMBER] ?? ''})`;
+}
+/** One powRgrip holder row -> one {@link HolderRecord}. */
+function holder(row, family) {
+    const what = subject(row);
+    const unit = holdingFact(family, 'unit', family.unit);
+    return holderRecord({
+        brand: familyBrand(family),
+        materialNumber: published(row[MATERIAL_NUMBER], what, 'material number'),
+        // The designation REGO-FIX titles the part with — `BT 30 / PG 25 x 080 H`.
+        // It is the catalog number and not a description: the vendor publishes no
+        // prose about a holder anywhere, so `description` is `''`.
+        catalogNumber: published(row[CATALOG_NUMBER], what, 'catalog number'),
+        description: '',
+        unit,
+        taper: holdingFact(family, 'taper', family.taper),
+        contact: contactMode(published(row[CONTACT_COLUMN], what, 'contact mode'), what),
+        clamping: clampingMode(holdingFact(family, 'clamping', family.clamping), what),
+        style: holdingFact(family, 'style', family.style),
+        colletSeries: row[COLLET_SERIES_COLUMN] || null,
+        gaugeLength: published(dim(row, 'L1', unit), what, 'L1 gage length'),
+        bodyDiameter: dim(row, 'D2', unit),
+        cadModelUrl: row[CAD_COLUMN] || null,
+        cadDxfUrl: null,
+    });
+}
+/** One PG or PGST collet row -> one {@link ColletRecord}. */
+function collet(row, family, options = {}) {
+    const warn = options.warn ?? consoleWarn;
+    const what = subject(row);
+    const unit = unitSystem(published(row[UNIT_COLUMN], what, 'unit system'), what);
+    // An inch collet carries both columns, because `scrape.colletRow` projects the
+    // exact fraction from the designation into millimetres. Cross-checking them is
+    // therefore checking this package's own arithmetic as much as the vendor's,
+    // which is worth doing once per row and costs nothing when they agree.
+    for (const label of ['D1', 'CCCN', 'CCCX'])
+        checkUnitAgreement(row, label, what, warn);
+    return colletRecord({
+        brand: familyBrand(family),
+        materialNumber: published(row[MATERIAL_NUMBER], what, 'material number'),
+        catalogNumber: published(row[CATALOG_NUMBER], what, 'catalog number'),
+        description: '',
+        unit,
+        // Written exactly as the vendor designates it, so a `PGST15` collet matches
+        // no `PG25` holder. `families/regofix.ts` records why that is the
+        // conservative direction and how to resolve it — by asking REGO-FIX, not by
+        // widening the string.
+        series: published(row[COLLET_DESIGNATION_COLUMN], what, 'collet series'),
+        style: holdingFact(family, 'style', family.style),
+        nominal: dim(row, 'D1', unit),
+        // A powRgrip collet clamps one size to h6 rather than closing over a range,
+        // so its capacity is its nominal diameter at both ends — the vendor's own
+        // `Clamping range or tolerance` row. A zero-width range is still a range,
+        // and `holding.checkCollet` refuses only an inverted one.
+        clampMin: published(dim(row, 'CCCN', unit), what, 'CCCN clamping minimum'),
+        clampMax: published(dim(row, 'CCCX', unit), what, 'CCCX clamping maximum'),
+    });
+}
+/** The toolholding half of the adapter contract `registry` looks up by brand. */
+export const HOLDING_MAPPERS = { holder, collet };

package/dist/vendors/regofix/index.d.ts

@@ -5,4 +5,5 @@
  * roster and the geometry are two different fetches. See
  * `docs/REGOFIX_PRODUCTFINDER_API.md`.
  */
+export * from './holding.js';
 export * from './scrape.js';

package/dist/vendors/regofix/index.js

@@ -5,4 +5,5 @@
  * roster and the geometry are two different fetches. See
  * `docs/REGOFIX_PRODUCTFINDER_API.md`.
  */
+export * from './holding.js';
 export * from './scrape.js';

package/dist/vendors/regofix/scrape.js

@@ -53,7 +53,7 @@
  *    (`1715.08215` and `1725.08215`). This is why the nominal size is parsed
  *    from the vendor's own designation and `o_mm` is only ever a cross-check.
  */
-import { CAD_COLUMN, COLLET_SERIES_COLUMN, CONTACT_COLUMN, DIN_PREFIX, GAGE_COLUMNS, } from '../../conventions.js';
+import { CAD_COLUMN, COLLET_DESIGNATION_COLUMN, COLLET_SERIES_COLUMN, CONTACT_COLUMN, DIN_PREFIX, GAGE_COLUMNS, } from '../../conventions.js';
 import { VendorResponseError } from '../../errors.js';
 import { statusOf } from '../../fetch.js';
 import { convertLength, fractionValue } from '../../measure.js';
@@ -417,7 +417,7 @@ export function colletRow(source, warn = consoleWarn) {
     const row = {
         'Material Number': sku,
         'ISO Catalog Number': title,
-        'Collet Series': (parsed['series'] ?? '').replaceAll(' ', ''),
+        [COLLET_DESIGNATION_COLUMN]: (parsed['series'] ?? '').replaceAll(' ', ''),
         unit,
         o_mm: plain(one(source, 'o_mm')),
         Square_mm: '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolpath/tool-scraper",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Scrape cutting-tool geometry from vendor catalogs into records and CSVs",
   "license": "MIT",
   "engines": {