@toolpath/tool-scraper 2.1.0 → 2.3.0

package/dist/holding.js

@@ -0,0 +1,360 @@
+/**
+ * What a holder and a collet become, and the two gates that refuse one.
+ *
+ * `records.ts` is the cutting-tool half of this package's output. This is the
+ * toolholding half, and it is a separate module rather than a third `ToolKind`
+ * because the three vocabularies genuinely do not overlap: a tool answers `DC`,
+ * a flute count and a workpiece material group; a holder answers a taper, a
+ * clamping mode and a gage length; a collet answers a series and a capacity
+ * band. `families/index.ts` states the same rule for the config tables —
+ *
+ * > Separate tables rather than a `kind` on one, because a holder and a collet
+ * > are not variants of a thing.
+ *
+ * — and the records follow it. What they *do* share is identity, the unit rule
+ * and the guid space, which is why both live here and not in two more files:
+ * `identity.recordGuid` mints a holder and a tool into one namespace per brand,
+ * so a consumer building a catalog from both can refuse a collision between
+ * them.
+ *
+ * ## Two copies of a dimension, and only where something compares them
+ *
+ * A fit-bearing dimension is kept twice — once in the family's native unit for
+ * display, once in canonical millimetres for arithmetic. The reason is that fit
+ * and filtering are different questions: a 3/8 in shank is 9.525 mm and
+ * genuinely seats in a metric 9-10 mm collet, so a fit comparison must convert,
+ * while a range *filter* must still refuse to, because "between 9 and 10 mm" is
+ * not a question an inch tool answers.
+ *
+ * Only {@link HolderRecord.bore}, {@link HolderRecord.gaugeLength},
+ * {@link ColletRecord.clampMin} and {@link ColletRecord.clampMax} get a twin.
+ * Everything else — usable length, body diameter, adjustment range — is
+ * displayed and never compared, and a second copy of a number nothing reads is
+ * a field to keep in sync for free.
+ *
+ * **The twin is derived here rather than read from the other unit column**, and
+ * that is a deliberate departure from the reference implementation, which read
+ * `D1_mm` directly whatever the family's unit was. Vendors publish pairs that
+ * disagree — see {@link checkUnitAgreement} — and a record whose `bore` and
+ * `boreMm` came from two contradicting cells is one record stating two sizes.
+ * Deriving makes `boreMm` exactly `bore` in millimetres by construction, so the
+ * pair cannot drift and a test can pin one to the other.
+ *
+ * ## Which refusal a vendor's row earns
+ *
+ * The split is **blank versus wrong**, and it decides whether one bad part ends
+ * a family:
+ *
+ * - A cell the vendor left **blank** that a part cannot exist without — no gage
+ *   length, no bore on a bore-clamping holder, no capacity on a collet — is an
+ *   `errors.IncompletePartError`. `registry.toHolding` warns and drops the row,
+ *   the same call `registry.toRecords` makes for a cutting tool, and for the
+ *   same reason: MariTool leaves `Shank Size` blank on four HSK holders out of
+ *   527, and losing five families over four rows is not a trade worth making.
+ * - A value that is **present and unreadable**, or two present values that
+ *   **contradict** — a clamping mode this package has no word for, a holder
+ *   that names both a bore and a collet series, a collet whose nominal size
+ *   falls outside its own published capacity — is an `errors.VendorResponseError`
+ *   and stops the family. Those say the vendor's vocabulary or this package's
+ *   reading of it has moved, and skipping past one quietly is how a scraper
+ *   starts publishing a catalog nobody checked.
+ */
+import { dimensionalColumn, UNIT_SUFFIX } from './conventions.js';
+import { IncompletePartError, ScraperConfigError, VendorResponseError } from './errors.js';
+import { BRANDS, productLink, recordGuid } from './identity.js';
+import { convertLength, fractionValue } from './measure.js';
+import { consoleWarn } from './scrape.js';
+/** Every {@link ClampingMode}, for a message that can list what it knows. */
+export const CLAMPING_MODES = ['bore', 'collet', 'shrink', 'hydraulic'];
+/**
+ * The clamping modes that grip a shank directly, and therefore publish a bore.
+ *
+ * One rule over three values rather than three rules: the gate in
+ * {@link checkHolder} asks whether a holder takes a shank or a collet, and
+ * every mode but `collet` takes a shank.
+ */
+export const BORE_CLAMPINGS = ['bore', 'shrink', 'hydraulic'];
+/** Every {@link ContactMode}, for the same reason {@link CLAMPING_MODES} is a list. */
+export const CONTACT_MODES = ['taper', 'face'];
+/**
+ * A per-family constant a toolholding mapper cannot proceed without.
+ *
+ * `family.fact`'s counterpart for a family with no `id` and no `ToolKind`. The
+ * two are separate rather than one widened function because the subject of the
+ * message differs: a cutting-tool family is named by its vendor-local id and a
+ * toolholding family by the catalog name a human reads.
+ *
+ * Refusing rather than defaulting, for the reason `family.fact` states: every
+ * default is a claim the family never made, and a missing `taper` becoming
+ * `''` ships a holder that fits no spindle and raises nothing.
+ */
+export function holdingFact(family, key, value) {
+    if (value === undefined) {
+        throw new ScraperConfigError(family.catalogName, `a ${family.kind} family must state ${key} as a fact`);
+    }
+    return value;
+}
+/**
+ * A value the vendor left blank on one part, refused as an incomplete part.
+ *
+ * The toolholding counterpart of `columns.required`, and it throws the same
+ * type for the same reason: this is the one refusal `registry.toHolding` skips
+ * past, because a single part with an unpublished cell must not end a family's
+ * conversion. See `errors.IncompletePartError` for why the others must not be
+ * skipped alike.
+ */
+export function published(value, what, label) {
+    if (value === null || value === undefined || value === '') {
+        throw new IncompletePartError(what, `publishes no ${label}`);
+    }
+    return value;
+}
+/**
+ * Round a converted value to six decimals.
+ *
+ * **This removes error rather than adding precision.** 9.525 mm is exactly
+ * 0.375 in, but `9.525 / 25.4` is `0.37500000000000006` in binary floating
+ * point, and that is the number that would land in a catalog and in a
+ * prefix-matched size string. Six places is far coarser than the ~1e-14 the
+ * error reaches at these magnitudes and far finer than the four decimals a
+ * vendor prints, so nothing anybody stated is lost.
+ */
+function round6(value) {
+    return Math.round(value * 1e6) / 1e6;
+}
+/**
+ * `value`, stated in `from`, as a number in `to` — a no-op when they agree.
+ *
+ * The one conversion every toolholding mapper makes, so that the rounding above
+ * is applied in one place rather than wherever somebody remembers to.
+ */
+export function asUnit(value, from, to) {
+    return from === to ? value : round6(convertLength(value, from, to));
+}
+export function millimeters(value, unit) {
+    return value === null ? null : asUnit(value, unit, 'millimeters');
+}
+/**
+ * One dimension in `unit`, converted from the other system where that is all
+ * the vendor published.
+ *
+ * **The fallback is load-bearing, not defensive.** Kennametal's `D1` is a unit
+ * pair on the BT30 hydraulic chucks and metric-only on the HSK63A HP line — an
+ * *inch* family with no `D1_in` column at all. A bare suffixed read is correct
+ * on the first and yields null on the second, producing a holder with no bore:
+ * it matches no tool, raises nothing, and looks like an empty result rather
+ * than a bug.
+ *
+ * The grammar is `measure.fractionValue`'s, which is the package's one reader
+ * for a machinist's number and refuses a range rather than summing it.
+ */
+export function dim(row, label, unit) {
+    const native = fractionValue(row[dimensionalColumn(label, unit)] ?? '');
+    if (native !== null)
+        return native;
+    const other = unit === 'millimeters' ? 'inches' : 'millimeters';
+    const fallback = fractionValue(row[dimensionalColumn(label, other)] ?? '');
+    if (fallback === null)
+        return null;
+    return round6(convertLength(fallback, other, unit));
+}
+/** Half a unit in the last decimal place a cell actually printed. */
+function halfUlp(raw) {
+    const fraction = raw.includes('.') ? raw.slice(raw.indexOf('.') + 1) : '';
+    return 0.5 * 10 ** -fraction.length;
+}
+/**
+ * Report where a vendor's own millimetre and inch cells disagree.
+ *
+ * **Vendors really do publish contradictory pairs.** Kennametal's `16ERSS0312`
+ * states `D1`'s metric cell as `0.3125` — the inch value sitting in the metric
+ * column, a factor of 25.4 out — and `25ER130M` publishes `CCCN` as both
+ * 12.0 mm and 0.437 in, which is 11.1 mm. Both are in the source HTML.
+ *
+ * **This reports; it does not gate.** Two disagreeing cells cannot say which
+ * one is wrong, so refusing the family would trade a knowable warning for an
+ * unusable pipeline, and correcting a cell here would make this package a place
+ * tool data is authored by hand. What protects the output instead is that
+ * {@link dim} reads the family's *native* column and never the other one, plus
+ * {@link checkCollet}'s native-unit test that a nominal size falls inside its
+ * own published capacity. Every disagreement found so far sits in the column
+ * {@link dim} ignores; escalate this to a gate if one ever lands in a native
+ * column.
+ *
+ * **The tolerance is the vendor's own rounding, not a percentage.** A relative
+ * tolerance cannot tell rounding from error at small sizes: `16ER010M`
+ * publishes 0.5 mm as `0.02` in, correct to the two decimals it states and
+ * 1.6 % off as a ratio. Half a unit in each column's last printed place is
+ * exactly the slack the printed precision allows, and it is nowhere near the
+ * 7.6 mm a value in the wrong column produces.
+ *
+ * Returns whether it warned, so a caller can count.
+ */
+export function checkUnitAgreement(row, label, what, warn = consoleWarn) {
+    const rawMm = (row[label + UNIT_SUFFIX.millimeters] ?? '').trim();
+    const rawIn = (row[label + UNIT_SUFFIX.inches] ?? '').trim();
+    const mm = fractionValue(rawMm);
+    const inch = fractionValue(rawIn);
+    if (mm === null || inch === null)
+        return false;
+    const slack = halfUlp(rawIn) * convertLength(1, 'inches', 'millimeters') + halfUlp(rawMm);
+    const asMm = convertLength(inch, 'inches', 'millimeters');
+    if (Math.abs(mm - asMm) <= slack)
+        return false;
+    warn(`  WARNING: ${what}: ${label} disagrees across unit systems — ` +
+        `${mm} mm vs ${inch} in (= ${asMm} mm); the native column is used`);
+    return true;
+}
+/**
+ * One cell as a {@link ContactMode}, refusing a word this package cannot read.
+ *
+ * A `VendorResponseError` and not an incomplete part: a *blank* contact is the
+ * caller's `published` call, and a contact the vendor states in a word nobody
+ * has mapped is the vocabulary having moved.
+ */
+export function contactMode(value, what) {
+    if (CONTACT_MODES.includes(value))
+        return value;
+    throw new VendorResponseError(what, `contact is ${JSON.stringify(value)} — it must be one of ` + `${CONTACT_MODES.join(', ')}`);
+}
+/** One cell as a {@link ClampingMode}, on the same terms as {@link contactMode}. */
+export function clampingMode(value, what) {
+    if (CLAMPING_MODES.includes(value))
+        return value;
+    throw new VendorResponseError(what, `clamping is ${JSON.stringify(value)} — it must be one of ` + `${CLAMPING_MODES.join(', ')}`);
+}
+/**
+ * One cell as a {@link UnitSystem}, on the same terms as {@link contactMode}.
+ *
+ * For the vendor that states the unit per row rather than per family: REGO-FIX
+ * publishes `PG 25 Ø 6.0 mm` and `PG 25 Ø 1/4"` in one product group, so its
+ * collet scrape writes the system it read off each designation into a column.
+ */
+export function unitSystem(value, what) {
+    if (Object.hasOwn(UNIT_SUFFIX, value))
+        return value;
+    throw new VendorResponseError(what, `unit is ${JSON.stringify(value)} — it must be one of ` +
+        `${Object.keys(UNIT_SUFFIX).sort().join(', ')}`);
+}
+/** How a record names itself in a warning or a refusal. */
+function subject(fields) {
+    return `${fields.catalogNumber} (${fields.materialNumber})`;
+}
+/**
+ * Vendor HTML is a system boundary, so this validates rather than guarding
+ * against a caller mistake.
+ *
+ * The `clamping` discriminant and the fields it implies must agree. **That is
+ * what turns Kennametal's missing-bore case into a failed conversion instead of
+ * a holder that quietly fits nothing** — a bore-clamping holder with no bore is
+ * the exact shape of that bug, and it raises nothing anywhere else.
+ */
+export function checkHolder(record) {
+    const what = subject(record);
+    const bore = BORE_CLAMPINGS.includes(record.clamping);
+    if (bore) {
+        if (record.bore === null) {
+            throw new IncompletePartError(what, `publishes no bore, and a ${record.clamping}-clamping holder grips a shank directly`);
+        }
+        if (record.colletSeries !== null) {
+            throw new VendorResponseError(what, `is ${record.clamping}-clamping and also names collet series ` +
+                `${JSON.stringify(record.colletSeries)} — a holder grips one way or the other`);
+        }
+    }
+    else {
+        if (record.colletSeries === null) {
+            throw new IncompletePartError(what, 'is collet-clamping and names no collet series');
+        }
+        if (record.bore !== null) {
+            throw new VendorResponseError(what, `is collet-clamping and also publishes a bore of ${record.bore} — ` +
+                `a holder grips one way or the other`);
+        }
+    }
+    // Optional is fine; *malformed* is refused. A consumer renders this as a
+    // download button, and a truncated or redirected link is the one failure that
+    // looks like a working feature until somebody clicks it. Widened from the
+    // reference implementation's `.stp`-only test because MariTool publishes both
+    // spellings.
+    const url = record.cadModelUrl;
+    if (url !== null && !/^https:\/\/.+\.ste?p$/i.test(url)) {
+        throw new VendorResponseError(what, `CAD model URL is not an https .stp or .step: ${JSON.stringify(url)}`);
+    }
+}
+/**
+ * The same boundary rule for a collet.
+ *
+ * A collet with no capacity would match every shank or none depending on which
+ * way a comparison read a null, which is why {@link ColletRecord.clampMin} and
+ * {@link ColletRecord.clampMax} are not nullable and the mapper refuses the row
+ * before it gets here.
+ */
+export function checkCollet(record) {
+    const what = subject(record);
+    // Equality is a sealed coolant-through collet clamping one exact size — real,
+    // and not a bug. Only an inverted range is impossible.
+    if (record.clampMin > record.clampMax) {
+        throw new VendorResponseError(what, `capacity is inverted: ${record.clampMin} > ${record.clampMax}`);
+    }
+    // In the native unit, which is the gate with teeth: these are the values a
+    // consumer compares, and the contradictory cells this catalog knows about all
+    // sit in the column `dim` ignores.
+    if (record.nominal !== null &&
+        (record.nominal < record.clampMin || record.nominal > record.clampMax)) {
+        throw new VendorResponseError(what, `nominal ${record.nominal} is outside its own capacity ` +
+            `${record.clampMin}-${record.clampMax}`);
+    }
+}
+/**
+ * Build a {@link HolderRecord}: mint its guid, derive its millimetre twins, and
+ * refuse the states that cannot be true.
+ *
+ * `guid`, `vendor` and `productLink` are not inputs at all — every adapter
+ * minting them would be three copies of `recordGuid(brand, materialNumber)` to
+ * drift, on the value that is the join key for every downstream consumer. The
+ * nullable dimensions stay **required on the type** so a consumer reading a
+ * record never handles `undefined`; only the construction is optional, which is
+ * the shape `records.toolRecord` already has.
+ *
+ * The result is frozen: a record is an interchange value, and a mapper that
+ * mutated one would be reaching back across the seam this type exists to draw.
+ */
+export function holderRecord(fields) {
+    const record = Object.freeze({
+        ...fields,
+        kind: 'holder',
+        guid: recordGuid(fields.brand, fields.materialNumber),
+        vendor: BRANDS[fields.brand].vendor,
+        productLink: productLink(fields.brand, fields.materialNumber),
+        colletSeries: fields.colletSeries ?? null,
+        bore: fields.bore ?? null,
+        boreMm: millimeters(fields.bore ?? null, fields.unit),
+        gaugeLengthMm: millimeters(fields.gaugeLength, fields.unit),
+        usableLength: fields.usableLength ?? null,
+        clampingLength: fields.clampingLength ?? null,
+        adjustmentRange: fields.adjustmentRange ?? null,
+        bodyDiameter: fields.bodyDiameter ?? null,
+        lockNutDiameter: fields.lockNutDiameter ?? null,
+        cadModelUrl: fields.cadModelUrl ?? null,
+        cadDxfUrl: fields.cadDxfUrl ?? null,
+    });
+    checkHolder(record);
+    return record;
+}
+/** Build a {@link ColletRecord}, on the same terms as {@link holderRecord}. */
+export function colletRecord(fields) {
+    const record = Object.freeze({
+        ...fields,
+        kind: 'collet',
+        guid: recordGuid(fields.brand, fields.materialNumber),
+        vendor: BRANDS[fields.brand].vendor,
+        productLink: productLink(fields.brand, fields.materialNumber),
+        nominal: fields.nominal ?? null,
+        clampMinMm: millimeters(fields.clampMin, fields.unit),
+        clampMaxMm: millimeters(fields.clampMax, fields.unit),
+        bodyDiameter: fields.bodyDiameter ?? null,
+        functionalLength: fields.functionalLength ?? null,
+        overallLength: fields.overallLength ?? null,
+    });
+    checkCollet(record);
+    return record;
+}

package/dist/index.d.ts

@@ -20,27 +20,37 @@
  * point, because a backend embedding this wants the data and a maintainer
  * running the CLI wants the file, and only one of those two needs `fs`.
  *
- * ## Cutting tools become records; toolholding is rows
- *
- * **`ToolRecord` is the uniform output for cutting tools, and only for those.**
- * `registry.toRecords` maps one cutting-tool family's scrape onto it, through
- * the adapter its brand binds. Holders and collets have no record type and no
- * mapper: REGO-FIX and MariTool ship toolholding and nothing else, so a scrape
- * of either ends at rows and a receipt, and a consumer that wants a holder
- * reads the CSV's own columns — the shared ones are named in `conventions`.
- *
- * That is a real gap rather than a design: `identity.recordGuid` already exists
- * so that a holder and a tool can be minted into one guid space, and nothing
- * mints a holder yet. Until something does, `toRecords` is the tool half and
- * the receipt is the whole of the toolholding half.
+ * ## Three record types, one guid space
+ *
+ * `ToolRecord` is the uniform output for **cutting tools**, and `HolderRecord`
+ * and `ColletRecord` are the toolholding half — `registry.toRecords` and
+ * `registry.toHolding` map one family's scrape onto them through the adapter
+ * its brand binds. All three are minted by `identity.recordGuid` in one
+ * namespace per brand, which is what lets a consumer build a catalog from
+ * holders and tools together and refuse a collision between them.
+ *
+ * They are three types rather than one because the vocabularies do not overlap:
+ * a tool answers `DC`, a flute count and a workpiece material group; a holder
+ * answers a taper, a clamping mode and a gage length; a collet answers a series
+ * and a capacity band. `holding.ts` states that at length, and `families/index.ts`
+ * already drew the same line for the config tables.
+ *
+ * **A vendor may publish holders, collets, both or neither, and none of it is
+ * required.** REGO-FIX ships toolholding and no cutting tools; MariTool ships
+ * holders and no collets; Harvey, EMUGE-FRANKEN and Destiny Tool ship neither.
+ * A brand with no mapper for a kind still scrapes, still writes a CSV and still
+ * checks a receipt — `registry.toHolding` is the only call that refuses, and it
+ * names the brand and what that brand does map.
  */
 export * from './columns.js';
 export * from './conventions.js';
 export * from './errors.js';
 export * from './family.js';
 export * from './fetch.js';
+export * from './holding.js';
 export * from './identity.js';
 export * from './measure.js';
+export * from './profiles.js';
 export * from './provenance.js';
 export * from './records.js';
 export * from './scrape.js';

package/dist/index.js

@@ -20,27 +20,37 @@
  * point, because a backend embedding this wants the data and a maintainer
  * running the CLI wants the file, and only one of those two needs `fs`.
  *
- * ## Cutting tools become records; toolholding is rows
- *
- * **`ToolRecord` is the uniform output for cutting tools, and only for those.**
- * `registry.toRecords` maps one cutting-tool family's scrape onto it, through
- * the adapter its brand binds. Holders and collets have no record type and no
- * mapper: REGO-FIX and MariTool ship toolholding and nothing else, so a scrape
- * of either ends at rows and a receipt, and a consumer that wants a holder
- * reads the CSV's own columns — the shared ones are named in `conventions`.
- *
- * That is a real gap rather than a design: `identity.recordGuid` already exists
- * so that a holder and a tool can be minted into one guid space, and nothing
- * mints a holder yet. Until something does, `toRecords` is the tool half and
- * the receipt is the whole of the toolholding half.
+ * ## Three record types, one guid space
+ *
+ * `ToolRecord` is the uniform output for **cutting tools**, and `HolderRecord`
+ * and `ColletRecord` are the toolholding half — `registry.toRecords` and
+ * `registry.toHolding` map one family's scrape onto them through the adapter
+ * its brand binds. All three are minted by `identity.recordGuid` in one
+ * namespace per brand, which is what lets a consumer build a catalog from
+ * holders and tools together and refuse a collision between them.
+ *
+ * They are three types rather than one because the vocabularies do not overlap:
+ * a tool answers `DC`, a flute count and a workpiece material group; a holder
+ * answers a taper, a clamping mode and a gage length; a collet answers a series
+ * and a capacity band. `holding.ts` states that at length, and `families/index.ts`
+ * already drew the same line for the config tables.
+ *
+ * **A vendor may publish holders, collets, both or neither, and none of it is
+ * required.** REGO-FIX ships toolholding and no cutting tools; MariTool ships
+ * holders and no collets; Harvey, EMUGE-FRANKEN and Destiny Tool ship neither.
+ * A brand with no mapper for a kind still scrapes, still writes a CSV and still
+ * checks a receipt — `registry.toHolding` is the only call that refuses, and it
+ * names the brand and what that brand does map.
  */
 export * from './columns.js';
 export * from './conventions.js';
 export * from './errors.js';
 export * from './family.js';
 export * from './fetch.js';
+export * from './holding.js';
 export * from './identity.js';
 export * from './measure.js';
+export * from './profiles.js';
 export * from './provenance.js';
 export * from './records.js';
 export * from './scrape.js';

package/dist/measure.d.ts

@@ -41,16 +41,22 @@
  * writes `1 1/2` and admits no hyphen at all. What it hands here is
  * {@link Measured}, which is the part they have in common.
  *
- * **`MM_PER_INCH` lives here and not in a vendor.** It was declared and
- * exported twice — `vendors/harvey/value.ts` and `vendors/regofix/scrape.ts`
- * — so `@toolpath/tool-scraper/vendors/harvey` and `.../vendors/regofix` each
- * published their own copy of 25.4. That is exactly what `conventions.CAD_COLUMN`
- * was moved up for, and what `tests/vendor-boundary.test.ts` now refuses by name.
+ * **`MM_PER_INCH` and `convertLength` are `@toolpath/tool-support`'s**, and are
+ * re-exported here under the names this package has always published.
+ *
+ * They were declared and exported twice inside this package alone —
+ * `vendors/harvey/value.ts` and `vendors/regofix/scrape.ts` — so
+ * `@toolpath/tool-scraper/vendors/harvey` and `.../vendors/regofix` each
+ * published their own copy of 25.4. `tests/vendor-boundary.test.ts` refuses that
+ * by name and moving the constant up here fixed it *within* this package, while
+ * a third copy went on standing in the application downstream. The domain
+ * package is where a constant every consumer shares can only be declared once,
+ * and `@toolpath/tool-support`'s own boundary test now holds the whole tree to
+ * one `25.4`.
  */
-import type { UnitSystem } from './conventions.js';
+import { convertLength, MM_PER_INCH, type UnitSystem } from '@toolpath/tool-support';
 import { type Warn } from './scrape.js';
-/** Exact by definition: the inch has been 25.4 mm since 1959. */
-export declare const MM_PER_INCH = 25.4;
+export { convertLength, MM_PER_INCH };
 /**
  * `.250` -> 0.25, `3/4` -> 0.75, `1-1/2` -> 1.5, `2` -> 2.
  *
@@ -63,8 +69,6 @@ export declare const MM_PER_INCH = 25.4;
  * that guessed would be the mistake `conventions.UNIT_SUFFIX` exists to prevent.
  */
 export declare function fractionValue(token: string): number | null;
-/** `value`, converted from `from` to `to`. A no-op when they agree. */
-export declare function convertLength(value: number, from: UnitSystem, to: UnitSystem): number;
 /**
  * What a value states about itself: a length system, or degrees.
  *

package/dist/measure.js

@@ -41,15 +41,22 @@
  * writes `1 1/2` and admits no hyphen at all. What it hands here is
  * {@link Measured}, which is the part they have in common.
  *
- * **`MM_PER_INCH` lives here and not in a vendor.** It was declared and
- * exported twice — `vendors/harvey/value.ts` and `vendors/regofix/scrape.ts`
- * — so `@toolpath/tool-scraper/vendors/harvey` and `.../vendors/regofix` each
- * published their own copy of 25.4. That is exactly what `conventions.CAD_COLUMN`
- * was moved up for, and what `tests/vendor-boundary.test.ts` now refuses by name.
+ * **`MM_PER_INCH` and `convertLength` are `@toolpath/tool-support`'s**, and are
+ * re-exported here under the names this package has always published.
+ *
+ * They were declared and exported twice inside this package alone —
+ * `vendors/harvey/value.ts` and `vendors/regofix/scrape.ts` — so
+ * `@toolpath/tool-scraper/vendors/harvey` and `.../vendors/regofix` each
+ * published their own copy of 25.4. `tests/vendor-boundary.test.ts` refuses that
+ * by name and moving the constant up here fixed it *within* this package, while
+ * a third copy went on standing in the application downstream. The domain
+ * package is where a constant every consumer shares can only be declared once,
+ * and `@toolpath/tool-support`'s own boundary test now holds the whole tree to
+ * one `25.4`.
  */
+import { convertLength, MM_PER_INCH } from '@toolpath/tool-support';
 import { consoleWarn } from './scrape.js';
-/** Exact by definition: the inch has been 25.4 mm since 1959. */
-export const MM_PER_INCH = 25.4;
+export { convertLength, MM_PER_INCH };
 /**
  * A decimal, a simple fraction or a mixed number — and nothing else.
  *
@@ -80,12 +87,6 @@ export function fractionValue(token) {
     const value = (whole === undefined ? 0 : Number(whole)) + part;
     return Number.isFinite(value) ? value : null;
 }
-/** `value`, converted from `from` to `to`. A no-op when they agree. */
-export function convertLength(value, from, to) {
-    if (from === to)
-        return value;
-    return to === 'inches' ? value / MM_PER_INCH : value * MM_PER_INCH;
-}
 /**
  * A read cell as a length in `unit`, or null where it publishes none.
  *

package/dist/node/cad-mirror.d.ts

@@ -27,7 +27,24 @@
  * later, optional step.
  */
 import type { Fetcher } from '../fetch.js';
+import type { BrandName } from '../identity.js';
 import { type ScrapedRow, type Warn } from '../scrape.js';
+/**
+ * What one part's mirrored STEP model is called.
+ *
+ * REGO-FIX's catalog number is the vendor's own title — `BT 30 / PG 25 x 075`
+ * — and a separator in it was being honoured as one: `downloadStep` creates
+ * the parent directory, so the file landed in a `BT 30 ` subdirectory instead
+ * of flat in `outDir`, against what this module promises. The number stays
+ * readable, which is the whole reason the file is named for it.
+ *
+ * **Exported because two things now resolve it**, and two answers to "what is
+ * this part's file called" is one too many — the same argument
+ * {@link cadCoverage} makes for counting the column here. `node/holder-import.ts`
+ * reads back what this writes, and a mirror that flattened a separator while a
+ * reader did not would report every REGO-FIX holder as unmirrored.
+ */
+export declare function stepFileName(catalogNumber: string): string;
 /** One STEP file onto disk. Returns the bytes written. */
 export declare function downloadStep(fetcher: Fetcher, url: string, dest: string): Promise<number>;
 /** One mirrored file. */
@@ -35,6 +52,35 @@ export interface MirroredStep {
     catalogNumber: string;
     bytes: number;
 }
+/** How much of one family the vendor publishes a downloadable model for. */
+export interface CadCoverage {
+    /** Rows in the CSV. */
+    rows: number;
+    /** Rows carrying a {@link CAD_COLUMN} a mirror could download. */
+    step: number;
+    /** Rows carrying a {@link CAD_DXF_COLUMN}. */
+    dxf: number;
+}
+/**
+ * What a mirror of these rows would and would not get, without asking for any
+ * of it.
+ *
+ * **This is the number that bounds anything built on measured geometry**, and
+ * it is worth knowing before the download rather than after: two of the three
+ * toolholding vendors publish a STEP model for every part, and MariTool — which
+ * is 527 of the 601 holder rows — publishes one for about two thirds. A
+ * pipeline scoped against 601 and run against 431 is a surprise at the end.
+ *
+ * Counted here rather than in the CLI because it is the same column read the
+ * same way {@link mirrorFamilySteps} reads it, and two answers to "does this row
+ * have a model" is one too many. Pure, and it makes no requests.
+ *
+ * **The DXF is counted and is not a fallback.** `conventions.CAD_DXF_COLUMN`
+ * says why the two are different columns: a DXF is a drawing whose datum,
+ * projection and layer semantics are the vendor's business, and deriving a
+ * profile from one is a separate project rather than a way to cover the gap.
+ */
+export declare function cadCoverage(rows: readonly ScrapedRow[]): CadCoverage;
 /**
  * Every STEP model a holder scrape names, into `outDir`, one file per row.
  *
@@ -42,6 +88,16 @@ export interface MirroredStep {
  * filename is what a human reads and `BT30ER16060M` says what the part is
  * where `1258023` does not.
  *
+ * **`brand` is what says which column that number is in, and it is an argument
+ * rather than a guess.** This read `row['ISO Catalog Number']` until 2026-09-02,
+ * which is Kennametal's pair and REGO-FIX's adopted copy of it. MariTool
+ * publishes one number per part, under `Material Number`, and no catalog
+ * designation at all — `conventions.IDENTITY_DEVIATIONS` records why — so every
+ * one of its 357 published models was skipped with a warning saying the row had
+ * no catalog number to name it. `conventions.catalogColumn` is the lookup, and
+ * it is a lookup rather than a fallback down a list of candidate columns for the
+ * reason stated there.
+ *
  * **`outDir` is a required argument and never inferred.** These files are a
  * local working copy, they are gitignored, and a default that pointed into a
  * tracked directory would be the one mistake that silently commits ~3 MB of
@@ -51,5 +107,6 @@ export interface MirroredStep {
  * `lightweightStepUrl`'s documented null case arriving here — and a skipped
  * row spends no delay, because the count that matters is downloads and a
  * family that is mostly blank should not sleep its way through the gaps.
+ * {@link cadCoverage} is how many of them there will be, before any of it runs.
  */
-export declare function mirrorFamilySteps(fetcher: Fetcher, rows: readonly ScrapedRow[], outDir: string, delayMs?: number, warn?: Warn): Promise<MirroredStep[]>;
+export declare function mirrorFamilySteps(fetcher: Fetcher, rows: readonly ScrapedRow[], brand: BrandName, outDir: string, delayMs?: number, warn?: Warn): Promise<MirroredStep[]>;