usedesign 0.2.0

package/dist/schema/route-inventory.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/nistoc/usedesign/schema/route-inventory.schema.json",
+  "title": "usedesign route inventory",
+  "description": "What the code actually registers, as an explicit artifact. Produced by the checked repository — usedesign consumes this, it does not extract routes. See design/route-conformance.md §3.",
+  "type": "object",
+  "required": ["usedesign_inventory", "produced_by", "routes"],
+  "additionalProperties": false,
+  "properties": {
+    "usedesign_inventory": {
+      "const": 1,
+      "description": "Format version."
+    },
+    "produced_by": {
+      "type": "string",
+      "minLength": 1,
+      "$comment": "Required. An inventory whose origin is unknown cannot be judged: a runtime dump and a hand-written list carry very different weight, and check 1 is only as trustworthy as its input.",
+      "description": "How this list was produced — e.g. 'runtime dump, express 4.19' or 'static extraction, scripts/routes.py'."
+    },
+    "produced_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Optional. A stale inventory is a silent lie; recording when it was taken lets a checker warn."
+    },
+    "routes": {
+      "type": "array",
+      "minItems": 1,
+      "$comment": "An empty inventory is almost always a failed dump rather than an application with no routes — and silently passing check 1 on a failed dump is the worst outcome the check can produce.",
+      "items": {
+        "type": "object",
+        "required": ["method", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "method": {
+            "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+            "description": "One entry per method. A handler registered for two methods produces two entries."
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^/",
+            "description": "The final path as served, including any mount prefix. Parameter syntax is whatever the framework uses — the checker normalises it."
+          },
+          "source": {
+            "type": "string",
+            "description": "Optional, for humans reading a diff. Never used for matching."
+          }
+        }
+      }
+    }
+  }
+}

package/dist/validate.d.ts

@@ -0,0 +1,18 @@
+import { Card, Finding } from "./core.js";
+export declare const REPO: string;
+export declare const MATURITY: string[];
+/**
+ * Where the published schema is. In the repository it is `schema/` at the root; in a published
+ * package it is copied next to the compiled code at build time. Both are the *same file* — the
+ * tool never carries a private variant of the schema it claims to implement, because that is how
+ * a schema and its implementation quietly start to disagree.
+ */
+export declare function schemaPathFor(name?: string): string;
+/** Validate a card's *form* against the published JSON Schema. */
+export declare function validateSchema(fm: Card): Finding[];
+/**
+ * Validate one card's *meaning*. `knownIds` enables the cross-card reference warnings; pass null
+ * when validating a card on its own, so that pointing at a card outside the set is not reported
+ * as if it were missing.
+ */
+export declare function validate(fm: Card, filename?: string, knownIds?: Set<string> | null): Finding[];

package/dist/validate.js

@@ -0,0 +1,259 @@
+/**
+ * Card validation: the JSON Schema for form, and the cross-reference rules for meaning.
+ *
+ * SPEC §7 draws the line — the schema says whether a card is *shaped* like a card, and this file
+ * says whether it *means* anything. A schema cannot know that a test covers a step that does not
+ * exist, and a hand-written rule should not be re-checking that `maturity` is a string.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, basename } from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { Finding } from "./core.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const REPO = join(HERE, "..", "..", "..");
+const REQUIRED = ["id", "title", "actors", "maturity", "steps", "concurrency", "interfaces", "data", "provenance", "reversibility"];
+export const MATURITY = ["conceived", "designed", "implemented", "tested", "in_production", "deprecated"];
+const CONCURRENCY_MODES = ["etag_required", "idempotency_by_header", "idempotency_by_formula", "none_by_design"];
+const TRANSPORTS = ["http_rest", "json_rpc", "in_process", "ui"];
+const TEST_LEVELS = ["unit", "integration", "ui", "contract"];
+const OPERATION_ID = /^[a-z0-9]+(\.[a-z0-9-]+){2,}$/;
+const STEP_ID = /^s[0-9]+-[a-z0-9-]+$/;
+/** maturity level → the evidence key it must carry */
+const EVIDENCE_FOR = {
+    implemented: "implemented",
+    tested: "tested",
+    in_production: "deployed",
+};
+let compiled = null;
+/**
+ * Where the published schema is. In the repository it is `schema/` at the root; in a published
+ * package it is copied next to the compiled code at build time. Both are the *same file* — the
+ * tool never carries a private variant of the schema it claims to implement, because that is how
+ * a schema and its implementation quietly start to disagree.
+ */
+export function schemaPathFor(name = "operation-card.schema.json") {
+    const packaged = join(HERE, "schema", name);
+    return existsSync(packaged) ? packaged : join(REPO, "schema", name);
+}
+/** Compile the published schema once. */
+function schemaValidator(schemaPath = schemaPathFor()) {
+    if (compiled)
+        return compiled;
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats.default ? addFormats.default(ajv) : addFormats(ajv);
+    compiled = ajv.compile(JSON.parse(readFileSync(schemaPath, "utf8")));
+    return compiled;
+}
+/** Validate a card's *form* against the published JSON Schema. */
+export function validateSchema(fm) {
+    const validator = schemaValidator();
+    if (validator(fm))
+        return [];
+    return (validator.errors ?? []).map((error) => new Finding("schema_violation", `${error.instancePath || "/"} ${error.message}`.trim()));
+}
+/**
+ * Validate one card's *meaning*. `knownIds` enables the cross-card reference warnings; pass null
+ * when validating a card on its own, so that pointing at a card outside the set is not reported
+ * as if it were missing.
+ */
+export function validate(fm, filename = "", knownIds = null) {
+    const out = [];
+    const err = (code, detail) => out.push(new Finding(code, detail));
+    const warn = (code, detail) => out.push(new Finding(code, detail, "warning"));
+    for (const field of REQUIRED) {
+        if (!(field in fm))
+            err("missing_required_field", `\`${field}\` is absent`);
+    }
+    const cardId = fm["id"] ?? "";
+    if (cardId && !OPERATION_ID.test(cardId)) {
+        err("malformed_operation_id", `\`${cardId}\` is not <area>.<object>.<action>`);
+    }
+    if (filename && cardId && basename(filename).replace(/\.md$/, "") !== `${cardId}.op`) {
+        warn("filename_mismatch", `file name does not match id \`${cardId}\``);
+    }
+    if (!("scenario" in fm) && !("serves_step" in fm)) {
+        err("no_owner", "neither `scenario` nor `serves_step` is present");
+    }
+    const maturity = fm["maturity"];
+    if (maturity !== undefined && !MATURITY.includes(maturity)) {
+        err("invalid_enum_value", `maturity \`${maturity}\` is not one of ${MATURITY}`);
+    }
+    // ── steps ──────────────────────────────────────────────────────────────────────────────────
+    const steps = fm["steps"] ?? [];
+    const stepIds = new Set();
+    for (const step of steps) {
+        const sid = step?.id ?? "";
+        if (!STEP_ID.test(sid))
+            err("malformed_step_id", `\`${sid}\` is not s<N>-<name>`);
+        else if (stepIds.has(sid))
+            err("duplicate_step_id", `\`${sid}\` appears more than once`);
+        stepIds.add(sid);
+    }
+    // ── maturity vs evidence ───────────────────────────────────────────────────────────────────
+    const evidence = fm["maturity_evidence"] ?? {};
+    const tests = fm["tests"] ?? [];
+    if (maturity && maturity in EVIDENCE_FOR) {
+        // Every level implies the ones below it.
+        for (const level of ["implemented", "tested", "in_production"]) {
+            if (MATURITY.indexOf(maturity) >= MATURITY.indexOf(level)) {
+                const key = EVIDENCE_FOR[level];
+                if (!(key in evidence)) {
+                    err("maturity_without_evidence", `\`${maturity}\` claimed without \`maturity_evidence.${key}\``);
+                }
+            }
+        }
+    }
+    if (maturity && ["tested", "in_production"].includes(maturity) && tests.length === 0) {
+        err("maturity_without_tests", `\`${maturity}\` claimed with an empty \`tests[]\``);
+    }
+    // ── concurrency ────────────────────────────────────────────────────────────────────────────
+    const concurrency = fm["concurrency"] ?? {};
+    const mode = concurrency["mode"];
+    if (mode !== undefined && !CONCURRENCY_MODES.includes(mode)) {
+        err("invalid_enum_value", `concurrency.mode \`${mode}\` is not one of ${CONCURRENCY_MODES}`);
+    }
+    if (mode && mode !== "etag_required" && !concurrency["rationale"]) {
+        err("relaxation_without_rationale", `mode \`${mode}\` weakens protection without a rationale`);
+    }
+    if (mode === "idempotency_by_formula" && !concurrency["formula"]) {
+        err("missing_required_field", "idempotency_by_formula without `formula`");
+    }
+    // ── interfaces ─────────────────────────────────────────────────────────────────────────────
+    const interfaces = fm["interfaces"] ?? {};
+    if (Object.keys(interfaces).length === 0) {
+        err("missing_required_field", "at least one interface is required");
+    }
+    for (const [name, iface] of Object.entries(interfaces)) {
+        const transport = iface?.transport;
+        if (!transport)
+            err("missing_transport", `interface \`${name}\` does not declare a transport`);
+        else if (!TRANSPORTS.includes(transport)) {
+            err("invalid_enum_value", `interface \`${name}\`: transport \`${transport}\` is unknown`);
+        }
+        for (const ref of iface?.covers_steps ?? []) {
+            if (!stepIds.has(ref))
+                err("unknown_step_reference", `interface \`${name}\` covers unknown step \`${ref}\``);
+        }
+    }
+    // ── tests ──────────────────────────────────────────────────────────────────────────────────
+    const covered = new Set();
+    for (const test of tests) {
+        const refs = Array.isArray(test?.covers) ? test.covers : [test?.covers];
+        for (const ref of refs) {
+            if (!stepIds.has(ref))
+                err("unknown_step_reference", `test \`${test?.id}\` covers unknown step \`${ref}\``);
+            covered.add(ref);
+        }
+        if (!TEST_LEVELS.includes(test?.level)) {
+            err("invalid_enum_value", `test \`${test?.id}\`: level \`${test?.level}\` is unknown`);
+        }
+    }
+    const gaps = new Set((fm["coverage_gaps"] ?? []).map((gap) => gap?.step));
+    for (const gap of gaps) {
+        if (!stepIds.has(gap))
+            err("unknown_step_reference", `coverage_gaps names unknown step \`${gap}\``);
+    }
+    for (const sid of stepIds) {
+        if (!covered.has(sid) && !gaps.has(sid)) {
+            warn("step_unproven", `step \`${sid}\` has no test and no declared gap`);
+        }
+    }
+    // ── outcomes, continuation, parameters ─────────────────────────────────────────────────────
+    //
+    // Three rules that need nothing but the card itself. Each one exists because the field it
+    // guards is otherwise a claim nobody can be wrong about — and a claim nobody can be wrong
+    // about is a claim nobody maintains.
+    const outcomes = fm["outcomes"] ?? [];
+    const outcomeIds = new Set(outcomes.map((o) => o?.id));
+    for (const [name, iface] of Object.entries(interfaces)) {
+        const declared = iface?.responses ?? [];
+        if (declared.length === 0)
+            continue; // the field is optional; absent is not a claim
+        const returned = new Map();
+        for (const step of steps) {
+            const code = step?.on_violation?.http;
+            if (typeof code === "number")
+                returned.set(code, `step \`${step.id}\``);
+        }
+        for (const outcome of outcomes) {
+            if (typeof outcome?.http === "number")
+                returned.set(outcome.http, `outcome \`${outcome.id}\``);
+        }
+        for (const [code, who] of returned) {
+            if (!declared.includes(code)) {
+                err("undeclared_response", `interface \`${name}\`: ${who} returns ${code}, absent from \`responses\``);
+            }
+        }
+    }
+    // A violated step that answers with success is either a typo or not a violation at all. The
+    // second case is real: a bulk operation reports per-item failures inside a 200, and the whole
+    // shape of `steps[]` — violated, therefore stopped, therefore an error code — does not fit it.
+    // A warning, not an error, because the honest bulk card would otherwise be unwritable.
+    const perItem = fm["per_item"];
+    for (const step of steps) {
+        const code = step?.on_violation?.http;
+        if (typeof code === "number" && code >= 200 && code < 300) {
+            if (perItem) {
+                // With `per_item` declared there is a true place to write this, so writing it falsely
+                // is a mistake rather than a shortage of vocabulary.
+                err("per_item_failure_as_violation", `step \`${step.id}\` answers ${code}; this card declares \`per_item\`, so a per-item failure belongs there and carries no status`);
+            }
+            else {
+                warn("violation_with_success_status", `step \`${step.id}\` is violated yet answers ${code} — either a typo, or this is a per-item failure and belongs in \`per_item\``);
+            }
+        }
+    }
+    // `after` may name an outcome or a job state. Axis F was designed with one example in hand —
+    // an operation answering immediately and suspending on an outcome — and the rule was fitted to
+    // it. A request thread suspends on `done`, a *job state*, and waits there for a person. The
+    // axis survived that; its check did not.
+    const continuation = fm["continuation"];
+    if (continuation && typeof continuation === "object") {
+        const jobStates = fm["async_execution"]?.job_states ?? [];
+        if (!outcomeIds.has(continuation.after) && !jobStates.includes(continuation.after)) {
+            err("continuation_without_outcome", `\`continuation.after\` names \`${continuation.after}\`, which is neither a declared outcome nor a job state`);
+        }
+    }
+    for (const [name, iface] of Object.entries(interfaces)) {
+        for (const parameter of iface?.parameters ?? []) {
+            if (parameter?.handling !== "decorative")
+                continue;
+            const path = iface?.path ?? "";
+            if (!path.includes(`{${parameter.name}}`)) {
+                err("decorative_parameter_not_in_path", `interface \`${name}\`: \`${parameter.name}\` is declared decorative but does not appear in \`${path || "(no path)"}\``);
+            }
+        }
+    }
+    // An operation that produces no effect has nothing to reverse. Saying `reversible` there
+    // answers a different question than the one asked, and both read-only cards in this project
+    // said it — because the field is required and, until round 7, had no honest value for them.
+    // A warning, not an error: the reading is a judgement about the card's own claims, and a
+    // checker that hard-fails on judgement gets switched off.
+    if (fm["data_transition"] === null && fm["provenance"] === "none" && fm["reversibility"] === "reversible") {
+        warn("reversibility_overstated", "read-only operation claims `reversible`; nothing was done, so nothing can be undone");
+    }
+    // ── effect of a write ──────────────────────────────────────────────────────────────────────
+    if ("data_transition" in fm && fm["data_transition"] === null) {
+        if (!fm["mutates"] && fm["provenance"] !== "none") {
+            err("write_without_effect", "`data_transition: null` with neither `mutates` nor `provenance: none`");
+        }
+    }
+    // ── cross-card references ──────────────────────────────────────────────────────────────────
+    if (knownIds !== null) {
+        const reversibility = fm["reversibility"];
+        if (reversibility && typeof reversibility === "object") {
+            const target = reversibility.reversible_via;
+            if (target && !knownIds.has(target)) {
+                warn("undescribed_counterpart", `\`reversible_via\` points at undescribed \`${target}\``);
+            }
+        }
+        const serves = fm["serves_step"];
+        if (serves && !knownIds.has(serves.operation)) {
+            warn("undescribed_counterpart", `\`serves_step\` points at undescribed \`${serves.operation}\``);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "usedesign",
+  "version": "0.2.0",
+  "description": "Validate and check Operation Cards: no wild endpoints, no unproven steps, no maturity beyond its evidence.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nistoc/usedesign.git",
+    "directory": "impl/typescript"
+  },
+  "homepage": "https://nistoc.github.io/usedesign/",
+  "type": "module",
+  "bin": {
+    "usedesign": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-schema.mjs",
+    "conformance": "npm run build && node dist/cli.js conformance",
+    "test": "npm run conformance"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "fast-xml-parser": "^4.5.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "operation-card",
+    "traceability",
+    "specification",
+    "openapi",
+    "documentation"
+  ]
+}