@opensoftware/contracts 0.0.0-stage → 1.0.0

package/dist/roundtrip.js

@@ -0,0 +1,89 @@
+// `osf-contracts roundtrip --client <client> [dir]`: every valid fixture under dir is loaded by a generated client
+// and written back; the result must equal the fixture. TypeScript is the only client (ADR 0012); the flag leaves
+// room for another one.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
+import { FORMATS } from "./formats.js";
+import { validate } from "./index.js";
+export const CLIENTS = ["typescript"];
+export function roundtrip(_client, dir) {
+    const fixtures = validFixtures(dir);
+    if (fixtures.length === 0) {
+        process.stderr.write(`No valid fixtures under ${dir}/<format>/fixtures/valid/\n`);
+        return 1;
+    }
+    let written;
+    try {
+        written = viaTypeScript(fixtures);
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n`);
+        return 1;
+    }
+    let changed = 0;
+    for (const { file } of fixtures) {
+        const original = JSON.parse(readFileSync(file, "utf8"));
+        const difference = written.has(file) ? firstDifference(original, written.get(file), "") : "not written back";
+        if (difference === undefined) {
+            process.stdout.write(`${file}: unchanged\n`);
+        }
+        else {
+            changed++;
+            process.stdout.write(`${file}: changed at ${difference}\n`);
+        }
+    }
+    return changed === 0 ? 0 : 1;
+}
+function validFixtures(dir) {
+    const out = [];
+    for (const format of FORMATS) {
+        const folder = join(dir, format.path, "fixtures", "valid");
+        if (!existsSync(folder) || !statSync(folder).isDirectory())
+            continue;
+        for (const entry of readdirSync(folder).sort()) {
+            if (entry.endsWith(".json"))
+                out.push({ file: join(folder, entry).split(sep).join("/"), format });
+        }
+    }
+    return out;
+}
+/** The TypeScript side: validate, then serialize the typed value again. */
+function viaTypeScript(fixtures) {
+    const out = new Map();
+    for (const { file, format } of fixtures) {
+        const document = JSON.parse(readFileSync(file, "utf8"));
+        const problems = validate(format, document);
+        if (problems.length > 0)
+            throw new Error(`${file} does not match ${format.name}: ${problems[0]?.path} ${problems[0]?.message}`);
+        out.set(file, JSON.parse(JSON.stringify(document)));
+    }
+    return out;
+}
+/** JSON Pointer and values of the first difference; numbers compare by value, so 4 equals 4.0. */
+function firstDifference(a, b, path) {
+    if (typeof a === "number" && typeof b === "number")
+        return a === b ? undefined : `${path || "/"}: ${a} → ${b}`;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return `${path || "/"}: ${a.length} items → ${b.length} items`;
+        for (let index = 0; index < a.length; index++) {
+            const found = firstDifference(a[index], b[index], `${path}/${index}`);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+        const left = a;
+        const right = b;
+        for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) {
+            const found = firstDifference(left[key], right[key], `${path}/${key}`);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    return JSON.stringify(a) === JSON.stringify(b)
+        ? undefined
+        : `${path || "/"}: ${JSON.stringify(a)} → ${JSON.stringify(b)}`;
+}

package/events/asyncapi.yaml

@@ -0,0 +1,144 @@
+# Events between modules (ADR 0006). Hand-written: TypeSpec has no maintained AsyncAPI emitter, so the
+# payloads are the JSON Schemas that `pnpm build` emits from typespec/events.tsp. Every message is a CloudEvents
+# 1.0 event in structured JSON mode; its `type` is the versioned name, for example "work.received@v1".
+asyncapi: 3.1.0
+info:
+  title: Open Software Factory events
+  version: 0.0.0
+  description: Facts that modules publish and others react to. Past tense, versioned, at-least-once.
+defaultContentType: application/cloudevents+json
+servers:
+  nats:
+    host: localhost:4222
+    protocol: nats
+    description: NATS JetStream (ADR 0003). Without a bus the same JSON is posted to webhooks.
+channels:
+  work-received:
+    address: osf.work.received.v1
+    description: A work item was accepted. `data` is a work item.
+    messages:
+      WorkReceived:
+        $ref: '#/components/messages/WorkReceived'
+  run-completed:
+    address: osf.run.completed.v1
+    description: A run ended.
+    messages:
+      RunCompleted:
+        $ref: '#/components/messages/RunCompleted'
+  gate-requested:
+    address: osf.gate.requested.v1
+    description: A stage waits for a decision.
+    messages:
+      GateRequested:
+        $ref: '#/components/messages/GateRequested'
+  gate-decided:
+    address: osf.gate.decided.v1
+    description: A gate was approved, rejected or expired.
+    messages:
+      GateDecided:
+        $ref: '#/components/messages/GateDecided'
+  score-recorded:
+    address: osf.score.recorded.v1
+    description: A scorer scored a run. `data` is a score.
+    messages:
+      ScoreRecorded:
+        $ref: '#/components/messages/ScoreRecorded'
+  pr-opened:
+    address: osf.pr.opened.v1
+    description: The factory opened a pull request.
+    messages:
+      PrOpened:
+        $ref: '#/components/messages/PrOpened'
+operations:
+  publishWorkReceived:
+    action: send
+    summary: Published by intake.
+    channel:
+      $ref: '#/channels/work-received'
+    messages:
+      - $ref: '#/channels/work-received/messages/WorkReceived'
+  publishRunCompleted:
+    action: send
+    summary: Published by foreman.
+    channel:
+      $ref: '#/channels/run-completed'
+    messages:
+      - $ref: '#/channels/run-completed/messages/RunCompleted'
+  publishGateRequested:
+    action: send
+    summary: Published by gatekeeper.
+    channel:
+      $ref: '#/channels/gate-requested'
+    messages:
+      - $ref: '#/channels/gate-requested/messages/GateRequested'
+  publishGateDecided:
+    action: send
+    summary: Published by gatekeeper.
+    channel:
+      $ref: '#/channels/gate-decided'
+    messages:
+      - $ref: '#/channels/gate-decided/messages/GateDecided'
+  publishScoreRecorded:
+    action: send
+    summary: Published by scorekit.
+    channel:
+      $ref: '#/channels/score-recorded'
+    messages:
+      - $ref: '#/channels/score-recorded/messages/ScoreRecorded'
+  publishPrOpened:
+    action: send
+    summary: Published by forge adapters.
+    channel:
+      $ref: '#/channels/pr-opened'
+    messages:
+      - $ref: '#/channels/pr-opened/messages/PrOpened'
+components:
+  messages:
+    WorkReceived:
+      name: work.received@v1
+      title: work.received@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './work-received/work-received.schema.json'
+    RunCompleted:
+      name: run.completed@v1
+      title: run.completed@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './run-completed/run-completed.schema.json'
+    GateRequested:
+      name: gate.requested@v1
+      title: gate.requested@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './gate-requested/gate-requested.schema.json'
+    GateDecided:
+      name: gate.decided@v1
+      title: gate.decided@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './gate-decided/gate-decided.schema.json'
+    ScoreRecorded:
+      name: score.recorded@v1
+      title: score.recorded@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './score-recorded/score-recorded.schema.json'
+    PrOpened:
+      name: pr.opened@v1
+      title: pr.opened@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './pr-opened/pr-opened.schema.json'

package/events/gate-decided/gate-decided.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/events/gate-decided/gate-decided.schema.json",
+  "title": "GateDecided",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "specversion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The producing module, for example \"/osf/intake\"."
+    },
+    "type": {
+      "type": "string",
+      "const": "gate.decided@v1"
+    },
+    "time": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "subject": {
+      "type": "string",
+      "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+    },
+    "datacontenttype": {
+      "type": "string",
+      "const": "application/json"
+    },
+    "dataschema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "traceparent": {
+      "type": "string",
+      "description": "W3C trace context (CloudEvents distributed tracing extension)."
+    },
+    "data": {
+      "type": "object",
+      "properties": {
+        "gateId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "workItemId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "decision": {
+          "type": "string",
+          "enum": [
+            "approved",
+            "rejected",
+            "expired"
+          ]
+        },
+        "decidedBy": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "person",
+                "trigger"
+              ],
+              "description": "Who caused something: a person, or an automated trigger such as a cron rule or an alert."
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Stable ID in the source system, prefixed with the source, for example \"slack:U024BE7LH\"."
+            },
+            "displayName": {
+              "type": "string",
+              "description": "Shown to people, for example \"Varun\"."
+            }
+          },
+          "required": [
+            "kind",
+            "id"
+          ],
+          "description": "The person who decided. Absent only when the gate expired."
+        },
+        "decidedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "reason": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "gateId",
+        "workItemId",
+        "decision",
+        "decidedAt"
+      ]
+    }
+  },
+  "required": [
+    "specversion",
+    "id",
+    "source",
+    "type",
+    "time",
+    "data"
+  ],
+  "description": "gatekeeper: a gate was decided."
+}

package/events/gate-requested/gate-requested.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/events/gate-requested/gate-requested.schema.json",
+  "title": "GateRequested",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "specversion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The producing module, for example \"/osf/intake\"."
+    },
+    "type": {
+      "type": "string",
+      "const": "gate.requested@v1"
+    },
+    "time": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "subject": {
+      "type": "string",
+      "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+    },
+    "datacontenttype": {
+      "type": "string",
+      "const": "application/json"
+    },
+    "dataschema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "traceparent": {
+      "type": "string",
+      "description": "W3C trace context (CloudEvents distributed tracing extension)."
+    },
+    "data": {
+      "type": "object",
+      "properties": {
+        "gateId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "workItemId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "runId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "stage": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "The stage that waits."
+        },
+        "policy": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to the policy in the factory definition."
+        },
+        "approvers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,62}$",
+            "description": "A lowercase name: letters, digits and hyphens, starting with a letter. Agents, stages, adapters, sources."
+          },
+          "minItems": 1,
+          "description": "Approver groups picked by the policy."
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What the approver is asked to decide, shown in the channel."
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string",
+                "format": "uri"
+              },
+              "title": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url"
+            ]
+          }
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": [
+        "gateId",
+        "workItemId",
+        "stage",
+        "policy",
+        "approvers",
+        "summary"
+      ]
+    }
+  },
+  "required": [
+    "specversion",
+    "id",
+    "source",
+    "type",
+    "time",
+    "data"
+  ],
+  "description": "gatekeeper: a decision is needed before a stage starts."
+}

package/events/pr-opened/pr-opened.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/events/pr-opened/pr-opened.schema.json",
+  "title": "PrOpened",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "specversion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The producing module, for example \"/osf/intake\"."
+    },
+    "type": {
+      "type": "string",
+      "const": "pr.opened@v1"
+    },
+    "time": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "subject": {
+      "type": "string",
+      "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+    },
+    "datacontenttype": {
+      "type": "string",
+      "const": "application/json"
+    },
+    "dataschema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "traceparent": {
+      "type": "string",
+      "description": "W3C trace context (CloudEvents distributed tracing extension)."
+    },
+    "data": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "repository": {
+          "type": "string",
+          "format": "uri"
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "headBranch": {
+          "type": "string"
+        },
+        "baseBranch": {
+          "type": "string"
+        },
+        "headCommit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$",
+          "description": "A Git commit hash, abbreviated (7+) or full. The factory version is the commit of the factory definition."
+        },
+        "author": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "person",
+                "trigger"
+              ],
+              "description": "Who caused something: a person, or an automated trigger such as a cron rule or an alert."
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Stable ID in the source system, prefixed with the source, for example \"slack:U024BE7LH\"."
+            },
+            "displayName": {
+              "type": "string",
+              "description": "Shown to people, for example \"Varun\"."
+            }
+          },
+          "required": [
+            "kind",
+            "id"
+          ],
+          "description": "A person or trigger. RUNTIME-008: every run is attributed to one."
+        },
+        "workItemId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "runId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        }
+      },
+      "required": [
+        "url",
+        "repository",
+        "number",
+        "title",
+        "headBranch",
+        "baseBranch",
+        "headCommit",
+        "author"
+      ]
+    }
+  },
+  "required": [
+    "specversion",
+    "id",
+    "source",
+    "type",
+    "time",
+    "data"
+  ],
+  "description": "forge adapters: the factory opened a pull request."
+}