@classytic/primitives 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 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.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/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.1",
   "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": [