@volter/twin-standard 1.0.0

package/src/spec-patches.ts

@@ -0,0 +1,23 @@
+// A pack's corrections to its vendor's spec (spec/patches.json): RFC 6902 operations (add, replace, remove, move, copy),
+// applied to the parsed spec so the vendored file stays the vendor's own bytes. derive-pack.ts applies them before the
+// IR; vendor-examples.ts reads the patched schemas, which are what the twin is derived from.
+
+export type SpecPatch = { op: string; path: string; from?: string; value?: unknown };
+
+/** Apply one patch to `doc` in place. */
+export function applySpecPatch(doc: unknown, p: SpecPatch): void {
+  const at = (pointer: string): { parent: any; key: string } => {
+    const keys = pointer.split('/').slice(1).map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~'));
+    const key = keys.pop()!;
+    return { parent: keys.reduce((node: any, k) => node[k], doc), key };
+  };
+  const read = (pointer: string): unknown => { const { parent, key } = at(pointer); return parent[key]; };
+  const value = p.op === 'move' || p.op === 'copy' ? structuredClone(read(p.from!)) : p.value;
+  const drop = ({ parent, key }: { parent: any; key: string }) => (Array.isArray(parent) ? parent.splice(Number(key), 1) : delete parent[key]);
+  if (p.op === 'move') drop(at(p.from!));
+  const { parent, key } = at(p.path);
+  if (p.op === 'remove') drop({ parent, key });
+  // into an array, `add` inserts at the index (`-` appends) and `replace` overwrites it
+  else if (Array.isArray(parent) && p.op !== 'replace') parent.splice(key === '-' ? parent.length : Number(key), 0, value);
+  else parent[key] = value;
+}

package/src/spec.ts

@@ -0,0 +1,8 @@
+// The spec side of the standard, for a tool that reads a vendor's spec as the derivation does (a vendor's published
+// examples replayed, a client's calls extracted): the spec IR, a Discovery document as OpenAPI, several documents as one
+// API, and a recorded patch applied.
+export { CRUD_CLASSES, fromOpenAPI, fromSmithy, fromSwagger2, slug, type SpecIR } from './spec-ir.ts';
+export { discoveryToOpenAPI, fromDiscovery, isDiscovery } from './spec-ir-discovery.ts';
+export type { ClientCall, ClientOpsSpec } from './spec-ir-client.ts';
+export { mergeDocuments, readSpecDocuments, type SpecDocuments } from './spec-documents.ts';
+export { applySpecPatch, type SpecPatch } from './spec-patches.ts';

package/src/types.ts

@@ -0,0 +1,53 @@
+// A standard the grader grades against (docs/contributing/architecture.md, "The grade"): its id and version, and
+// its criteria, unweighted (a grade is criteria met over criteria). The grader is one engine (./grade.ts); a new
+// protocol, or a revision of one, is another module beside this, released as a version of this package.
+
+/** What a criterion is checked against: one unit (a pack, or one lane of a multi-API pack), read from the tree. */
+export interface GradeUnit {
+  /** `stripe`, or a lane `aws/secretsmanager` */
+  name: string;
+  /** the vendor (the pack directory's name) */
+  vendor: string;
+  /** absolute path of the unit's directory */
+  dir: string;
+  /** score-pack's report for the unit, recomputed now (null when the unit has no customer life to walk) */
+  report: ScoreReport | null;
+  /** why the walk gave no report although the unit has a life (a crash, a timeout), else undefined */
+  walkError?: string;
+}
+
+export interface ScoreReport {
+  vendor: string;
+  life: { steps: number; verdict: string; judge: string | null; authors: string[] };
+  failures: Array<{ step: string; beat: string; detail: string }>;
+  flags: Array<{ pattern: string; step: string; detail: string }>;
+  coverage: { missing: number; code: { lines: number; run: number; recorded: number; missing: number }; state?: unknown } | null;
+  examples: { done: boolean; replayed?: boolean; verdict?: string; line: string };
+  breadth: { operations: number; [servedBy: string]: number };
+  missingForDone: string[];
+}
+
+export interface CriterionResult {
+  pass: boolean;
+  /** why it failed, or what it measured when it passed */
+  reason: string;
+}
+
+export interface Criterion {
+  id: string;
+  section: 'form' | 'proof' | 'soundness';
+  /** it runs the pack (typecheck, tests), so its result can vary with the machine; the rest read the tree */
+  executed?: boolean;
+  /** what it asks, in one line, for the catalog */
+  asks: string;
+  check(unit: GradeUnit): CriterionResult | Promise<CriterionResult>;
+}
+
+export interface Standard {
+  id: string;
+  version: number;
+  title: string;
+  criteria: Criterion[];
+  /** criteria the standard names that no tool decides yet: shown, counted in no grade */
+  planned: string[];
+}

package/src/unit.ts

@@ -0,0 +1,15 @@
+// A unit the standard grades, named from its directory (docs/contributing/architecture.md, "The catalog: where twins come
+// from": the standard takes a pack's directory, in any repository, or an unpacked published tarball): a pack is its
+// directory's name, and a lane keeps its vendor (`cloudflare/r2`).
+import { existsSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+
+/** The unit at `path`: its absolute directory and the name it is reported by. */
+export function unitAt(path: string): { dir: string; name: string } {
+  const dir = resolve(path.replace(/^~/, process.env.HOME ?? '~'));
+  // a lane is a unit under its vendor's package: it has no package.json of its own, its vendor's directory does (a pack
+  // has its own, whatever its parent holds: a pack repository's root is a workspace)
+  const parent = resolve(dir, '..');
+  const lane = !existsSync(join(dir, 'package.json')) && existsSync(join(parent, 'package.json')) && existsSync(join(dir, 'spec'));
+  return { dir, name: lane ? `${basename(parent)}/${basename(dir)}` : basename(dir) };
+}