@stratum-hq/compliance 0.1.1 → 0.1.3

package/README.md

@@ -2,11 +2,13 @@
 
 A content-free compliance **kernel** for [Stratum](https://github.com/stratum-hq/Stratum): the pure mechanics and type shapes any compliance product needs, with none of the content. Zero runtime dependencies, no database, no network, no provider, and no built-in catalog.
 
+Read the documentation at [docs.stratum-hq.org/packages/compliance](https://docs.stratum-hq.org/packages/compliance/).
+
 It gives you three things:
 
-1. **Coverage scoring** — diff a declared baseline against a resolved state and get a per-control breakdown plus a 0 to 100 score.
-2. **A finding state machine** — a pure decision for whether a new evaluation outcome should open, resolve, or leave a finding alone.
-3. **A control type vocabulary** — structural interfaces for describing a catalog of controls.
+1. **Coverage scoring:** diff a declared baseline against a resolved state and get a per-control breakdown plus a 0 to 100 score.
+2. **A finding state machine:** a pure decision for whether a new evaluation outcome should open, resolve, or leave a finding alone.
+3. **A control type vocabulary:** structural interfaces for describing a catalog of controls.
 
 > [!NOTE]
 > This is **not** a batteries-included compliance solution. It ships no frameworks, no controls, no provider mappings, and no thresholds. **Bring your own catalog:** you supply the content and the persistence; this package supplies the arithmetic and the shapes.
@@ -42,7 +44,7 @@ const result = scoreCoverage(baseline, resolved);
 ```
 
 - `status` is `"compliant"` (matches), `"drift"` (present but wrong), or `"missing"` (no own resolved entry for that key).
-- `score` is `round(compliant / total * 100)`. An **empty baseline scores 100** — nothing is required, so nothing is out of compliance.
+- `score` is `round(compliant / total * 100)`. An **empty baseline scores 100**. Nothing is required, so nothing is out of compliance.
 
 ### Equality
 
@@ -57,16 +59,16 @@ looseEqual(true, "true"); // => true
 
 ## Finding state machine
 
-`reconcileFinding` decides what should happen to a control's finding when a new evaluation outcome arrives. It is a pure decision — you persist the result.
+`reconcileFinding` decides what should happen to a control's finding when a new evaluation outcome arrives. It is a pure decision; you persist the result.
 
 ```typescript
 import { reconcileFinding } from "@stratum-hq/compliance";
 
-reconcileFinding("fail", "none"); // { type: "open" }    — new gap
-reconcileFinding("fail", "open"); // { type: "noop" }    — already tracked
-reconcileFinding("pass", "open"); // { type: "resolve" } — gap closed
-reconcileFinding("pass", "accepted"); // { type: "noop" } — accepted risk untouched
-reconcileFinding("na", "open"); // { type: "noop" }      — na/error never change a finding
+reconcileFinding("fail", "none"); // { type: "open" }    (new gap)
+reconcileFinding("fail", "open"); // { type: "noop" }    (already tracked)
+reconcileFinding("pass", "open"); // { type: "resolve" } (gap closed)
+reconcileFinding("pass", "accepted"); // { type: "noop" } (accepted risk untouched)
+reconcileFinding("na", "open"); // { type: "noop" }      (na/error never change a finding)
 ```
 
 The rules:
@@ -74,8 +76,9 @@ The rules:
 - `fail` **opens** a finding, unless one is already active (`open` / `remediating`) or the risk was formally `accepted`.
 - `pass` **resolves** an active finding (`open` / `remediating`), and leaves an `accepted` finding untouched; otherwise there is nothing to resolve.
 - `na` and `error` are always no-ops.
+- Any other outcome throws a `TypeError`.
 
-Map `{ type: "open" }` and `{ type: "resolve" }` onto your own inserts and updates — the state machine has no opinion about storage.
+Map `{ type: "open" }` and `{ type: "resolve" }` onto your own inserts and updates. The state machine has no opinion about storage.
 
 ## Type vocabulary
 
@@ -98,6 +101,7 @@ Everything here is a pure function or a type. No side effects, no IO, no global
 
 ## Links
 
+- Documentation: https://docs.stratum-hq.org/packages/compliance/
 - GitHub: https://github.com/stratum-hq/Stratum
 
 ## License

package/dist/finding.d.ts

@@ -19,6 +19,7 @@ export type FindingAction = {
  * - `pass` resolves an active finding (`open` / `remediating`), and leaves an
  *   `accepted` finding untouched; there is nothing to resolve otherwise.
  * - `na` and `error` never change a finding.
+ * - Any other outcome throws a `TypeError`.
  */
 export declare function reconcileFinding(newOutcome: ControlOutcome, currentState: FindingState): FindingAction;
 //# sourceMappingURL=finding.d.ts.map

package/dist/finding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finding.d.ts","sourceRoot":"","sources":["../src/finding.ts"],"names":[],"mappings":"AAQA,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;AAE9D,gFAAgF;AAChF,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,aAAa,GACb,UAAU,GACV,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,EAC1B,YAAY,EAAE,YAAY,GACzB,aAAa,CAsBf"}
+{"version":3,"file":"finding.d.ts","sourceRoot":"","sources":["../src/finding.ts"],"names":[],"mappings":"AAQA,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;AAE9D,gFAAgF;AAChF,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,aAAa,GACb,UAAU,GACV,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,EAC1B,YAAY,EAAE,YAAY,GACzB,aAAa,CA4Bf"}

package/dist/finding.js

@@ -18,6 +18,7 @@ exports.reconcileFinding = reconcileFinding;
  * - `pass` resolves an active finding (`open` / `remediating`), and leaves an
  *   `accepted` finding untouched; there is nothing to resolve otherwise.
  * - `na` and `error` never change a finding.
+ * - Any other outcome throws a `TypeError`.
  */
 function reconcileFinding(newOutcome, currentState) {
     switch (newOutcome) {
@@ -36,6 +37,9 @@ function reconcileFinding(newOutcome, currentState) {
         case "na":
         case "error":
             return { type: "noop" };
+        default:
+            // Unreachable for typed callers; guards untyped input such as parsed JSON.
+            throw new TypeError(`reconcileFinding: unknown control outcome ${JSON.stringify(newOutcome)}; expected one of pass, fail, na, error`);
     }
 }
 //# sourceMappingURL=finding.js.map

package/dist/finding.js.map

@@ -1 +1 @@
-{"version":3,"file":"finding.js","sourceRoot":"","sources":["../src/finding.ts"],"names":[],"mappings":";AAAA,yBAAyB;AACzB,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,eAAe;;AA6Bf,4CAyBC;AApCD;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAC9B,UAA0B,EAC1B,YAA0B;IAE1B,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,IACE,YAAY,KAAK,MAAM;gBACvB,YAAY,KAAK,aAAa;gBAC9B,YAAY,KAAK,UAAU,EAC3B,CAAC;gBACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;YAC1B,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,MAAM;YACT,IAAI,YAAY,KAAK,MAAM,IAAI,YAAY,KAAK,aAAa,EAAE,CAAC;gBAC9D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7B,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,IAAI,CAAC;QACV,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"finding.js","sourceRoot":"","sources":["../src/finding.ts"],"names":[],"mappings":";AAAA,yBAAyB;AACzB,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,eAAe;;AA8Bf,4CA+BC;AA3CD;;;;;;;;;;;GAWG;AACH,SAAgB,gBAAgB,CAC9B,UAA0B,EAC1B,YAA0B;IAE1B,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,IACE,YAAY,KAAK,MAAM;gBACvB,YAAY,KAAK,aAAa;gBAC9B,YAAY,KAAK,UAAU,EAC3B,CAAC;gBACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;YAC1B,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,MAAM;YACT,IAAI,YAAY,KAAK,MAAM,IAAI,YAAY,KAAK,aAAa,EAAE,CAAC;gBAC9D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7B,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B,KAAK,IAAI,CAAC;QACV,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAE1B;YACE,2EAA2E;YAC3E,MAAM,IAAI,SAAS,CACjB,6CAA6C,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,yCAAyC,CACjH,CAAC;IACN,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratum-hq/compliance",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Content-free compliance kernel for Stratum: baseline coverage scoring, a finding state machine, and a control type vocabulary",
   "keywords": [
     "compliance",
@@ -43,7 +43,7 @@
   },
   "license": "MIT",
   "author": "Christian Crank",
-  "homepage": "https://github.com/stratum-hq/Stratum/tree/main/packages/compliance#readme",
+  "homepage": "https://docs.stratum-hq.org/packages/compliance/",
   "bugs": "https://github.com/stratum-hq/Stratum/issues",
   "engines": {
     "node": ">=20.0.0"