@lovrozagar/oat 0.1.0

package/dist/report/console.js

@@ -0,0 +1,237 @@
+/**
+ * Console renderers for the offline commands.
+ *
+ * `doctor` is the adoption surface: it reports what oat cannot test against this spec and names
+ * the meta tag that would close each gap. A backend team's path to full coverage is to run it
+ * and work the list down.
+ */
+/**
+ * Which checks each tag makes possible, measured rather than estimated.
+ *
+ * `oat conformance` runs the reference backend twice — once with its tags, once with them
+ * stripped — and asserts this map matches the difference, so it cannot drift into marketing.
+ *
+ * The distinction below is the honest part. Some tags *unlock* checks that are otherwise
+ * impossible: nothing in a document reveals that a 202 is a receipt, or that a column is a
+ * tombstone. Others do not change how much runs at all — they change whether what runs is
+ * trustworthy. Without `x-query`, oat assumes every scalar property is filterable and probes
+ * fields the backend may never have indexed; without `x-tenant`, a cross-tenant read is reported
+ * as an ambiguity because oat only inferred the boundary it thinks was crossed.
+ */
+export const TAG_UNLOCKS = {
+    "x-async": ["async.reaches-terminal-state", "async.receipt-identifies-the-job"],
+    "x-effects": ["effects.declared-effect-occurs"],
+    "x-immutable": ["patch.immutable-field-rejected"],
+    "x-invalidate": ["invalidation.declared-route-changes"],
+    /* Declaring filterable fields is itself a claim, and a claim is testable: oat probes each
+     * one and reports the document — not the backend — when a declared filter is refused. */
+    "x-query": [
+        "spec.declared-filterable-is-filterable",
+        "spec.declared-sortable-is-sortable",
+        "spec.declared-selectable-is-selectable",
+    ],
+    "x-soft-delete": ["softdelete.absent-from-default-list"],
+    "x-invite": ["auth.invite-grants-then-revokes"],
+};
+/** Tags that change the *confidence* of checks that already run, not the count. */
+const TAG_SHARPENS = {
+    "x-query": "the remaining query checks run against every scalar property, including fields the "
+        + "backend never indexed — expect findings you will have to dismiss",
+    "x-tenant": "a cross-tenant read is reported as an ambiguity, not a security finding, because "
+        + "oat inferred the boundary rather than reading it",
+};
+const TAG_REMEDY = {
+    "x-async": "declare the poll route so the operation's real outcome can be observed",
+    "x-entity": "name the entity and action so this operation joins a lifecycle",
+    "x-entity.identity": "name the property identifying an instance",
+    "x-invalidate": "list the read routes this mutation must change",
+    "x-query": "declare which fields support the filter / order / search / select roles",
+    "x-tenant": "name the path parameter that scopes this operation to a tenant",
+    "x-invite": "name the invite, accept and revoke operations for delegated access",
+};
+function bar(value, total, width = 24) {
+    if (total === 0)
+        return "─".repeat(width);
+    const filled = Math.round((value / total) * width);
+    return "█".repeat(filled) + "░".repeat(width - filled);
+}
+function lifecycleGlyphs(entity) {
+    const slots = [
+        ["C", entity.create],
+        ["L", entity.list],
+        ["R", entity.read],
+        ["U", entity.update],
+        ["D", entity.delete],
+    ];
+    return slots.map(([letter, opId]) => (opId === undefined ? "·" : letter)).join("");
+}
+function plan(model, asJson) {
+    if (asJson) {
+        return `${JSON.stringify({
+            entities: [...model.entities.values()],
+            operations: model.operations,
+            roots: model.roots,
+        }, null, 2)}\n`;
+    }
+    const lines = [];
+    const entities = [...model.entities.values()].sort((a, b) => a.name.localeCompare(b.name));
+    lines.push("");
+    lines.push(`  ${model.operations.length} operations · ${entities.length} entities`);
+    lines.push("");
+    lines.push("  entity              CLRUD  ident      read surface");
+    lines.push("  ─────────────────────────────────────────────────────────────────────");
+    for (const entity of entities) {
+        const surface = entity.readSurface.length === 0
+            ? "— none"
+            : `${entity.readSurface.length} route(s)${entity.declaredSurface.length > 0 ? " (declared)" : " (inferred)"}`;
+        lines.push(`  ${entity.name.padEnd(18)}  ${lifecycleGlyphs(entity)}  ${(entity.identity ?? "—").padEnd(9)}  ${surface}`);
+        for (const route of entity.readSurface)
+            lines.push(`  ${"".padEnd(38)}${route}`);
+    }
+    if (model.roots.length > 0) {
+        lines.push("");
+        lines.push("  roots — no create operation, must be supplied before a run:");
+        for (const root of model.roots)
+            lines.push(`    ${root}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function doctor(model, externalRefs, asJson) {
+    const entities = [...model.entities.values()].sort((a, b) => a.name.localeCompare(b.name));
+    const trackable = entities.filter((e) => e.trackable && e.readSurface.length > 0);
+    const listable = trackable.filter((e) => e.list !== undefined);
+    const byTag = new Map();
+    for (const gap of model.gaps.gaps) {
+        const list = byTag.get(gap.tag) ?? [];
+        list.push(gap);
+        byTag.set(gap.tag, list);
+    }
+    const blocking = entities.length - trackable.length + (model.roots.length > 0 ? 1 : 0);
+    if (asJson) {
+        return {
+            blocking,
+            text: `${JSON.stringify({
+                blocking,
+                entities: entities.length,
+                externalRefs,
+                gaps: model.gaps.gaps,
+                listableEntities: listable.length,
+                roots: model.roots,
+                testableEntities: trackable.length,
+                trackableEntities: trackable.length,
+            }, null, 2)}\n`,
+        };
+    }
+    const lines = [];
+    lines.push("");
+    lines.push(`  trackable  ${bar(trackable.length, entities.length)}  ${trackable.length}/${entities.length} ` +
+        "entities have an identity and a read");
+    lines.push(`  listable   ${bar(listable.length, entities.length)}  ${listable.length}/${entities.length} ` +
+        (listable.length === 0
+            ? "entities have a list — query checks will not run"
+            : "entities have a list, so query checks can run"));
+    lines.push("");
+    /*
+     * What the missing tags cost, in checks. A gap list tells an author what oat could not read;
+     * this tells them what they get for fixing it, which is the only form of the message anyone
+     * acts on.
+     */
+    const declared = new Set(model.operations.flatMap((op) => [
+        ...(op.async === null ? [] : ["x-async"]),
+        ...(op.effects.length > 0 ? ["x-effects"] : []),
+        ...(op.immutable.length > 0 ? ["x-immutable"] : []),
+        ...(op.invalidates.length > 0 ? ["x-invalidate"] : []),
+        ...(op.softDelete === null ? [] : ["x-soft-delete"]),
+        ...(op.tenantSource === "tag" ? ["x-tenant"] : []),
+        ...(op.query?.source === "tag" ? ["x-query"] : []),
+    ]));
+    for (const entity of entities) {
+        if (entity.invite !== null)
+            declared.add("x-invite");
+    }
+    const lockedTags = Object.keys(TAG_UNLOCKS).filter((tag) => !declared.has(tag));
+    const lockedChecks = lockedTags.flatMap((tag) => TAG_UNLOCKS[tag] ?? []);
+    if (lockedChecks.length > 0) {
+        lines.push(`  ${lockedChecks.length} check(s) cannot run against this document`);
+        for (const tag of lockedTags) {
+            lines.push(`    ${tag.padEnd(16)} would enable ${(TAG_UNLOCKS[tag] ?? []).join(", ")}`);
+        }
+        lines.push("");
+    }
+    const inferredTenant = model.operations.some((op) => op.tenantSource !== null);
+    const vague = Object.keys(TAG_SHARPENS).filter((tag) => {
+        if (declared.has(tag))
+            return false;
+        if (tag === "x-query")
+            return listable.length > 0;
+        if (tag === "x-tenant")
+            return inferredTenant;
+        return true;
+    });
+    if (vague.length > 0) {
+        lines.push("  running, but on inferred information");
+        for (const tag of vague) {
+            lines.push(`    ${tag.padEnd(16)} ${TAG_SHARPENS[tag] ?? ""}`);
+        }
+        lines.push("");
+    }
+    const untrackable = entities.filter((e) => !trackable.includes(e));
+    if (untrackable.length > 0) {
+        lines.push("  not trackable");
+        for (const entity of untrackable) {
+            const reason = entity.identity === null
+                ? "no identity property — instances cannot be tracked across projections"
+                : "no read surface — mutations cannot be verified";
+            lines.push(`    ${entity.name.padEnd(20)} ${reason}`);
+        }
+        lines.push("");
+    }
+    const itemOnly = trackable.filter((e) => e.list === undefined);
+    if (itemOnly.length > 0) {
+        lines.push("  no list — query, pagination and count checks will not run");
+        for (const entity of itemOnly) {
+            const route = entity.read ?? entity.readSurface[0] ?? "item route only";
+            lines.push(`    ${entity.name.padEnd(20)} ${route}`);
+        }
+        lines.push("");
+    }
+    if (model.roots.length > 0) {
+        lines.push("  roots required in config (no create operation in this document)");
+        for (const root of model.roots)
+            lines.push(`    ${root}`);
+        lines.push("");
+    }
+    if (!model.hasAuthOperations && model.securitySchemes.length > 0) {
+        lines.push("  auth");
+        lines.push(`    document declares ${model.securitySchemes.map((s) => `"${s}"`).join(", ")} but contains no`);
+        lines.push("    operation for obtaining a credential. No generic client can bootstrap from");
+        lines.push("    this spec. Add the auth operations, or declare x-auth-flows at document root.");
+        lines.push("");
+    }
+    if (externalRefs.length > 0) {
+        lines.push("  unresolved external $refs (not fetched — a test tool should not follow arbitrary URLs)");
+        for (const ref of externalRefs)
+            lines.push(`    ${ref}`);
+        lines.push("");
+    }
+    if (byTag.size > 0) {
+        lines.push("  gaps by tag");
+        const sorted = [...byTag.entries()].sort((a, b) => b[1].length - a[1].length);
+        for (const [tag, gapList] of sorted) {
+            const remedy = TAG_REMEDY[tag] ?? "see the README";
+            lines.push(`    ${tag} (${gapList.length}) — ${remedy}`);
+            for (const gap of gapList.slice(0, 4)) {
+                lines.push(`      ${gap.operationId}: ${gap.detail}`);
+            }
+            if (gapList.length > 4)
+                lines.push(`      … and ${gapList.length - 4} more`);
+        }
+        lines.push("");
+    }
+    if (blocking === 0 && byTag.size === 0)
+        lines.push("  no gaps — full coverage available\n");
+    return { blocking, text: lines.join("\n") };
+}
+export const report = { doctor, plan };
+//# sourceMappingURL=console.js.map

package/dist/report/console.js.map

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

package/dist/report/matrix.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Poster + machine graph of how oat crossed the entities in a run.
+ *
+ * One entity is a loom: warp windows on one cohort, weft cells woven only if the warp holds.
+ * Several entities add a second graph on top — `x-invalidate` edges from a writer to another
+ * entity's read surface. That is the claim `invalidation.declared-route-changes` actually tests.
+ */
+import type { ReportInput } from "./render.ts";
+export type CellStatus = "held" | "failed" | "blocked" | "skipped";
+export type MatrixLayer = "warp" | "weft" | "surface" | "auth" | "schema" | "spec";
+export interface MatrixView {
+    entity: string;
+    baseUrl: string;
+    generatedAt: string;
+    readSurface: string[];
+    failed: number;
+    blocked: number;
+    held: number;
+    skipped: number;
+    nodes: MatrixNode[];
+}
+export interface MatrixNode {
+    id: string;
+    label: string;
+    hint: string;
+    status: CellStatus;
+    because?: string;
+}
+export interface MatrixGraphNode {
+    id: string;
+    group: string;
+    layer: MatrixLayer;
+    status: CellStatus;
+    needs?: string;
+    because?: string;
+    summary?: string;
+    verdict?: string;
+}
+export interface MatrixGraphEdge {
+    from: string;
+    to: string;
+    /** `dependsOn`: if `from` failed, `to` is blocked. `uses`: weft cell woven from this warp. */
+    kind: "dependsOn" | "uses";
+}
+export interface InvalidateLink {
+    fromEntity: string;
+    fromOp: string;
+    toEntity: string;
+    toRoute: string;
+    /** True when the declared route belongs to a *different* entity — the case the check probes. */
+    cross: boolean;
+}
+export interface EntityMatrix {
+    name: string;
+    identity: string | null;
+    readSurface: string[];
+    counts: {
+        failed: number;
+        blocked: number;
+        held: number;
+        skipped: number;
+    };
+    roots: string[];
+    nodes: MatrixGraphNode[];
+}
+export interface MatrixGraph {
+    kind: "oat.matrix";
+    version: 2;
+    read: {
+        purpose: string;
+        status: Record<CellStatus, string>;
+        edges: Record<MatrixGraphEdge["kind"] | "invalidate", string>;
+    };
+    baseUrl: string;
+    generatedAt: string;
+    thesis: string;
+    summary: string;
+    index: {
+        entityCount: number;
+        failed: string[];
+        parents: string[];
+        crossClaims: number;
+        inbound: Record<string, number>;
+    };
+    counts: {
+        failed: number;
+        blocked: number;
+        held: number;
+        skipped: number;
+    };
+    entities: EntityMatrix[];
+    invalidate: InvalidateLink[];
+    edges: MatrixGraphEdge[];
+    mermaid: string;
+}
+type MatrixParts = {
+    entity: string;
+    baseUrl: string;
+    generatedAt: string;
+    readSurface: string[];
+    checksRun: readonly string[];
+    checksSkipped: ReadonlyArray<{
+        check: string;
+        entity?: string;
+        needs: string;
+    }>;
+    checksSuppressed: ReadonlyArray<{
+        check: string;
+        entity?: string;
+        because: string;
+    }>;
+    findings: ReadonlyArray<{
+        check: string;
+        entity?: string;
+        verdict: string;
+        summary: string;
+        detail?: string;
+    }>;
+};
+export declare function matrixViewFromReport(input: ReportInput): MatrixView;
+export declare function matrixViewFromParts(parts: MatrixParts): MatrixView;
+export declare function renderMatrixFromParts(parts: MatrixParts): string;
+export declare function renderMatrixHtml(input: ReportInput): string;
+export declare function renderMatrixGraph(input: ReportInput): string;
+export declare function renderMatrixGraphFromParts(parts: MatrixParts): string;
+export declare function buildMatrixGraphFromReport(input: ReportInput): MatrixGraph;
+export declare function buildMatrixGraph(parts: MatrixParts): MatrixGraph;
+/** Drop per-check nodes for clean entities so a 2k-entity graph stays loadable. */
+export declare function compactMatrixGraph(graph: MatrixGraph): MatrixGraph;
+export {};
+//# sourceMappingURL=matrix.d.ts.map

package/dist/report/matrix.d.ts.map

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