@classytic/primitives 0.26.0 → 0.26.2

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.26.2
+
+### Added — `stockKeyFor` (`/item-identity`): one stock-key precedence for every package
+
+The product-level stock key, with a single precedence:
+
+1. the variant's stamped `skuRef` — assigned once at birth, immutable
+2. a **sole** variant with no stamp → the product's `_id`, never the label
+   (legacy writers derived `variantSku || productId`, and for one variant that
+   key IS the `_id`)
+3. a **sibling** with no stamp → its label, which genuinely is its legacy key
+4. nothing addressable → the product's `_id`
+
+The caller declares only what it HAS — `{ kind: 'sole' | 'label' | 'variant' }`
+— so the sole-vs-sibling decision is internal and a caller cannot make it wrong.
+That choice previously lived at every call site across three packages, in two
+functions with different fallbacks; they disagreed on a sole, unstamped,
+labelled variant, and the read then looked up a key no quant is stored under.
+
+It lives here, below every domain, because `@spinekit/order` and
+`@spinekit/catalog` must not import a peer domain — the rule sitting one layer
+too high is exactly why each package re-derived it.
+
+## 0.26.1
+
+- `./testing/stock-key-seam` — new subpath; `scanStockKeySeam`, `assertStockKeySeam`, `takesStockKeyFromLabel`, `STOCK_KEY_SEAM_FIXTURES` for conformance-scanning packages that resolve stock keys
+
 ## [0.26.0] — 2026-08-27
 
 ### Added

package/dist/item-identity.d.mts

@@ -31,6 +31,50 @@ interface SkuFields {
 declare function stockKeyOf(item: SkuFields, fallback?: string | {
   toString(): string;
 }): StockKey | undefined;
+/** The minimal product shape {@link stockKeyFor} reads. */
+interface StockKeySource {
+  _id: string | {
+    toString(): string;
+  };
+  variants?: ReadonlyArray<SkuFields> | null;
+}
+/**
+ * WHAT THE CALLER HAS — never what the key should be.
+ *
+ * - `sole`    nothing selected (a simple product, or a whole-product read)
+ * - `label`   an operator-typed / scanned SKU label
+ * - `variant` one variant record in hand, from iterating `variants`
+ */
+type StockKeySelector = {
+  readonly kind: "sole";
+} | {
+  readonly kind: "label";
+  readonly sku: string;
+} | {
+  readonly kind: "variant";
+  readonly variant: SkuFields;
+};
+/**
+ * THE product-level stock key. One precedence, for every package.
+ *
+ *   1. the variant's STAMPED `skuRef` — assigned once at birth, immutable
+ *   2. a SOLE variant with no stamp -> the product's `_id`. Never the label:
+ *      legacy writers derived `variantSku || productId`, and for one variant
+ *      that key IS the `_id`
+ *   3. a SIBLING with no stamp -> its label, which genuinely IS its legacy key
+ *   4. nothing addressable -> the product's `_id`
+ *
+ * The caller declares only what it HAS; the sole-vs-sibling decision is
+ * internal, so a caller cannot make it wrong. That choice previously lived at
+ * every call site across three packages, in two functions with different
+ * fallbacks — they disagreed on a sole, unstamped, labelled variant, and the
+ * read then looked up a key no quant is stored under.
+ *
+ * Lives HERE, below every domain, because `@spinekit/order` and
+ * `@spinekit/catalog` must not import a peer domain — the rule being one layer
+ * too high is exactly why each re-derived it.
+ */
+declare function stockKeyFor(product: StockKeySource, selector: StockKeySelector): StockKey;
 /**
  * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
  * a reservation on `undefined` returns "out of stock" instead of failing.
@@ -58,4 +102,4 @@ declare function skuDisplay(item: SkuFields): SkuDisplay;
  */
 declare function looksLikeOpaqueId(value: string | undefined): boolean;
 //#endregion
-export { SkuDisplay, SkuFields, StockKey, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { SkuDisplay, SkuFields, StockKey, StockKeySelector, StockKeySource, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyFor, stockKeyOf };

package/dist/item-identity.mjs

@@ -14,6 +14,49 @@ function stockKeyOf(item, fallback) {
 	return nonEmpty(item.skuRef) ?? nonEmpty(item.sku) ?? (fallback !== void 0 ? String(fallback) : void 0);
 }
 /**
+* THE product-level stock key. One precedence, for every package.
+*
+*   1. the variant's STAMPED `skuRef` — assigned once at birth, immutable
+*   2. a SOLE variant with no stamp -> the product's `_id`. Never the label:
+*      legacy writers derived `variantSku || productId`, and for one variant
+*      that key IS the `_id`
+*   3. a SIBLING with no stamp -> its label, which genuinely IS its legacy key
+*   4. nothing addressable -> the product's `_id`
+*
+* The caller declares only what it HAS; the sole-vs-sibling decision is
+* internal, so a caller cannot make it wrong. That choice previously lived at
+* every call site across three packages, in two functions with different
+* fallbacks — they disagreed on a sole, unstamped, labelled variant, and the
+* read then looked up a key no quant is stored under.
+*
+* Lives HERE, below every domain, because `@spinekit/order` and
+* `@spinekit/catalog` must not import a peer domain — the rule being one layer
+* too high is exactly why each re-derived it.
+*/
+function stockKeyFor(product, selector) {
+	const productId = String(product._id);
+	const variants = product.variants ?? [];
+	const sole = variants.length <= 1;
+	switch (selector.kind) {
+		case "sole":
+			if (!sole) return productId;
+			return nonEmpty(variants[0]?.skuRef) ?? productId;
+		case "label": {
+			const matched = variants.find((v) => v.sku === selector.sku);
+			const stamp = nonEmpty(matched?.skuRef);
+			if (stamp !== void 0) return stamp;
+			if (sole) return productId;
+			return selector.sku;
+		}
+		case "variant": {
+			const stamp = nonEmpty(selector.variant.skuRef);
+			if (stamp !== void 0) return stamp;
+			if (sole) return productId;
+			return stockKeyOf(selector.variant, productId);
+		}
+	}
+}
+/**
 * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
 * a reservation on `undefined` returns "out of stock" instead of failing.
 */
@@ -47,4 +90,4 @@ function looksLikeOpaqueId(value) {
 	return typeof value === "string" && /^[0-9a-f]{24}$/i.test(value);
 }
 //#endregion
-export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyFor, stockKeyOf };

package/dist/testing/stock-key-seam.d.mts

@@ -0,0 +1,47 @@
+//#region src/testing/stock-key-seam.d.ts
+interface StockKeyViolation {
+  /** Path relative to the scanned root. */
+  file: string;
+  /** 1-indexed line number. */
+  line: number;
+  /** The offending source line, trimmed. */
+  text: string;
+}
+/**
+ * Does this line take a stock key from a label?
+ *
+ * The class is "assigns `skuRef` from an expression that reads `.sku` and never
+ * reads `.skuRef`". Matching `.sku` alone flags the CORRECT idiom
+ * (`line.skuRef ?? line.sku`), and a gate that cries wolf is a gate someone
+ * deletes — so the ref-read is what distinguishes a fallback from a label grab.
+ */
+declare function takesStockKeyFromLabel(line: string): boolean;
+/** @deprecated Kept for callers that want the raw predicate; prefer {@link takesStockKeyFromLabel}. */
+declare const STOCK_KEY_FROM_LABEL: {
+  test: typeof takesStockKeyFromLabel;
+};
+interface StockKeySeamScan {
+  /** How many source files were read — assert a floor, or the gate can pass on an empty tree. */
+  scanned: number;
+  violations: StockKeyViolation[];
+}
+/** Scan a package's `src` root. Pure: returns findings, throws nothing. */
+declare function scanStockKeySeam(srcRoot: string): StockKeySeamScan;
+/**
+ * Throwing form for a one-line test. `minFiles` is the scan-volume floor: a gate
+ * that quietly scanned nothing passes forever, so state what "ran" means.
+ */
+declare function assertStockKeySeam(srcRoot: string, opts: {
+  minFiles: number;
+}): void;
+/**
+ * The fixtures the matcher must and must not fire on — exported so every
+ * adopting package falsifies the DETECTOR, not just its own current cleanliness.
+ * Both live defects are here verbatim.
+ */
+declare const STOCK_KEY_SEAM_FIXTURES: {
+  readonly mustMatch: readonly ["        skuRef: (snapshot.sku as string | undefined) ?? '',", "        skuRef: snap?.sku ?? '',", "      const skuRef = line.snapshot?.sku ?? line.offerId;", "        skuRef: (line.snapshot?.sku ?? line.offerId) as string,"];
+  readonly mustNotMatch: readonly ["        skuRef: stockKeyOf(snapshot) ?? '',", "        skuRef: line.skuRef,", "        sku: (snapshot.sku as string | undefined) ?? '',", "      const label = variant.sku ?? variant.skuRef;", "      const skuRef = line.skuRef ?? line.sku;", "        skuRef: item.skuRef ?? item.sku,"];
+};
+//#endregion
+export { STOCK_KEY_FROM_LABEL, STOCK_KEY_SEAM_FIXTURES, StockKeySeamScan, StockKeyViolation, assertStockKeySeam, scanStockKeySeam, takesStockKeyFromLabel };

package/dist/testing/stock-key-seam.mjs

@@ -0,0 +1,109 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+//#region src/testing/stock-key-seam.ts
+/**
+* Conformance scan: a STOCK KEY is never taken from a merchandising label.
+*
+* `skuRef: snapshot.sku` type-checks (both are `string`), reads plausibly, and
+* ships. Downstream it decrements a quant nothing is stocked under — the row
+* goes NEGATIVE while the real units sit under the stamped ref, and nothing
+* throws because a move carrying a reservation may go negative. The rule and
+* `stockKeyOf` already existed when that shipped; what was missing was a gate.
+*
+* Every package that resolves a stock key runs this over its own `src`, the way
+* `@classytic/arc/testing`'s store contracts are run by their implementors. The
+* matcher lives HERE so a fix to it reaches every consumer at once — a regex
+* copied per package is the same drift one layer up.
+*
+* Node-only (`node:fs`), so it is a `/testing` subpath and never reachable from
+* the isomorphic value-object entries.
+*/
+/** `skuRef` being assigned — property (`skuRef:`) or binding (`const skuRef =`). Both are the same defect. */
+const ASSIGNS_STOCK_KEY = /\bskuRef\s*[:=]\s*([^,;{}\n]*)/;
+/** The right-hand side reads a `.sku` label. `(?!Ref)` so `.skuRef` is not a `.sku` hit. */
+const READS_LABEL = /\.sku\b(?!Ref)/;
+/** The right-hand side already reads the stamped ref, i.e. it IS the `skuRef ?? sku` fallback. */
+const READS_REF = /\.skuRef\b/;
+/**
+* Does this line take a stock key from a label?
+*
+* The class is "assigns `skuRef` from an expression that reads `.sku` and never
+* reads `.skuRef`". Matching `.sku` alone flags the CORRECT idiom
+* (`line.skuRef ?? line.sku`), and a gate that cries wolf is a gate someone
+* deletes — so the ref-read is what distinguishes a fallback from a label grab.
+*/
+function takesStockKeyFromLabel(line) {
+	const rhs = ASSIGNS_STOCK_KEY.exec(line)?.[1];
+	if (rhs === void 0) return false;
+	return READS_LABEL.test(rhs) && !READS_REF.test(rhs);
+}
+/** @deprecated Kept for callers that want the raw predicate; prefer {@link takesStockKeyFromLabel}. */
+const STOCK_KEY_FROM_LABEL = { test: takesStockKeyFromLabel };
+/** Lines that are prose, not code. */
+const isComment = (trimmed) => trimmed.startsWith("*") || trimmed.startsWith("//") || trimmed.startsWith("/*");
+function tsFilesIn(dir, acc = []) {
+	for (const entry of readdirSync(dir)) {
+		if (entry === "node_modules" || entry === "dist") continue;
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory()) tsFilesIn(full, acc);
+		else if (entry.endsWith(".ts") && !entry.endsWith(".d.ts")) acc.push(full);
+	}
+	return acc;
+}
+/** Scan a package's `src` root. Pure: returns findings, throws nothing. */
+function scanStockKeySeam(srcRoot) {
+	const files = tsFilesIn(srcRoot);
+	const violations = [];
+	for (const file of files) {
+		const lines = readFileSync(file, "utf8").split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const raw = lines[i] ?? "";
+			const trimmed = raw.trim();
+			if (isComment(trimmed)) continue;
+			if (takesStockKeyFromLabel(raw)) violations.push({
+				file: relative(srcRoot, file),
+				line: i + 1,
+				text: trimmed.slice(0, 120)
+			});
+		}
+	}
+	return {
+		scanned: files.length,
+		violations
+	};
+}
+/**
+* Throwing form for a one-line test. `minFiles` is the scan-volume floor: a gate
+* that quietly scanned nothing passes forever, so state what "ran" means.
+*/
+function assertStockKeySeam(srcRoot, opts) {
+	const { scanned, violations } = scanStockKeySeam(srcRoot);
+	if (scanned < opts.minFiles) throw new Error(`stock-key seam REFUSING to pass: scanned only ${scanned} file(s) under ${srcRoot}, expected >= ${opts.minFiles}`);
+	if (violations.length > 0) {
+		const list = violations.map((v) => `  ${v.file}:${v.line}  ${v.text}`).join("\n");
+		throw new Error(`A stock key must come from stockKeyOf() (skuRef ?? sku), never from the .sku label:\n${list}`);
+	}
+}
+/**
+* The fixtures the matcher must and must not fire on — exported so every
+* adopting package falsifies the DETECTOR, not just its own current cleanliness.
+* Both live defects are here verbatim.
+*/
+const STOCK_KEY_SEAM_FIXTURES = {
+	mustMatch: [
+		"        skuRef: (snapshot.sku as string | undefined) ?? '',",
+		"        skuRef: snap?.sku ?? '',",
+		"      const skuRef = line.snapshot?.sku ?? line.offerId;",
+		"        skuRef: (line.snapshot?.sku ?? line.offerId) as string,"
+	],
+	mustNotMatch: [
+		"        skuRef: stockKeyOf(snapshot) ?? '',",
+		"        skuRef: line.skuRef,",
+		"        sku: (snapshot.sku as string | undefined) ?? '',",
+		"      const label = variant.sku ?? variant.skuRef;",
+		"      const skuRef = line.skuRef ?? line.sku;",
+		"        skuRef: item.skuRef ?? item.sku,"
+	]
+};
+//#endregion
+export { STOCK_KEY_FROM_LABEL, STOCK_KEY_SEAM_FIXTURES, assertStockKeySeam, scanStockKeySeam, takesStockKeyFromLabel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -225,6 +225,10 @@
     "./item-facts": {
       "types": "./dist/item-facts.d.mts",
       "default": "./dist/item-facts.mjs"
+    },
+    "./testing/stock-key-seam": {
+      "types": "./dist/testing/stock-key-seam.d.mts",
+      "default": "./dist/testing/stock-key-seam.mjs"
     }
   },
   "files": [