@suluk/harden 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/harden",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Schema HARDENING as a derived contract facet: audit a v4 'Suluk' document's input schemas for the validations that keep weird/oversized input from breaking the system — every string a maxLength + a pattern, every number a maximum, every array a maxItems, every object closed + typed, no any/unknown — score it (A-F), surface the grade to INCENTIVISE the author, and gate CI on a minimum. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -19,7 +19,8 @@
 ".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "^0.1.11"
+"@suluk/core": "^0.1.13",
+"@suluk/examples": "^0.1.0"
 },
 "devDependencies": {
 "@types/bun": "latest"

package/src/index.ts

@@ -16,3 +16,6 @@ export {
 } from "./audit";
 // the inverse of the audit — the hardening TRANSFORM that adds the baseline bounds the audit grades for.
 export { hardenSchema, hardenDocument, type HardenOptions } from "./harden";
+// C043: a SECOND dimension — schema-fact READINESS (computed-required, request-without-example), separate from the
+// security grade. Fold its letter into `combineGrades` alongside the security grade + journeys coverage.
+export { auditReadiness, type ReadinessAudit, type ReadinessOptions } from "./readiness";

package/src/readiness.ts

@@ -0,0 +1,79 @@
+/**
+ * READINESS audit (C043) — a SECOND, separate harden dimension (kept apart from the security `auditDocument` grade so a
+ * security score never mixes with a readiness score). It grades schema-FACT readiness the doc can answer alone — the
+ * concerns C040/C041 made expressible:
+ *   • `computed-required` — a request field marked `computed` (or `readOnly`) AND `required`: a client CANNOT send it,
+ *     so the request can never be satisfied (a real contract bug). HIGH.
+ *   • `request-without-example` — a request body with no curated `examples`/`example` (author one in `.meta`, or promote
+ *     a tester `@public` row). A docs/demo readiness gap. LOW.
+ *
+ * BDD COVERAGE is the OTHER readiness gap — but it needs the `.feature` files, so `@suluk/journeys` computes it and the
+ * caller folds its letter in via `combineGrades` (harden never depends on journeys — the established harden+agents seam).
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { fieldOrigin, type JsonSchema } from "@suluk/examples";
+import { grade, type Finding, type Grade } from "./audit";
+
+export interface ReadinessAudit {
+  findings: Finding[];
+  nodes: number;
+  clean: number;
+  score: number;
+  grade: Grade;
+}
+
+export interface ReadinessOptions {
+  /** skip operations (e.g. third-party/ingested surfaces) — they don't count toward the readiness grade. */
+  ignore?: (uri: string, name: string) => boolean;
+}
+
+interface RawReq {
+  method: string;
+  contentSchema?: unknown;
+  parameterSchema?: { body?: unknown };
+}
+
+const hasExample = (s: JsonSchema): boolean => (Array.isArray(s.examples) && s.examples.length > 0) || "example" in s;
+
+/** Audit the document's request bodies for client-sendability + example presence → findings + a readiness grade. */
+export function auditReadiness(doc: OpenAPIv4Document, opts: ReadinessOptions = {}): ReadinessAudit {
+  const findings: Finding[] = [];
+  let nodes = 0;
+  let clean = 0;
+  const pass = () => {
+    nodes++;
+    clean++;
+  };
+  const fail = (f: Finding) => {
+    nodes++;
+    findings.push(f);
+  };
+
+  for (const [uri, piRaw] of Object.entries(doc.paths ?? {})) {
+    const pi = piRaw as { requests?: Record<string, RawReq> };
+    for (const [name, req] of Object.entries(pi.requests ?? {})) {
+      if (opts.ignore?.(uri, name)) continue;
+      const body = (req.contentSchema ?? req.parameterSchema?.body) as JsonSchema | undefined;
+      if (!body || typeof body !== "object") continue; // no request body → nothing to assess
+
+      // node: a curated example present?
+      if (hasExample(body)) pass();
+      else fail({ rule: "request-without-example", severity: "low", path: `${name}/body`, message: `request '${name}' has no example`, fix: "author one in .meta({ examples }), or promote a tester @public row via `journeys promote`" });
+
+      // node per REQUIRED field: is it client-sendable (not computed/readOnly)?
+      const props = (body.properties ?? {}) as Record<string, JsonSchema>;
+      const required = new Set(Array.isArray(body.required) ? (body.required as string[]) : []);
+      for (const [k, sub] of Object.entries(props)) {
+        if (!required.has(k)) continue;
+        if (fieldOrigin(sub) === "computed") {
+          fail({ rule: "computed-required", severity: "high", path: `${name}/body/${k}`, message: `required field '${k}' is computed/readOnly — a client cannot send it`, fix: "make it optional or non-computed (drop x-suluk-origin:computed / readOnly), or remove it from required" });
+        } else {
+          pass();
+        }
+      }
+    }
+  }
+
+  const score = nodes === 0 ? 100 : Math.round((clean / nodes) * 100);
+  return { findings, nodes, clean, score, grade: grade(score) };
+}

package/test/readiness.test.ts

@@ -0,0 +1,85 @@
+import { test, expect, describe } from "bun:test";
+import { auditReadiness } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C043 — the readiness dimension: computed-required (a required field a client can't send) + request-without-example.
+ * Separate from the security grade; folded into combineGrades alongside security + journeys coverage.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "balance"],
+            properties: {
+              amountCents: { type: "integer" },
+              balance: { type: "integer", "x-suluk-origin": "computed" }, // required AND computed → a bug
+            },
+          },
+        },
+      },
+    },
+    "/good": {
+      requests: {
+        good: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["name"],
+            properties: { name: { type: "string" } },
+            examples: [{ name: "ok" }], // has an example
+          },
+        },
+      },
+    },
+    "/health": { requests: { health: { method: "get", responses: { "200": { status: 200 } } } } }, // no body → not assessed
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("auditReadiness", () => {
+  const audit = auditReadiness(doc);
+  const rules = audit.findings.map((f) => f.rule);
+
+  test("flags a required computed/readOnly field as not client-sendable (high)", () => {
+    const f = audit.findings.find((x) => x.rule === "computed-required");
+    expect(f).toBeDefined();
+    expect(f!.severity).toBe("high");
+    expect(f!.path).toBe("charge/body/balance");
+  });
+
+  test("flags a request body with no example (low)", () => {
+    const f = audit.findings.find((x) => x.rule === "request-without-example" && x.path === "charge/body");
+    expect(f).toBeDefined();
+    expect(f!.severity).toBe("low");
+  });
+
+  test("a body WITH an example + only sendable required fields raises no finding", () => {
+    expect(rules).not.toContain("good/body");
+    expect(audit.findings.some((f) => f.path.startsWith("good/"))).toBe(false);
+  });
+
+  test("a body-less op is not assessed (no nodes for it)", () => {
+    expect(audit.findings.some((f) => f.path.startsWith("health/"))).toBe(false);
+  });
+
+  test("produces a score + grade from the clean/nodes ratio", () => {
+    expect(audit.nodes).toBeGreaterThan(0);
+    expect(["A", "B", "C", "D", "F"]).toContain(audit.grade);
+  });
+
+  test("readOnly is treated as computed (no x-suluk-origin needed)", () => {
+    const ro = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { "/x": { requests: { x: { method: "post", contentSchema: { type: "object", required: ["id"], properties: { id: { type: "string", readOnly: true } } } } } } } } as unknown as OpenAPIv4Document;
+    expect(auditReadiness(ro).findings.some((f) => f.rule === "computed-required")).toBe(true);
+  });
+
+  test("a clean contract grades A", () => {
+    const clean = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { "/x": { requests: { x: { method: "post", contentSchema: { type: "object", required: ["n"], properties: { n: { type: "string" } }, examples: [{ n: "a" }] } } } } } } as unknown as OpenAPIv4Document;
+    expect(auditReadiness(clean).grade).toBe("A");
+  });
+});