@spfn/core 0.2.0-beta.8 → 0.3.0-beta.1

package/dist/contract/index.js

@@ -0,0 +1,558 @@
+import { createHash } from 'crypto';
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, statSync } from 'fs';
+import { join } from 'path';
+
+// src/contract/collect.ts
+var ContractCollectionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractCollectionError";
+  }
+};
+function isRouter(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function isRouteDef(value) {
+  return value !== null && typeof value === "object" && "handler" in value;
+}
+function toJsonSchema(schema) {
+  return JSON.parse(JSON.stringify(schema));
+}
+var REQUEST_SECTIONS = ["params", "query", "body", "headers", "cookies"];
+function toContractRequest(input) {
+  const request = {};
+  if (!input) {
+    return request;
+  }
+  for (const section of REQUEST_SECTIONS) {
+    const schema = input[section];
+    if (schema) {
+      request[section] = toJsonSchema(schema);
+    }
+  }
+  return request;
+}
+function visitRouter(router, trail, found) {
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      visitRouter(entry, [...trail, name], found);
+      continue;
+    }
+    if (!isRouteDef(entry)) {
+      continue;
+    }
+    const routeDef = entry;
+    if (!routeDef.contract) {
+      continue;
+    }
+    addOperation(name, routeDef, [...trail, name], found);
+  }
+  for (const packageRouter of router._packageRouters ?? []) {
+    visitRouter(packageRouter, [...trail, "(package)"], found);
+  }
+}
+function assertNoFormData(where, routeDef) {
+  const input = routeDef.input;
+  const interceptor = routeDef.interceptor;
+  const section = input?.formData ? "input" : interceptor?.formData ? "interceptor" : void 0;
+  if (!section) {
+    return;
+  }
+  throw new ContractCollectionError(
+    `Contracted route "${where}" declares ${section}.formData, which a contract cannot describe. The contract grammar covers JSON values, and multipart carries file parts that have no spelling in it. Drop .contract() from this route, or move the operation to a JSON body.`
+  );
+}
+function addOperation(name, routeDef, trail, found) {
+  const where = trail.join(".");
+  const contract = routeDef.contract;
+  assertNoFormData(where, routeDef);
+  if (!routeDef.method || !routeDef.path) {
+    throw new ContractCollectionError(
+      `Contracted route "${where}" has no method or path. A contract describes an operation on the wire, so both are required.`
+    );
+  }
+  if (!contract.since) {
+    throw new ContractCollectionError(
+      `Contracted route "${where}" has no "since" version. The version an operation first appeared in is part of the promise.`
+    );
+  }
+  if (!contract.response) {
+    throw new ContractCollectionError(
+      `Contracted route "${where}" declares no response schema. An operation with no body declares Type.Null().`
+    );
+  }
+  const existing = found.get(name);
+  if (existing) {
+    throw new ContractCollectionError(
+      `Two contracted routes are both named "${name}" (${existing.trail} and ${where}). An operation is identified by its name across versions, so names must be unique.`
+    );
+  }
+  found.set(name, {
+    trail: where,
+    operation: {
+      name,
+      method: routeDef.method,
+      path: routeDef.path,
+      since: contract.since,
+      auth: contract.auth ?? "none",
+      requiresSession: contract.requiresSession ?? false,
+      ...contract.deprecatedIn ? { deprecatedIn: contract.deprecatedIn } : {},
+      ...contract.removedIn ? { removedIn: contract.removedIn } : {},
+      request: toContractRequest(routeDef.input),
+      interceptor: toContractRequest(routeDef.interceptor),
+      response: toJsonSchema(contract.response)
+    }
+  });
+}
+function collectContractDocument(router) {
+  const found = /* @__PURE__ */ new Map();
+  visitRouter(router, ["router"], found);
+  const operations = [...found.values()].map((entry) => entry.operation).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  return {
+    documentVersion: 1,
+    ...router._contractVersion ? { contractVersion: router._contractVersion } : {},
+    compatibilityPolicy: "perOperation",
+    operations
+  };
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const source = value;
+  const sorted = {};
+  for (const key of Object.keys(source).sort()) {
+    if (source[key] === void 0) {
+      continue;
+    }
+    sorted[key] = canonicalize(source[key]);
+  }
+  return sorted;
+}
+function stableStringify(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function stableStringifyPretty(value) {
+  return `${JSON.stringify(canonicalize(value), null, 4)}
+`;
+}
+function stableDigest(value) {
+  return createHash("sha256").update(stableStringify(value), "utf8").digest("hex");
+}
+
+// src/contract/compare.ts
+var REQUEST_SECTIONS2 = ["params", "query", "body", "formData", "headers", "cookies"];
+function leafSignature(schema) {
+  const { properties, required, items, ...rest } = schema;
+  return stableStringify(rest);
+}
+function propertiesOf(schema) {
+  const properties = schema.properties;
+  if (!properties || typeof properties !== "object") {
+    return {};
+  }
+  return properties;
+}
+function requiredOf(schema) {
+  const required = schema.required;
+  if (!Array.isArray(required)) {
+    return /* @__PURE__ */ new Set();
+  }
+  return new Set(required.filter((name) => typeof name === "string"));
+}
+function requiresClientToSend(schema) {
+  if (schema.type !== "object") {
+    return true;
+  }
+  return requiredOf(schema).size > 0;
+}
+function report(ctx, kind, location, detail) {
+  ctx.violations.push({ kind, operation: ctx.operation, location, detail });
+}
+function compareSchema(before, after, location, ctx) {
+  if (!before && !after) {
+    return;
+  }
+  if (before && !after) {
+    if (ctx.side === "response") {
+      report(ctx, "response.field-removed", location, "the response no longer carries this, and old clients read it");
+    }
+    return;
+  }
+  if (!before && after) {
+    if (ctx.side === "request" && requiresClientToSend(after)) {
+      report(
+        ctx,
+        "request.required-field-added",
+        location,
+        "this is new and mandatory, so every already-released client is refused"
+      );
+    }
+    return;
+  }
+  const from = before;
+  const to = after;
+  if (leafSignature(from) !== leafSignature(to)) {
+    report(
+      ctx,
+      ctx.side === "request" ? "request.type-changed" : "response.type-changed",
+      location,
+      `the declared type changed: ${leafSignature(from)} \u2192 ${leafSignature(to)}`
+    );
+    return;
+  }
+  compareProperties(from, to, location, ctx);
+  compareSchema(
+    from.items,
+    to.items,
+    `${location}[]`,
+    ctx
+  );
+}
+function compareProperties(from, to, location, ctx) {
+  const beforeProperties = propertiesOf(from);
+  const afterProperties = propertiesOf(to);
+  const beforeRequired = requiredOf(from);
+  const afterRequired = requiredOf(to);
+  for (const [name, beforeSchema] of Object.entries(beforeProperties)) {
+    const where = `${location}.${name}`;
+    const afterSchema = afterProperties[name];
+    compareSchema(beforeSchema, afterSchema, where, ctx);
+    if (!afterSchema) {
+      continue;
+    }
+    const wasRequired = beforeRequired.has(name);
+    const isRequired = afterRequired.has(name);
+    if (ctx.side === "request" && !wasRequired && isRequired) {
+      report(ctx, "request.field-became-required", where, "clients that never sent this are now refused");
+    }
+    if (ctx.side === "response" && wasRequired && !isRequired) {
+      report(ctx, "response.field-became-optional", where, "clients that counted on this always arriving now break");
+    }
+  }
+  for (const name of Object.keys(afterProperties)) {
+    if (beforeProperties[name]) {
+      continue;
+    }
+    if (ctx.side === "request" && afterRequired.has(name)) {
+      report(
+        ctx,
+        "request.required-field-added",
+        `${location}.${name}`,
+        "this is new and mandatory, so every already-released client is refused"
+      );
+    }
+  }
+}
+function compareRequestSections(before, after, prefix, ctx) {
+  for (const section of REQUEST_SECTIONS2) {
+    compareSchema(before[section], after[section], `${prefix}.${section}`, ctx);
+  }
+}
+function compareOperation(before, after) {
+  const violations = [];
+  if (before.path !== after.path) {
+    violations.push({
+      kind: "operation.path-changed",
+      operation: before.name,
+      detail: `path moved ${before.path} \u2192 ${after.path}; released clients call the old one`
+    });
+  }
+  if (before.method !== after.method) {
+    violations.push({
+      kind: "operation.method-changed",
+      operation: before.name,
+      detail: `method changed ${before.method} \u2192 ${after.method}; released clients send the old one`
+    });
+  }
+  const requestCtx = { operation: before.name, side: "request", violations };
+  compareRequestSections(before.request, after.request, "request", requestCtx);
+  compareRequestSections(before.interceptor, after.interceptor, "interceptor", requestCtx);
+  compareSchema(
+    before.response,
+    after.response,
+    "response",
+    { operation: before.name, side: "response", violations }
+  );
+  return violations;
+}
+function compareDocuments(before, after) {
+  const current = new Map(after.operations.map((operation) => [operation.name, operation]));
+  const violations = [];
+  const removedOperations = [];
+  for (const operation of before.operations) {
+    const now = current.get(operation.name);
+    if (!now) {
+      removedOperations.push(operation.name);
+      continue;
+    }
+    violations.push(...compareOperation(operation, now));
+  }
+  return { violations, removedOperations };
+}
+var ContractSnapshotError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractSnapshotError";
+  }
+};
+var CURRENT_FILENAME = "current.json";
+var RELEASED_DIRNAME = "released";
+var USAGE_DIRNAME = "usage";
+function currentPath(contractsDir) {
+  return join(contractsDir, CURRENT_FILENAME);
+}
+function releasedDir(contractsDir) {
+  return join(contractsDir, RELEASED_DIRNAME);
+}
+function usageDir(contractsDir) {
+  return join(contractsDir, USAGE_DIRNAME);
+}
+function compareVersions(a, b) {
+  const [aCore, aPre] = splitVersion(a);
+  const [bCore, bPre] = splitVersion(b);
+  for (let i = 0; i < 3; i++) {
+    if (aCore[i] !== bCore[i]) {
+      return aCore[i] - bCore[i];
+    }
+  }
+  if (aPre === bPre) {
+    return 0;
+  }
+  if (aPre === void 0) {
+    return 1;
+  }
+  if (bPre === void 0) {
+    return -1;
+  }
+  return comparePreRelease(aPre, bPre);
+}
+function splitVersion(version) {
+  const [core, ...rest] = version.split("-");
+  const parts = core.split(".").map((part) => Number.parseInt(part, 10));
+  if (parts.length !== 3 || parts.some((part) => !Number.isInteger(part) || part < 0)) {
+    throw new ContractSnapshotError(`"${version}" is not a version of the form major.minor.patch`);
+  }
+  return [parts, rest.length > 0 ? rest.join("-") : void 0];
+}
+function comparePreRelease(a, b) {
+  const aParts = a.split(".");
+  const bParts = b.split(".");
+  for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+    const left = aParts[i];
+    const right = bParts[i];
+    if (left === void 0) {
+      return -1;
+    }
+    if (right === void 0) {
+      return 1;
+    }
+    if (left === right) {
+      continue;
+    }
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+      return Number(left) - Number(right);
+    }
+    if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    }
+    return left < right ? -1 : 1;
+  }
+  return 0;
+}
+function listSnapshots(contractsDir) {
+  const dir = releasedDir(contractsDir);
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir).filter((name) => name.endsWith(".json")).map((name) => ({ version: name.slice(0, -".json".length), file: join(dir, name) })).sort((a, b) => compareVersions(a.version, b.version));
+}
+function newestSnapshot(contractsDir) {
+  const snapshots = listSnapshots(contractsDir);
+  return snapshots[snapshots.length - 1];
+}
+function readSnapshot(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ContractSnapshotError(`${file} could not be read: ${message}`);
+  }
+  if (typeof parsed.version !== "string" || typeof parsed.sha256 !== "string" || !parsed.document) {
+    throw new ContractSnapshotError(`${file} is not a contract snapshot: expected version, sha256 and document`);
+  }
+  const digest = stableDigest(parsed.document);
+  if (digest !== parsed.sha256) {
+    throw new ContractSnapshotError(
+      `${file} was edited after release: it records sha256 ${parsed.sha256} but its document hashes to ${digest}`
+    );
+  }
+  return { version: parsed.version, sha256: parsed.sha256, document: parsed.document };
+}
+function writeSnapshot(contractsDir, document) {
+  const version = document.contractVersion;
+  if (!version) {
+    throw new ContractSnapshotError(
+      'The contract declares no version, so a release cannot be named. Add .contractVersion("x.y.z") to the router before cutting one.'
+    );
+  }
+  compareVersions(version, version);
+  const dir = releasedDir(contractsDir);
+  const file = join(dir, `${version}.json`);
+  if (existsSync(file)) {
+    throw new ContractSnapshotError(
+      `${file} already exists. A released version's contract is never rewritten \u2014 cut a new version instead.`
+    );
+  }
+  const newest = newestSnapshot(contractsDir);
+  if (newest && compareVersions(version, newest.version) <= 0) {
+    throw new ContractSnapshotError(
+      `${version} is not newer than the released ${newest.version}. The gate compares against the newest snapshot, so filling one in behind it would never be checked.`
+    );
+  }
+  mkdirSync(dir, { recursive: true });
+  const snapshot = { version, sha256: stableDigest(document), document };
+  writeFileSync(file, stableStringifyPretty(snapshot), "utf-8");
+  return file;
+}
+function readCurrentDocument(contractsDir) {
+  const file = currentPath(contractsDir);
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ContractSnapshotError(
+      `${file} could not be read: ${message}. Run the @spfn/core:contract generator first.`
+    );
+  }
+}
+function writeCurrentDocument(contractsDir, document) {
+  const file = currentPath(contractsDir);
+  const content = stableStringifyPretty(document);
+  const existing = existsSync(file) ? readFileSync(file, "utf-8") : void 0;
+  if (existing === content) {
+    return false;
+  }
+  mkdirSync(contractsDir, { recursive: true });
+  writeFileSync(file, content, "utf-8");
+  return true;
+}
+function parseRecord(file, raw) {
+  const parsed = JSON.parse(raw);
+  if (typeof parsed.platform !== "string" || parsed.platform.length === 0) {
+    throw new Error('"platform" must be a non-empty string');
+  }
+  if (typeof parsed.appVersion !== "string" || parsed.appVersion.length === 0) {
+    throw new Error('"appVersion" must be a non-empty string');
+  }
+  if (!Array.isArray(parsed.operations) || parsed.operations.some((name) => typeof name !== "string")) {
+    throw new Error('"operations" must be an array of operation names');
+  }
+  return {
+    platform: parsed.platform,
+    appVersion: parsed.appVersion,
+    operations: parsed.operations,
+    file
+  };
+}
+function readUsageRecords(usageDir2) {
+  let entries;
+  try {
+    if (!statSync(usageDir2).isDirectory()) {
+      return { decidable: false, reason: `${usageDir2} is not a directory` };
+    }
+    entries = readdirSync(usageDir2).filter((name) => name.endsWith(".json")).sort();
+  } catch {
+    return { decidable: false, reason: `${usageDir2} does not exist` };
+  }
+  if (entries.length === 0) {
+    return { decidable: false, reason: `${usageDir2} holds no usage file` };
+  }
+  const records = [];
+  for (const entry of entries) {
+    const file = join(usageDir2, entry);
+    try {
+      records.push(parseRecord(file, readFileSync(file, "utf-8")));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { decidable: false, reason: `${file} could not be read: ${message}` };
+    }
+  }
+  return { decidable: true, records };
+}
+function callersOf(operation, records) {
+  return records.filter((record) => record.operations.includes(operation));
+}
+
+// src/contract/check.ts
+function checkContract(contractsDir, current) {
+  const baseline = newestSnapshot(contractsDir);
+  if (!baseline) {
+    return {
+      violations: [],
+      warnings: [
+        "No released contract snapshot found, so nothing was compared. This is expected for a first contract, and a mistake if a release forgot to write one."
+      ]
+    };
+  }
+  let previous;
+  try {
+    previous = readSnapshot(baseline.file).document;
+  } catch (error) {
+    return {
+      baselineVersion: baseline.version,
+      warnings: [],
+      violations: [{
+        kind: "snapshot.digest-mismatch",
+        detail: error instanceof Error ? error.message : String(error)
+      }]
+    };
+  }
+  const { violations, removedOperations } = compareDocuments(previous, current);
+  return {
+    baselineVersion: baseline.version,
+    warnings: [],
+    violations: [...violations, ...judgeRemovals(contractsDir, removedOperations)]
+  };
+}
+function judgeRemovals(contractsDir, removedOperations) {
+  if (removedOperations.length === 0) {
+    return [];
+  }
+  const usage = readUsageRecords(usageDir(contractsDir));
+  if (!usage.decidable) {
+    return [{
+      kind: "usage.undecidable",
+      detail: `${removedOperations.join(", ")} would be removed, but no released client's call list could be read (${usage.reason}). Not knowing who calls an operation is not the same as knowing nobody does.`
+    }];
+  }
+  const violations = [];
+  for (const operation of removedOperations) {
+    const callers = callersOf(operation, usage.records);
+    if (callers.length === 0) {
+      continue;
+    }
+    violations.push({
+      kind: "usage.still-called",
+      operation,
+      detail: "still called by " + callers.map((caller) => `${caller.platform} ${caller.appVersion}`).join(", ")
+    });
+  }
+  return violations;
+}
+function formatViolations(violations) {
+  return violations.map((violation) => {
+    const where = [violation.operation, violation.location].filter(Boolean).join(" ");
+    return `  - [${violation.kind}]${where ? ` ${where}` : ""}: ${violation.detail}`;
+  }).join("\n");
+}
+
+export { CURRENT_FILENAME, ContractCollectionError, ContractSnapshotError, RELEASED_DIRNAME, USAGE_DIRNAME, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, usageDir, writeCurrentDocument, writeSnapshot };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map