@daltonr/authwrite-testing 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { AuthEngine, AuthObserver, DecisionEvent, Decision, Subject, Resource } from '@daltonr/authwrite-core';
+export interface DecisionRecorder extends AuthObserver {
+    /** All decision events recorded so far, in order. */
+    all(): DecisionEvent[];
+    /** Shorthand — just the Decision objects, without the wrapping event. */
+    decisions(): Decision[];
+    /** Clear all recorded events. */
+    clear(): void;
+}
+export declare function decisionRecorder(): DecisionRecorder;
+export interface CoverageReport {
+    totalRules: number;
+    coveredRules: string[];
+    untouchedRules: string[];
+    coveragePercent: number;
+}
+/**
+ * Analyse which rules in the engine's active policy were never the deciding
+ * reason in any recorded event. Pass `recorder.all()` as the second argument.
+ *
+ * An untouched rule is a silent security hole — if a deny rule has never fired
+ * in your test suite, you have no evidence it works.
+ */
+export declare function coverageReport<S extends Subject = Subject, R extends Resource = Resource>(engine: AuthEngine<S, R>, events: DecisionEvent[]): CoverageReport;

package/dist/index.js

@@ -0,0 +1,38 @@
+export function decisionRecorder() {
+    const events = [];
+    return {
+        onDecision(event) {
+            events.push(event);
+        },
+        all() {
+            return [...events];
+        },
+        decisions() {
+            return events.map(e => e.decision);
+        },
+        clear() {
+            events.length = 0;
+        },
+    };
+}
+/**
+ * Analyse which rules in the engine's active policy were never the deciding
+ * reason in any recorded event. Pass `recorder.all()` as the second argument.
+ *
+ * An untouched rule is a silent security hole — if a deny rule has never fired
+ * in your test suite, you have no evidence it works.
+ */
+export function coverageReport(engine, events) {
+    const policy = engine.getPolicy();
+    if (!policy) {
+        throw new Error('coverageReport requires a static policy — engine has a dynamic or composite resolver. ' +
+            'Run at least one evaluation first, or pass a static PolicyDefinition to createAuthEngine.');
+    }
+    const allRuleIds = policy.rules.map(r => r.id);
+    const reasonsHit = new Set(events.map(e => e.decision.reason));
+    const coveredRules = allRuleIds.filter(id => reasonsHit.has(id));
+    const untouchedRules = allRuleIds.filter(id => !reasonsHit.has(id));
+    const coveragePercent = allRuleIds.length === 0 ? 100 : (coveredRules.length / allRuleIds.length) * 100;
+    return { totalRules: allRuleIds.length, coveredRules, untouchedRules, coveragePercent };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAoB,EAAE,CAAA;IAElC,OAAO;QACL,UAAU,CAAC,KAAK;YACd,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;QACD,GAAG;YACD,OAAO,CAAC,GAAG,MAAM,CAAC,CAAA;QACpB,CAAC;QACD,SAAS;YACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;QACpC,CAAC;QACD,KAAK;YACH,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC;AAWD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAwB,EACxB,MAAuB;IAEvB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAA;IACjC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,wFAAwF;YACxF,2FAA2F,CAC5F,CAAA;IACH,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;IAE9D,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAChE,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAEnE,MAAM,eAAe,GACnB,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,GAAG,CAAA;IAEjF,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA;AACzF,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@daltonr/authwrite-testing",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Test helpers for AuthEngine: decision recorder and policy coverage report.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richardadalton/authwrite.git",
+    "directory": "packages/testing"
+  },
+  "keywords": ["authorization", "authz", "testing", "coverage", "policy"],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepublishOnly": "test -d dist && echo 'dist already built, skipping' || (npm run clean && npm run build)"
+  },
+  "dependencies": {
+    "@daltonr/authwrite-core": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+import type {
+  AuthEngine,
+  AuthObserver,
+  DecisionEvent,
+  Decision,
+  PolicyDefinition,
+  Subject,
+  Resource,
+} from '@daltonr/authwrite-core'
+
+// ─── DecisionRecorder ────────────────────────────────────────────────────────
+
+export interface DecisionRecorder extends AuthObserver {
+  /** All decision events recorded so far, in order. */
+  all(): DecisionEvent[]
+  /** Shorthand — just the Decision objects, without the wrapping event. */
+  decisions(): Decision[]
+  /** Clear all recorded events. */
+  clear(): void
+}
+
+export function decisionRecorder(): DecisionRecorder {
+  const events: DecisionEvent[] = []
+
+  return {
+    onDecision(event) {
+      events.push(event)
+    },
+    all() {
+      return [...events]
+    },
+    decisions() {
+      return events.map(e => e.decision)
+    },
+    clear() {
+      events.length = 0
+    },
+  }
+}
+
+// ─── CoverageReport ──────────────────────────────────────────────────────────
+
+export interface CoverageReport {
+  totalRules: number
+  coveredRules: string[]
+  untouchedRules: string[]
+  coveragePercent: number
+}
+
+/**
+ * Analyse which rules in the engine's active policy were never the deciding
+ * reason in any recorded event. Pass `recorder.all()` as the second argument.
+ *
+ * An untouched rule is a silent security hole — if a deny rule has never fired
+ * in your test suite, you have no evidence it works.
+ */
+export function coverageReport<S extends Subject = Subject, R extends Resource = Resource>(
+  engine: AuthEngine<S, R>,
+  events: DecisionEvent[]
+): CoverageReport {
+  const policy = engine.getPolicy()
+  if (!policy) {
+    throw new Error(
+      'coverageReport requires a static policy — engine has a dynamic or composite resolver. ' +
+      'Run at least one evaluation first, or pass a static PolicyDefinition to createAuthEngine.'
+    )
+  }
+  const allRuleIds = policy.rules.map(r => r.id)
+  const reasonsHit = new Set(events.map(e => e.decision.reason))
+
+  const coveredRules = allRuleIds.filter(id => reasonsHit.has(id))
+  const untouchedRules = allRuleIds.filter(id => !reasonsHit.has(id))
+
+  const coveragePercent =
+    allRuleIds.length === 0 ? 100 : (coveredRules.length / allRuleIds.length) * 100
+
+  return { totalRules: allRuleIds.length, coveredRules, untouchedRules, coveragePercent }
+}