@toolpath/tool-scraper 2.0.0 → 2.2.0

package/dist/columns.d.ts

@@ -20,9 +20,11 @@
  * - 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, naming the canonical
- *   field and quoting the cell, because a tool with no cutting diameter is not
- *   a part;
+ * - 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

package/dist/columns.js

@@ -20,9 +20,11 @@
  * - 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, naming the canonical
- *   field and quoting the cell, because a tool with no cutting diameter is not
- *   a part;
+ * - 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
@@ -31,7 +33,7 @@
  * 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 { VendorResponseError } from './errors.js';
+import { IncompletePartError } from './errors.js';
 /**
  * The three readers, over one vendor's `read`.
  *
@@ -54,7 +56,11 @@ export function columnReaders(read) {
         const raw = cell(row, columns, canonical, unit);
         const value = raw === undefined ? null : read(raw, unit, what, options.warn);
         if (value === null) {
-            throw new VendorResponseError(what, `publishes no ${canonical} — its cell is ${JSON.stringify(raw ?? '')}`);
+            // `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;
     };

package/dist/conventions.d.ts

@@ -22,6 +22,7 @@
  * | `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        |
+ * | `Collet Series` names the series a collet is        | Kennametal, REGO-FIX      |
  * | `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    |
@@ -97,6 +98,24 @@ export declare const CAD_DXF_COLUMN = "CAD_DXF_URL";
  * `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`.
  *
@@ -116,6 +135,21 @@ export declare const CONTACT_COLUMN = "contact";
  * the same reason.
  */
 export declare const COLLET_SERIES_COLUMN = "CST";
+/**
+ * The CSV column naming the series a collet **is** — `ER16`, `PG25`, `PGST15`.
+ *
+ * The other half of {@link COLLET_SERIES_COLUMN}, and deliberately a second
+ * column rather than the same one: `CST` is the series a *holder takes* and
+ * this is the series a *collet belongs to*, so the join between a holder family
+ * and a collet family is a comparison of the two. One column carrying both
+ * would make that join a row's comparison with itself.
+ *
+ * Vendor-neutral and here rather than in either adapter for the reason
+ * {@link CAD_COLUMN} is: Kennametal's ER collet tables and REGO-FIX's PG collet
+ * index both write it, and neither owns it. Both close the vendor's own spacing
+ * before writing, exactly as they do for `CST` — two spellings join to nothing.
+ */
+export declare const COLLET_DESIGNATION_COLUMN = "Collet Series";
 /**
  * The CSV columns carrying a holder's gage length, one per unit system.
  *
@@ -188,6 +222,26 @@ export declare function dimensionalColumn(label: string, unit: string): string;
  * indistinguishable from a scrape that lost it.
  */
 export declare function identityColumns(brand: BrandName): readonly string[];
+/**
+ * The identity column a human reads one part by.
+ *
+ * The catalog designation where the vendor publishes one, and the sole
+ * identifier where it does not — the **last** of {@link identityColumns},
+ * because that is the order the pair is written in and a deviation lists the
+ * one column its vendor has.
+ *
+ * A lookup rather than a read of the row, for the reason {@link identityColumns}
+ * gives: a header that is missing `ISO Catalog Number` is indistinguishable
+ * from a scrape that lost it, so a caller that fell back column by column would
+ * name half a family's files after part numbers and never say why.
+ *
+ * It exists because `node/cad-mirror.ts` names a mirrored file after the part
+ * it holds, and hardcoded `'ISO Catalog Number'` to do it. That is Kennametal's
+ * pair; MariTool publishes one number per part under `Material Number` and no
+ * catalog designation at all, so every one of its 357 STEP models was skipped
+ * with a warning that the row had no catalog number to name it.
+ */
+export declare function catalogColumn(brand: BrandName): string;
 /**
  * Every identity column `brand` claims is really in the CSV header.
  *

package/dist/conventions.js

@@ -22,6 +22,7 @@
  * | `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        |
+ * | `Collet Series` names the series a collet is        | Kennametal, REGO-FIX      |
  * | `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    |
@@ -98,6 +99,24 @@ export const CAD_DXF_COLUMN = 'CAD_DXF_URL';
  * `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`.
  *
@@ -117,6 +136,21 @@ export const CONTACT_COLUMN = 'contact';
  * the same reason.
  */
 export const COLLET_SERIES_COLUMN = 'CST';
+/**
+ * The CSV column naming the series a collet **is** — `ER16`, `PG25`, `PGST15`.
+ *
+ * The other half of {@link COLLET_SERIES_COLUMN}, and deliberately a second
+ * column rather than the same one: `CST` is the series a *holder takes* and
+ * this is the series a *collet belongs to*, so the join between a holder family
+ * and a collet family is a comparison of the two. One column carrying both
+ * would make that join a row's comparison with itself.
+ *
+ * Vendor-neutral and here rather than in either adapter for the reason
+ * {@link CAD_COLUMN} is: Kennametal's ER collet tables and REGO-FIX's PG collet
+ * index both write it, and neither owns it. Both close the vendor's own spacing
+ * before writing, exactly as they do for `CST` — two spellings join to nothing.
+ */
+export const COLLET_DESIGNATION_COLUMN = 'Collet Series';
 /**
  * The CSV columns carrying a holder's gage length, one per unit system.
  *
@@ -218,6 +252,31 @@ export function dimensionalColumn(label, unit) {
 export function identityColumns(brand) {
     return IDENTITY_DEVIATIONS[brand] ?? IDENTITY_COLUMNS;
 }
+/**
+ * The identity column a human reads one part by.
+ *
+ * The catalog designation where the vendor publishes one, and the sole
+ * identifier where it does not — the **last** of {@link identityColumns},
+ * because that is the order the pair is written in and a deviation lists the
+ * one column its vendor has.
+ *
+ * A lookup rather than a read of the row, for the reason {@link identityColumns}
+ * gives: a header that is missing `ISO Catalog Number` is indistinguishable
+ * from a scrape that lost it, so a caller that fell back column by column would
+ * name half a family's files after part numbers and never say why.
+ *
+ * It exists because `node/cad-mirror.ts` names a mirrored file after the part
+ * it holds, and hardcoded `'ISO Catalog Number'` to do it. That is Kennametal's
+ * pair; MariTool publishes one number per part under `Material Number` and no
+ * catalog designation at all, so every one of its 357 STEP models was skipped
+ * with a warning that the row had no catalog number to name it.
+ */
+export function catalogColumn(brand) {
+    const columns = identityColumns(brand);
+    // Non-null: `IDENTITY_COLUMNS` has two entries and every deviation has at
+    // least one, which `tests/conventions.test.ts` holds the table to.
+    return columns[columns.length - 1];
+}
 /**
  * Every identity column `brand` claims is really in the CSV header.
  *

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 {
+}

package/dist/families/emuge.d.ts

@@ -8,7 +8,9 @@
  * coating and the coolant supply **per part**, in columns, and a scraped column
  * beats a family constant. Splitting by product line would turn four counted
  * row totals into thirty and buy nothing a `product line` column does not
- * already carry.
+ * already carry — and it is carried: `vendors/emuge/records.ts`'s
+ * `PRODUCT_LINE_COLUMNS` reads one per part onto `ToolRecord.productLine`, from
+ * a column every scrape already writes.
  *
  * So the only fact three of these four state is `unit`, and the fourth adds the
  * two a drill record cannot be built without.

package/dist/families/emuge.js

@@ -8,7 +8,9 @@
  * coating and the coolant supply **per part**, in columns, and a scraped column
  * beats a family constant. Splitting by product line would turn four counted
  * row totals into thirty and buy nothing a `product line` column does not
- * already carry.
+ * already carry — and it is carried: `vendors/emuge/records.ts`'s
+ * `PRODUCT_LINE_COLUMNS` reads one per part onto `ToolRecord.productLine`, from
+ * a column every scrape already writes.
  *
  * So the only fact three of these four state is `unit`, and the fourth adds the
  * two a drill record cannot be built without.
@@ -100,9 +102,11 @@ export const FAMILIES = {
         kind: 'drill',
         familyCode: 'FB01',
         // `SIG` is a mapped column and not a fact, which no other drill family in
-        // this package manages: EMUGE states a point angle on every part's detail
-        // record. Kennametal's two drill lines assume theirs or derive them from a
-        // point length, and both say so at length in `families/kennametal.ts`.
+        // this package manages: EMUGE states a point angle on the detail record of
+        // 2,669 of these 2,670 parts, and leaves the cell empty on the last, so the
+        // record may carry no `SIG` — see `vendors/emuge/records.ts`'s `angle`.
+        // Kennametal's two drill lines assume theirs or derive them from a point
+        // length, and both say so at length in `families/kennametal.ts`.
         columns: {
             DC: 'nominal diameter d₁',
             SFDM: 'Shank diameter d₂',

package/dist/family.d.ts

@@ -18,6 +18,7 @@
  */
 import type { UnitSystem } from './conventions.js';
 import type { BrandName } from './identity.js';
+import type { HoldingMapper, ToolholdingKind } from './holding.js';
 import type { Fact } from './provenance.js';
 import type { ColumnMap, ToolKind, ToolRecord } from './records.js';
 import type { MapperOptions, ScrapedRow } from './scrape.js';
@@ -121,8 +122,21 @@ export type BoundFamily = Omit<FamilyDefinition, 'columns'> & FamilyFacts & {
     /** The adapter that turns this family's rows into records. */
     readonly records: RecordMapper;
 };
-/** A toolholding family after its facts have been checked and projected. */
-export type BoundToolholding = ToolholdingDefinition & FamilyFacts;
+/**
+ * A toolholding family after its facts have been checked and projected.
+ *
+ * `kind` is projected by the registry from **which table declared the family**,
+ * rather than being a key on {@link ToolholdingDefinition}: the table is the
+ * fact, and a `kind` beside it would be a second copy free to disagree with it.
+ * `records` is the mapper that brand binds for that kind, and it is optional
+ * because a vendor's holders may be scraped long before anybody has read its
+ * columns — see `holding.HoldingMappers`.
+ */
+export type BoundToolholding = ToolholdingDefinition & FamilyFacts & {
+    readonly kind: ToolholdingKind;
+    /** The adapter that turns this family's rows into records, where there is one. */
+    readonly records?: HoldingMapper;
+};
 /**
  * A family's id: `<brand>:<vendor-local id>`.
  *