@opensoftware/contracts 0.0.0-stage → 1.4.0

package/dist/index.js

@@ -0,0 +1,75 @@
+// @opensoftware/contracts: the types of the shared formats and a validator for each. Modules import only from here.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020, {} from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { formatNamed } from "./formats.js";
+export { diff as breakingChanges } from "./breaking.js";
+export { FORMATS, formatNamed } from "./formats.js";
+export { runSpans } from "./run-record.js";
+/** The package root: dist/ and src/ both sit one level below it, next to the schema folders. */
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const validators = new Map();
+/** The JSON Schema of a format, as published in `<path>/<name>.schema.json`. */
+export function schemaOf(format) {
+    const found = typeof format === "string" ? formatNamed(format) : format;
+    if (!found)
+        throw new Error(`Unknown format: ${String(format)}`);
+    return JSON.parse(readFileSync(join(ROOT, found.path, `${found.name}.schema.json`), "utf8"));
+}
+/** Every problem of the document; empty when it matches the format. */
+export function validate(format, document) {
+    const name = typeof format === "string" ? format : format.name;
+    let check = validators.get(name);
+    if (!check) {
+        // strictRequired is off: "exactly one of" rules use `not: { required: [...] }` on purpose.
+        const ajv = new Ajv2020.default({ allErrors: true, strict: true, strictRequired: false });
+        addFormats.default(ajv);
+        check = ajv.compile(schemaOf(format));
+        validators.set(name, check);
+    }
+    return check(document) ? [] : problems(check.errors ?? []);
+}
+/** True when the document matches the format, with its type narrowed. */
+export function isValid(format, document) {
+    return validate(format, document).length === 0;
+}
+const ALTERNATIVES = new Set(["anyOf", "oneOf"]);
+/** Ajv errors as one line per problem; the branches of a failed `anyOf` or `oneOf` collapse into one problem. */
+function problems(errors) {
+    const alternatives = errors.filter((error) => ALTERNATIVES.has(error.keyword)).map((error) => error.instancePath);
+    const insideAlternative = (error) => !ALTERNATIVES.has(error.keyword) &&
+        /\/(anyOf|oneOf)\//.test(error.schemaPath) &&
+        alternatives.some((path) => error.instancePath === path || error.instancePath.startsWith(`${path}/`));
+    const seen = new Set();
+    const out = [];
+    for (const error of errors) {
+        if (insideAlternative(error))
+            continue;
+        const problem = describe(error);
+        const key = `${problem.path} ${problem.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(problem);
+    }
+    return out;
+}
+function describe(error) {
+    const child = (name) => `${error.instancePath}/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+    switch (error.keyword) {
+        case "additionalProperties":
+            return { path: child(String(error.params.additionalProperty)), message: "unknown field" };
+        case "unevaluatedProperties":
+            return { path: child(String(error.params.unevaluatedProperty)), message: "unknown field" };
+        case "required":
+            return { path: child(String(error.params.missingProperty)), message: "missing required field" };
+        case "anyOf":
+        case "oneOf":
+            return { path: error.instancePath || "/", message: "must match exactly one of the allowed forms" };
+        default:
+            return { path: error.instancePath || "/", message: error.message ?? error.keyword };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/roundtrip.d.ts

@@ -0,0 +1,3 @@
+export declare const CLIENTS: readonly ["typescript"];
+export type Client = (typeof CLIENTS)[number];
+export declare function roundtrip(_client: Client, dir: string): number;

package/dist/roundtrip.js

@@ -0,0 +1,90 @@
+// `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)}`;
+}
+//# sourceMappingURL=roundtrip.js.map

package/dist/roundtrip.js.map

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

package/dist/run-record.d.ts

@@ -0,0 +1,18 @@
+/** An OTLP/JSON attribute value as runlog writes it: a string, an integer, a double or an array of them. */
+export type AttributeValue = string | number | AttributeValue[] | undefined;
+export type SpanAttributes = Record<string, AttributeValue>;
+/** One span of a run record, with its resource. */
+export interface RunSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | undefined;
+    name: string;
+    /** Unix time in nanoseconds; 0 when the span has none. */
+    start: bigint;
+    end: bigint;
+    /** The attributes of the span's resource, like `osf.run.id`. */
+    resource: SpanAttributes;
+    attributes: SpanAttributes;
+}
+/** The spans of a run record in the order they appear; undefined when the value is no OTLP/JSON trace export request. */
+export declare function runSpans(record: unknown): RunSpan[] | undefined;

package/dist/run-record.js

@@ -0,0 +1,27 @@
+// Reading run records: OTLP/JSON trace export requests with the run-record attributes, as runlog writes them.
+/** The spans of a run record in the order they appear; undefined when the value is no OTLP/JSON trace export request. */
+export function runSpans(record) {
+    const { resourceSpans } = (record ?? {});
+    if (!Array.isArray(resourceSpans))
+        return undefined;
+    return resourceSpans.flatMap((entry) => {
+        const resource = decode(entry.resource?.attributes);
+        return (entry.scopeSpans ?? []).flatMap((scope) => (scope.spans ?? []).map((span) => ({
+            traceId: span.traceId,
+            spanId: span.spanId,
+            parentSpanId: span.parentSpanId || undefined,
+            name: span.name ?? "",
+            start: BigInt(span.startTimeUnixNano ?? 0),
+            end: BigInt(span.endTimeUnixNano ?? 0),
+            resource,
+            attributes: decode(span.attributes),
+        })));
+    });
+}
+const value = (otlp) => {
+    if (otlp.arrayValue)
+        return (otlp.arrayValue.values ?? []).map(value);
+    return otlp.intValue === undefined ? (otlp.stringValue ?? otlp.doubleValue) : Number(otlp.intValue);
+};
+const decode = (list) => Object.fromEntries((list ?? []).map(({ key, value: entry }) => [key, value(entry)]));
+//# sourceMappingURL=run-record.js.map

package/dist/run-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.js","sourceRoot":"","sources":["../src/run-record.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAyC9G,yHAAyH;AACzH,MAAM,UAAU,QAAQ,CAAC,MAAe;IACtC,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAgC,CAAC;IACxE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,OAAQ,aAAqC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9D,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACpD,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAChD,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,SAAS;YAC5C,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;YACrB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,CAAC;YAC1C,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC;YACtC,QAAQ;YACR,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;SACpC,CAAC,CAAC,CACJ,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,IAAe,EAAkB,EAAE;IAChD,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACtG,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,CAAC,IAAoB,EAAkB,EAAE,CACtD,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/events/asyncapi.yaml

@@ -0,0 +1,186 @@
+# 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'
+  pr-reviewed:
+    address: osf.pr.reviewed.v1
+    description: A person, an agent or a bot reviewed or commented on a pull request.
+    messages:
+      PrReviewed:
+        $ref: '#/components/messages/PrReviewed'
+  pr-closed:
+    address: osf.pr.closed.v1
+    description: A pull request was merged or closed without a merge.
+    messages:
+      PrClosed:
+        $ref: '#/components/messages/PrClosed'
+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'
+  publishPrReviewed:
+    action: send
+    summary: Published by forge adapters.
+    channel:
+      $ref: '#/channels/pr-reviewed'
+    messages:
+      - $ref: '#/channels/pr-reviewed/messages/PrReviewed'
+  publishPrClosed:
+    action: send
+    summary: Published by forge adapters.
+    channel:
+      $ref: '#/channels/pr-closed'
+    messages:
+      - $ref: '#/channels/pr-closed/messages/PrClosed'
+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'
+    PrReviewed:
+      name: pr.reviewed@v1
+      title: pr.reviewed@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './pr-reviewed/pr-reviewed.schema.json'
+    PrClosed:
+      name: pr.closed@v1
+      title: pr.closed@v1
+      contentType: application/cloudevents+json
+      payload:
+        schemaFormat: application/schema+json;version=draft-2020-12
+        schema:
+          $ref: './pr-closed/pr-closed.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."
+}