@reventlessdev/reventless-spec 3.0.0-alpha.124 → 3.0.0-alpha.126

package/src/components/TraitCertificate.res

@@ -0,0 +1,105 @@
+/**
+What a trait's conformance suite proved, against one host, as data.
+
+The suite has run inside a consumer's build since the emitter shipped. What was
+missing is any way for something downstream to *read* the result: it was console
+output, so a listing could carry a claim nobody could check and a CI gate had
+nothing to gate on. This is that result, typed and versioned like every other
+persisted shape here.
+
+## What it is evidence of, and what it is not
+
+It says: this trait, at this version, asserted these rules through this host, and
+they held. It does **not** say the host is correct — the suite deliberately covers
+only what the trait has an opinion about, and the host's own lifecycle refusals,
+authorization and projections are asserted by the host's own tests and are none of
+the trait's business.
+
+So a listing that carries this can say "verified against its declared hosts" and
+cannot say "this application works". The distinction is the whole reason the
+assertion names travel with the counts: a reader can see *what* was proved rather
+than trusting a number.
+
+## Why the results come from a test report
+
+The framework does not own the runner. A consumer runs their own suite, their own
+way, and hands the report here — so this module is a pure transformation with no
+opinion about Jest, CI, or where files live. `fromReport` is the whole of it.
+*/
+
+/** One assertion, and whether it held. Named, not numbered: a count that changed
+    tells a reader nothing, and a name that disappeared tells them everything. */
+@schema
+type assertion = {name: string, passed: bool}
+
+@schema
+type t = {
+  /** The trait's package name — its identity everywhere else too. */
+  trait: string,
+  traitVersion: string,
+  /** The framework the suite ran against. A trait is certified against a
+      framework version, not in the abstract: `marketplace`'s Verified tier is
+      "passes its suite against the latest framework", and without this the claim
+      cannot be aged out. */
+  framework: string,
+  /** The bound host's component name — `Spec.name` from the binding. */
+  host: string,
+  /** The suite's own title, as the trait composes it. Carried so a reader can
+      find the run this came from without reconstructing the string. */
+  suite: string,
+  assertions: array<assertion>,
+  passed: int,
+  failed: int,
+}
+
+/**
+The badge rule, stated once.
+
+Every assertion held, and there was at least one. The second half matters more
+than it looks: a binding that registers nothing produces an empty, all-passing
+certificate, and "zero assertions, zero failures" is exactly the shape a broken
+graft takes. A certificate that called that verified would certify silence.
+*/
+let verified = (certificate: t) =>
+  certificate.failed == 0 && certificate.assertions->Array.length > 0
+
+/**
+Build a certificate from a suite's results.
+
+`results` is `(assertion name, passed)` in the order the suite registered them —
+whatever produced them. Counts are derived rather than passed in, so a caller
+cannot hand over a total that disagrees with the list it accompanies.
+*/
+let fromReport = (
+  ~trait: string,
+  ~traitVersion: string,
+  ~framework: string,
+  ~host: string,
+  ~suite: string,
+  ~results: array<(string, bool)>,
+): t => {
+  let assertions = results->Array.map(((name, passed)) => {name, passed})
+  {
+    trait,
+    traitVersion,
+    framework,
+    host,
+    suite,
+    assertions,
+    passed: assertions->Array.filter(a => a.passed)->Array.length,
+    failed: assertions->Array.filter(a => !a.passed)->Array.length,
+  }
+}
+
+/** Deterministic rendering: 2-space indent, trailing newline. Rebuilding from an
+    unchanged run must produce a byte-identical file, so a committed certificate
+    does not churn and a diff means something moved. */
+let render = (certificate: t): string =>
+  JSON.stringify(certificate->Util_Sury.toJson(schema), ~space=2) ++ "\n"
+
+/** A one-line summary for a build log — the counts plus the verdict, so a
+    console reader and a machine reader agree without either restating the rule. */
+let summarize = (certificate: t): string =>
+  `${certificate.trait}@${certificate.traitVersion} → ${certificate.host}: ` ++
+  `${certificate.passed->Int.toString}/${(certificate.assertions->Array.length)
+    ->Int.toString} assertions, ` ++ (certificate->verified ? "verified" : "NOT verified")

package/src/components/TraitCertificate.res.mjs

@@ -0,0 +1,65 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+
+let assertionSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  passed: s.m(Sury.bool)
+}));
+
+let schema = Sury.$schema(s => ({
+  trait: s.m(Sury.string),
+  traitVersion: s.m(Sury.string),
+  framework: s.m(Sury.string),
+  host: s.m(Sury.string),
+  suite: s.m(Sury.string),
+  assertions: s.m(Sury.array(assertionSchema)),
+  passed: s.m(Sury.int),
+  failed: s.m(Sury.int)
+}));
+
+function verified(certificate) {
+  if (certificate.failed === 0) {
+    return certificate.assertions.length !== 0;
+  } else {
+    return false;
+  }
+}
+
+function fromReport(trait, traitVersion, framework, host, suite, results) {
+  let assertions = results.map(param => ({
+    name: param[0],
+    passed: param[1]
+  }));
+  return {
+    trait: trait,
+    traitVersion: traitVersion,
+    framework: framework,
+    host: host,
+    suite: suite,
+    assertions: assertions,
+    passed: assertions.filter(a => a.passed).length,
+    failed: assertions.filter(a => !a.passed).length
+  };
+}
+
+function render(certificate) {
+  return JSON.stringify(Util_Sury$Reventless.toJson(certificate, schema), undefined, 2) + "\n";
+}
+
+function summarize(certificate) {
+  return certificate.trait + `@` + certificate.traitVersion + ` → ` + certificate.host + `: ` + (certificate.passed.toString() + `/` + certificate.assertions.length.toString() + ` assertions, `) + (
+    verified(certificate) ? "verified" : "NOT verified"
+  );
+}
+
+export {
+  assertionSchema,
+  schema,
+  verified,
+  fromReport,
+  render,
+  summarize,
+}
+/* assertionSchema Not a pure module */

package/src/components/TraitManifest.res

@@ -0,0 +1,90 @@
+/**
+A trait's listing metadata, derived rather than written.
+
+The old design had a hand-written `trait.yaml`. Everything in it is already a
+fact somewhere typed — the package declares the identity, the trait exports what
+it needs, and the emitter's config schema declares what a graft must be told — so
+a second copy could only be a place for those to disagree.
+
+## What is here, and what a run has to supply
+
+This is the **static** half: identity, needs, and the config surface. All of it is
+readable without running anything, which is what a listing wants before anybody
+installs.
+
+The **dynamic** half is `TraitCertificate` — what the suite proved, against a
+host. The two are deliberately separate artifacts: a listing carries the manifest
+always, and a certificate only once somebody has run the suite, so folding them
+together would force a listing to claim a proof it does not have.
+
+## What is deliberately absent
+
+The assertion list. What a trait certifies cannot be enumerated without running
+the suite — the assertions are registered by a functor, not declared as data —
+so a manifest that listed them would be restating the certificate from memory.
+A reader who wants to know what was proved reads a certificate.
+*/
+
+/** One field the emitter's config declares. `required` is read off the schema,
+    so an optional field cannot be listed as mandatory by a stale hand. */
+@schema
+type configField = {name: string, required: bool}
+
+@schema
+type t = {
+  /** The package name — this trait's identity everywhere else too. */
+  trait: string,
+  version: string,
+  description: string,
+  license: string,
+  /** Platform capabilities a host of this trait must have provisioned, as
+      `CapabilityNeed.toString` spells them. **Empty is a statement**, not a
+      silence: the attachments trait needs an object *store*, which is declared
+      by the field carrying it rather than as a capability, so its empty list is
+      the true answer. */
+  capabilities: array<string>,
+  /** What a graft must be told, from the emitter's own sury-validated config.
+      Sorted by name so the file does not churn on a field reordering. */
+  config: array<configField>,
+  /** Whether the trait ships an emitter at all. A trait whose graft is all
+      patches has nothing to write, and a consumer should know that before
+      reaching for `graft-trait` and being told. */
+  scaffolded: bool,
+}
+
+/** Deterministic rendering: 2-space indent, trailing newline. */
+let render = (manifest: t): string =>
+  JSON.stringify(manifest->Util_Sury.toJson(schema), ~space=2) ++ "\n"
+
+/**
+The emitter's config surface, read off its schema.
+
+Introspecting the schema rather than being handed a list is the whole point: a
+field added to the config appears here without anyone remembering to say so, and
+one renamed cannot linger under its old name.
+*/
+let configFieldsOf = (schema: S.t<unknown>): array<configField> =>
+  switch schema {
+  | Object({properties}) =>
+    properties
+    ->Dict.toArray
+    ->Array.map(((name, field)) => {
+      name,
+      // sury models an optional field as a union with `undefined`, which is how
+      // `?` reaches this side. Anything else is required.
+      required: switch field {
+      | AnyOf({anyOf}) =>
+        !(
+          anyOf->Array.some(m =>
+            switch m {
+            | Undefined(_) => true
+            | _ => false
+            }
+          )
+        )
+      | _ => true
+      },
+    })
+    ->Array.toSorted((a, b) => String.compare(a.name, b.name))
+  | _ => []
+  }

package/src/components/TraitManifest.res.mjs

@@ -0,0 +1,48 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+
+let configFieldSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  required: s.m(Sury.bool)
+}));
+
+let schema = Sury.$schema(s => ({
+  trait: s.m(Sury.string),
+  version: s.m(Sury.string),
+  description: s.m(Sury.string),
+  license: s.m(Sury.string),
+  capabilities: s.m(Sury.array(Sury.string)),
+  config: s.m(Sury.array(configFieldSchema)),
+  scaffolded: s.m(Sury.bool)
+}));
+
+function render(manifest) {
+  return JSON.stringify(Util_Sury$Reventless.toJson(manifest, schema), undefined, 2) + "\n";
+}
+
+function configFieldsOf(schema) {
+  if (schema.type === "object") {
+    return Object.entries(schema.properties).map(param => {
+      let field = param[1];
+      let tmp;
+      tmp = field.type === "anyOf" ? !field.anyOf.some(m => m.type === "undefined") : true;
+      return {
+        name: param[0],
+        required: tmp
+      };
+    }).toSorted((a, b) => Primitive_string.compare(a.name, b.name));
+  } else {
+    return [];
+  }
+}
+
+export {
+  configFieldSchema,
+  schema,
+  render,
+  configFieldsOf,
+}
+/* configFieldSchema Not a pure module */

package/src/generator/CertifyTrait.res

@@ -0,0 +1,190 @@
+// Turn a test report into a trait conformance certificate.
+//
+// Usage: certify-trait <trait-package> --host <componentName> --report <jest.json> --out <file>
+//
+// The trait's suite has run inside a consumer's build since the emitter shipped.
+// What was missing is a result something downstream can read: it was console
+// output, so a listing could carry a claim nobody could check.
+//
+// **The framework does not own the runner.** A consumer runs their suite their
+// own way and hands the report here — this reads it, selects the assertions
+// belonging to the trait's suite, and writes `Reventless.TraitCertificate`. The
+// decision of what "verified" means lives in that module, once, so a registry and
+// a build gate cannot disagree about it.
+//
+// The trait is resolved **by the name it is given** and its conformance module is
+// dynamically imported, exactly as `graft-trait` imports the scaffold — so
+// `reventless-spec` still depends on no trait.
+
+@val external dynImport: string => promise<'a> = "import"
+
+// ── The dynamic-import boundary ──────────────────────────────────────────────
+//
+// A trait's conformance module exports its suite title as a function of the host
+// name. Read rather than reconstructed: the suite registers that exact string,
+// and a CLI that re-derived it from prose would be guessing at the trait's own
+// wording and would break the day it was reworded.
+type conformanceExports = {suiteName: string => string}
+
+let fail = (message: string) => {
+  Console.error("certify-trait: " ++ message)
+  NodeProcess.exit(1)
+}
+
+let usage = `Usage: certify-trait <trait-package> --host <componentName> --report <jest.json> --out <file>
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --host           the bound component's name, as its Spec declares it
+  --report         a Jest JSON report (jest --json --outputFile=…)
+  --out            where to write the certificate
+
+  Exits non-zero if the suite is absent from the report, or if it did not pass —
+  an absent suite is the failure worth catching, since a build that never ran the
+  conformance suite is indistinguishable from one that ran it green.`
+
+// ── The report, at the boundary ──────────────────────────────────────────────
+//
+// Only the three fields this needs, decoded leniently: a report carries a great
+// deal more, and a strict shape here would break on a runner version that added
+// a field.
+@schema
+type reportAssertion = {
+  ancestorTitles: array<string>,
+  title: string,
+  status: string,
+}
+
+@schema
+type reportSuite = {assertionResults: array<reportAssertion>}
+
+@schema
+type report = {testResults: array<reportSuite>}
+
+/** Every assertion registered under this suite title, in report order.
+
+    Matched on the *full* ancestor title rather than a prefix or a substring: two
+    hosts of one trait produce two suites whose titles differ only by the host's
+    name, and a prefix match would fold one into the other and certify a host
+    against another host's run. */
+let assertionsFor = (report: report, ~suite: string): array<(string, bool)> =>
+  report.testResults->Array.flatMap(s =>
+    s.assertionResults->Array.filterMap(a =>
+      a.ancestorTitles->Array.includes(suite) ? Some((a.title, a.status == "passed")) : None
+    )
+  )
+
+let readJson = (path: string) =>
+  switch NodeFs.readFileSync(path)->JSON.parseOrThrow {
+  | json => json
+  | exception _ =>
+    fail(`could not read ${path} as JSON.`)
+    JSON.Encode.null
+  }
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+let main = async () => {
+  let argv = NodeProcess.argv->Array.slice(~start=2, ~end=NodeProcess.argv->Array.length)
+  let flag = key =>
+    switch argv->Array.indexOf("--" ++ key) {
+    | -1 => None
+    | i => argv->Array.get(i + 1)
+    }
+
+  switch argv->Array.get(0) {
+  | None | Some("") | Some("--help") | Some("-h") => {
+      Console.log(usage)
+      NodeProcess.exit(argv->Array.length == 0 ? 1 : 0)
+    }
+  | Some(traitPackage) =>
+    switch (flag("host"), flag("report"), flag("out")) {
+    | (None, _, _) | (_, None, _) | (_, _, None) =>
+      fail("--host, --report and --out are all required.\n\n" ++ usage)
+    | (Some(host), Some(reportPath), Some(out)) => {
+        // `@scope/trait-attachments` → `Attachments_Conformance`, the same
+        // derivation `graft-trait` does for `_Scaffold`.
+        let conformanceModule =
+          traitPackage
+          ->String.split("/")
+          ->Array.last
+          ->Option.getOr("")
+          ->String.replace("trait-", "")
+          ->String.split("-")
+          ->Array.map(part =>
+            part->String.charAt(0)->String.toUpperCase ++
+              part->String.slice(~start=1, ~end=part->String.length)
+          )
+          ->Array.join("") ++ "_Conformance"
+        let specifier = `${traitPackage}/src/${conformanceModule}.res.mjs`
+        // Resolved from the **caller's** directory: the trait is a dependency of
+        // the plugin being certified and deliberately not one of this package.
+        let modulePath = try NodeModule.createRequire(
+          NodeProcess.cwd() ++ "/index.js",
+        )->NodeModule.requireResolve(specifier) catch {
+        | _ => specifier
+        }
+        let conformance: conformanceExports = try await dynImport(
+          NodeUrl.pathToFileURL(modulePath)["href"],
+        ) catch {
+        | _ =>
+          fail(
+            `${traitPackage} ships no conformance suite (looked for ${specifier}).\n` ++
+            `  A trait without one cannot be certified — there is nothing to prove.`,
+          )
+          %raw(`undefined`)
+        }
+
+        let suite = conformance.suiteName(host)
+        let parsed = switch readJson(reportPath)->Util_Sury.fromJson(reportSchema) {
+        | value => value
+        | exception _ =>
+          fail(`${reportPath} is not a Jest JSON report (expected \`testResults\`).`)
+          %raw(`undefined`)
+        }
+
+        switch parsed->assertionsFor(~suite) {
+        // The failure worth catching. A green build that never ran the suite
+        // looks exactly like one that ran it and passed, so silence is refused
+        // rather than certified as zero-of-zero.
+        | [] =>
+          fail(
+            `the report contains no suite titled "${suite}".\n` ++
+            `  Either the conformance binding was never registered, or ${host} is not the ` ++
+            `name its Spec declares.`,
+          )
+        | results => {
+            let resolveVersion = specifier =>
+              try {
+                let entry =
+                  NodeModule.createRequire(
+                    NodeProcess.cwd() ++ "/index.js",
+                  )->NodeModule.requireResolve(specifier)
+                PackageVersion.fromModuleUrl(NodeUrl.pathToFileURL(entry)["href"])
+              } catch {
+              | _ => "0.0.0"
+              }
+
+            let certificate = TraitCertificate.fromReport(
+              ~trait=traitPackage,
+              ~traitVersion=resolveVersion(specifier),
+              // The framework the suite ran against, read the same way — a trait
+              // is certified against a version, never in the abstract.
+              ~framework=resolveVersion("@reventlessdev/reventless-spec/package.json"),
+              ~host,
+              ~suite,
+              ~results,
+            )
+            NodeFs.writeFileSync(out, certificate->TraitCertificate.render)
+            Console.log(`certify-trait: ${certificate->TraitCertificate.summarize}`)
+            Console.log(`Wrote: ${out}`)
+            if !(certificate->TraitCertificate.verified) {
+              NodeProcess.exit(1)
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+main()->Promise.ignore

package/src/generator/CertifyTrait.res.mjs

@@ -0,0 +1,154 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Nodefs from "node:fs";
+import * as Nodeurl from "node:url";
+import * as Nodemodule from "node:module";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+import * as PackageVersion$Reventless from "../PackageVersion.res.mjs";
+import * as TraitCertificate$Reventless from "../components/TraitCertificate.res.mjs";
+
+function fail(message) {
+  console.error("certify-trait: " + message);
+  process.exit(1);
+}
+
+let usage = `Usage: certify-trait <trait-package> --host <componentName> --report <jest.json> --out <file>
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --host           the bound component's name, as its Spec declares it
+  --report         a Jest JSON report (jest --json --outputFile=…)
+  --out            where to write the certificate
+
+  Exits non-zero if the suite is absent from the report, or if it did not pass —
+  an absent suite is the failure worth catching, since a build that never ran the
+  conformance suite is indistinguishable from one that ran it green.`;
+
+let reportAssertionSchema = Sury.$schema(s => ({
+  ancestorTitles: s.m(Sury.array(Sury.string)),
+  title: s.m(Sury.string),
+  status: s.m(Sury.string)
+}));
+
+let reportSuiteSchema = Sury.$schema(s => ({
+  assertionResults: s.m(Sury.array(reportAssertionSchema))
+}));
+
+let reportSchema = Sury.$schema(s => ({
+  testResults: s.m(Sury.array(reportSuiteSchema))
+}));
+
+function assertionsFor(report, suite) {
+  return report.testResults.flatMap(s => Stdlib_Array.filterMap(s.assertionResults, a => {
+    if (a.ancestorTitles.includes(suite)) {
+      return [
+        a.title,
+        a.status === "passed"
+      ];
+    }
+  }));
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(Nodefs.readFileSync(path, "utf8"));
+  } catch (exn) {
+    fail(`could not read ` + path + ` as JSON.`);
+    return null;
+  }
+}
+
+async function main() {
+  let argv = process.argv.slice(2, process.argv.length);
+  let flag = key => {
+    let i = argv.indexOf("--" + key);
+    if (i !== -1) {
+      return argv[i + 1 | 0];
+    }
+  };
+  let traitPackage = argv[0];
+  if (traitPackage !== undefined) {
+    switch (traitPackage) {
+      case "" :
+      case "--help" :
+      case "-h" :
+        break;
+      default:
+        let match = flag("host");
+        let match$1 = flag("report");
+        let match$2 = flag("out");
+        if (match === undefined) {
+          return fail("--host, --report and --out are all required.\n\n" + usage);
+        }
+        if (match$1 === undefined) {
+          return fail("--host, --report and --out are all required.\n\n" + usage);
+        }
+        if (match$2 === undefined) {
+          return fail("--host, --report and --out are all required.\n\n" + usage);
+        }
+        let conformanceModule = Stdlib_Option.getOr(Stdlib_Array.last(traitPackage.split("/")), "").replace("trait-", "").split("-").map(part => part.charAt(0).toUpperCase() + part.slice(1, part.length)).join("") + "_Conformance";
+        let specifier = traitPackage + `/src/` + conformanceModule + `.res.mjs`;
+        let modulePath;
+        try {
+          modulePath = Nodemodule.createRequire(process.cwd() + "/index.js").resolve(specifier);
+        } catch (exn) {
+          modulePath = specifier;
+        }
+        let conformance;
+        try {
+          conformance = await import(Nodeurl.pathToFileURL(modulePath).href);
+        } catch (exn$1) {
+          fail(traitPackage + ` ships no conformance suite (looked for ` + specifier + `).\n  A trait without one cannot be certified — there is nothing to prove.`);
+          conformance = undefined;
+        }
+        let suite = conformance.suiteName(match);
+        let parsed;
+        try {
+          parsed = Util_Sury$Reventless.fromJson(readJson(match$1), reportSchema);
+        } catch (exn$2) {
+          fail(match$1 + ` is not a Jest JSON report (expected \`testResults\`).`);
+          parsed = undefined;
+        }
+        let results = assertionsFor(parsed, suite);
+        if (results.length === 0) {
+          return fail(`the report contains no suite titled "` + suite + `".\n` + (`  Either the conformance binding was never registered, or ` + match + ` is not the `) + `name its Spec declares.`);
+        }
+        let resolveVersion = specifier => {
+          try {
+            let entry = Nodemodule.createRequire(process.cwd() + "/index.js").resolve(specifier);
+            return PackageVersion$Reventless.fromModuleUrl(Nodeurl.pathToFileURL(entry).href);
+          } catch (exn) {
+            return "0.0.0";
+          }
+        };
+        let certificate = TraitCertificate$Reventless.fromReport(traitPackage, resolveVersion(specifier), resolveVersion("@reventlessdev/reventless-spec/package.json"), match, suite, results);
+        Nodefs.writeFileSync(match$2, TraitCertificate$Reventless.render(certificate), "utf8");
+        console.log(`certify-trait: ` + TraitCertificate$Reventless.summarize(certificate));
+        console.log(`Wrote: ` + match$2);
+        if (!TraitCertificate$Reventless.verified(certificate)) {
+          process.exit(1);
+          return;
+        } else {
+          return;
+        }
+    }
+  }
+  console.log(usage);
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+
+main();
+
+export {
+  fail,
+  usage,
+  reportAssertionSchema,
+  reportSuiteSchema,
+  reportSchema,
+  assertionsFor,
+  readJson,
+  main,
+}
+/* reportAssertionSchema Not a pure module */