mhproto 0.8.0-preview.0

package/viewer/diff.js

@@ -0,0 +1,245 @@
+// Pure contract comparison, shared by the CLI, server and browser.
+const unordered = new Set([
+  'required',
+  'enum',
+  'type',
+  'rules',
+  'operations',
+  'examples',
+  'sources',
+  'testNames',
+  'x-mhproto-rules',
+  'x-clauses',
+]);
+export function canonical(value, key = '', parents = []) {
+  const path = [...parents, key];
+  const literal =
+    path.some(
+      (part, i) =>
+        ['example', 'default', 'const', 'value'].includes(part) && path[i - 1] !== 'properties',
+    ) || path.some((part, i) => part === 'body' && ['request', 'response'].includes(path[i - 1]));
+  if (Array.isArray(value)) {
+    const items = value.map((v) => canonical(v, '', path));
+    return !literal && unordered.has(key)
+      ? items.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))
+      : items;
+  }
+  if (value && typeof value === 'object')
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .filter((k) => value[k] !== undefined)
+        .map((k) => [k, canonical(value[k], k, path)]),
+    );
+  return value;
+}
+export function snapshotProject(value) {
+  const wrapped = ['mhproto-snapshot', 'bive-snapshot'].includes(value?.format);
+  if (wrapped && value.version !== 1) throw new Error('Unsupported MHProto snapshot version.');
+  const project = wrapped ? value.project : value;
+  if (
+    !project ||
+    !Array.isArray(project.capabilities) ||
+    !project.capabilities.length ||
+    typeof project.name !== 'string'
+  )
+    throw new Error('Choose a MHProto snapshot JSON or exported preview HTML.');
+  const ids = new Set();
+  for (const cap of project.capabilities) {
+    if (
+      !cap ||
+      typeof cap.id !== 'string' ||
+      ids.has(cap.id) ||
+      !Array.isArray(cap.operations) ||
+      !Array.isArray(cap.rules) ||
+      !Array.isArray(cap.examples) ||
+      !Array.isArray(cap.checks) ||
+      !cap.openapi
+    )
+      throw new Error('The baseline does not contain a valid MHProto contract.');
+    ids.add(cap.id);
+  }
+  return project;
+}
+export function contractSnapshot(
+  value,
+  { label = 'Iteration baseline', createdAt = new Date().toISOString() } = {},
+) {
+  const project = snapshotProject(value);
+  // Detach nested schemas and visuals: later viewer edits must not move the baseline.
+  return JSON.parse(
+    JSON.stringify({
+      format: 'mhproto-snapshot',
+      version: 1,
+      label,
+      createdAt,
+      project: {
+        name: project.name,
+        system: project.system ?? '',
+        visuals: project.visuals ?? [],
+        capabilities: project.capabilities.map(({ evidence, digest, ...cap }) => cap),
+      },
+    }),
+  );
+}
+const status = (a, b) => (a === undefined ? 'added' : b === undefined ? 'removed' : 'changed');
+export function fieldChanges(before, after, path = []) {
+  if (
+    JSON.stringify(canonical(before, path.at(-1), path.slice(0, -1))) ===
+    JSON.stringify(canonical(after, path.at(-1), path.slice(0, -1)))
+  )
+    return [];
+  const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+  if (object(before) && object(after))
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+      .sort()
+      .flatMap((key) => fieldChanges(before[key], after[key], [...path, key]));
+  return [
+    {
+      path,
+      status: status(before, after),
+      beforePresent: before !== undefined,
+      afterPresent: after !== undefined,
+      before: before ?? null,
+      after: after ?? null,
+    },
+  ];
+}
+function behaviourText(text = '') {
+  let rule = false,
+    fence;
+  return text
+    .replaceAll('\r\n', '\n')
+    .split('\n')
+    .filter((line) => {
+      const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+      if (marker) {
+        if (!fence) fence = marker;
+        else if (marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+        rule = false;
+        return true;
+      }
+      if (fence) return true;
+      if (/^\s*-\s+\*\*[A-Z][A-Z0-9-]*-\d+\*\*/.test(line)) {
+        rule = true;
+        return false;
+      }
+      if (rule && /^\s{2,}\S/.test(line)) return false;
+      rule = false;
+      return true;
+    })
+    .map((line) => line.trimEnd())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+export function compareModels(beforeValue, afterValue) {
+  const before = snapshotProject(beforeValue),
+    after = snapshotProject(afterValue),
+    changes = [];
+  const add = (capability, kind, id, a, b) => {
+    const fields = fieldChanges(a, b);
+    if (fields.length)
+      changes.push({
+        capability,
+        kind,
+        id,
+        status: status(a, b),
+        before: a ?? null,
+        after: b ?? null,
+        fields,
+      });
+  };
+  const compare = (capability, kind, oldItems, newItems, key) => {
+    const oldMap = new Map(oldItems.map((x) => [x[key], x])),
+      newMap = new Map(newItems.map((x) => [x[key], x]));
+    for (const id of new Set([...oldMap.keys(), ...newMap.keys()]))
+      add(capability, kind, id, oldMap.get(id), newMap.get(id));
+  };
+  add(
+    null,
+    'system',
+    'system',
+    { name: before.name, system: before.system ?? '' },
+    { name: after.name, system: after.system ?? '' },
+  );
+  const oldCaps = new Map(before.capabilities.map((c) => [c.id, c])),
+    newCaps = new Map(after.capabilities.map((c) => [c.id, c]));
+  const feature = (cap) => {
+    if (!cap) return undefined;
+    const { operations, ruleTitles, ...presentation } = cap.presentation ?? {};
+    const { paths, components, ...api } = cap.openapi,
+      { schemas, ...shared } = components ?? {};
+    const pathItems = Object.fromEntries(
+      Object.entries(paths ?? {}).map(([url, item]) => [
+        url,
+        Object.fromEntries(
+          Object.entries(item).filter(
+            ([key]) =>
+              ![
+                'get',
+                'post',
+                'put',
+                'patch',
+                'delete',
+                'options',
+                'head',
+                'trace',
+                'parameters',
+              ].includes(key),
+          ),
+        ),
+      ]),
+    );
+    return {
+      title: cap.title ?? cap.id,
+      description: cap.description ?? '',
+      url: cap.url ?? '',
+      behaviour: behaviourText(cap.prose),
+      api: { ...api, components: shared, pathItems },
+      transitions: cap.transitions ?? [],
+      nonTransitions: cap.nonTransitions ?? [],
+      presentation,
+      files: cap.files ?? {},
+      sources: cap.sources ?? [],
+      gaps: cap.gaps ?? [],
+    };
+  };
+  const rules = (cap) =>
+    (cap?.rules ?? []).map((r) => ({ ...r, title: cap.presentation?.ruleTitles?.[r.id] ?? r.id }));
+  const operations = (cap) =>
+    (cap?.operations ?? []).map((op) => ({
+      ...op,
+      presentation: cap.presentation?.operations?.[op.operationId] ?? {},
+    }));
+  for (const id of new Set([...oldCaps.keys(), ...newCaps.keys()])) {
+    const a = oldCaps.get(id),
+      b = newCaps.get(id);
+    add(id, 'feature', id, feature(a), feature(b));
+    compare(id, 'rule', rules(a), rules(b), 'id');
+    compare(id, 'operation', operations(a), operations(b), 'operationId');
+    compare(id, 'example', a?.examples ?? [], b?.examples ?? [], 'id');
+    compare(id, 'check', a?.checks ?? [], b?.checks ?? [], 'id');
+    compare(
+      id,
+      'schema',
+      Object.entries(a?.openapi.components?.schemas ?? {}).map(([name, schema]) => ({
+        name,
+        schema,
+      })),
+      Object.entries(b?.openapi.components?.schemas ?? {}).map(([name, schema]) => ({
+        name,
+        schema,
+      })),
+      'name',
+    );
+    compare(
+      id,
+      'visual',
+      (before.visuals ?? []).filter((v) => v.target?.capability === id),
+      (after.visuals ?? []).filter((v) => v.target?.capability === id),
+      'id',
+    );
+  }
+  return changes;
+}

package/viewer/index.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>MHProto</title>
+    <meta
+      name="description"
+      content="A shared contract for humans and agents: linked behaviour, API types, examples and verification."
+    />
+    <link
+      rel="icon"
+      type="image/svg+xml"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='white'/%3E%3Ctext x='3' y='43' font-family='monospace' font-size='26' font-weight='700' fill='%23141414'%3E%5Bmh%5D%3C/text%3E%3C/svg%3E"
+    />
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body>
+    <aside class="sidebar">
+      <a class="brand" id="home" href="https://mhproto.dev/" aria-label="MHProto homepage"
+        ><span class="brand-mark">[mh]</span><span>mhproto</span></a
+      >
+      <div class="nav-label">Project</div>
+      <div id="project-name" class="project-name">Loading…</div>
+      <div class="nav-label">Features</div>
+      <nav id="features" aria-label="Features"></nav>
+      <div class="sidebar-footer">
+        <a id="changes-link" href="#/changes">Changes</a><a id="sources-link" href="#">Sources</a
+        ><button id="save-preview" class="text-button" hidden>Save preview</button
+        ><span id="view-mode"></span>
+      </div>
+    </aside>
+    <main>
+      <div class="search-row">
+        <label class="sr-only" for="search">Search this project</label
+        ><input
+          id="search"
+          type="search"
+          placeholder="Search this project…"
+          autocomplete="off"
+        /><kbd>/</kbd>
+      </div>
+      <div id="content" aria-live="polite">Loading…</div>
+      <footer class="page-footer">
+        <span id="freshness"></span><span id="read-mode">Read-only</span>
+      </footer>
+    </main>
+    <script src="/vendor/mermaid.min.js"></script>
+    <script type="module" src="/app.js"></script>
+  </body>
+</html>