visigraph 0.0.6 → 0.0.7

package/README.md

@@ -1,11 +1,12 @@
 # visigraph
 
 Command line for [VisiGraph](https://github.com/textologylabs/visigraph):
-architecture models you can play through.
+bringing your architecture to life.
 
-Early, pre-1.0. Today it validates a model. Next it builds a static,
-playable site from one: no server, works as a file, a GitLab Pages site or
-a Confluence embed.
+Early, pre-1.0. Today it validates a model. Next it builds a static site
+from one: an explorable model you can zoom, drill into and follow, with
+journeys you can play on top. No server; works as a file, a GitLab Pages
+site or a Confluence embed.
 
 ```sh
 npm install -g visigraph

package/dist/main.js

@@ -2856,10 +2856,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} flag
        * @private
        */
-      unknownOption(flag) {
+      unknownOption(flag2) {
         if (this._allowUnknownOption) return;
         let suggestion = "";
-        if (flag.startsWith("--") && this._showSuggestionAfterError) {
+        if (flag2.startsWith("--") && this._showSuggestionAfterError) {
           let candidateFlags = [];
           let command = this;
           do {
@@ -2867,9 +2867,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
             candidateFlags = candidateFlags.concat(moreFlags);
             command = command.parent;
           } while (command && !command._enablePositionalOptions);
-          suggestion = suggestSimilar(flag, candidateFlags);
+          suggestion = suggestSimilar(flag2, candidateFlags);
         }
-        const message = `error: unknown option '${flag}'${suggestion}`;
+        const message = `error: unknown option '${flag2}'${suggestion}`;
         this.error(message, { code: "commander.unknownOption" });
       }
       /**
@@ -10807,16 +10807,86 @@ function lineOf(range, lines) {
   return `line ${line}, column ${col}`;
 }
 
+// ../core/dist/kinds.js
+var FAMILIES = ["container", "endpoint", "entity"];
+var KindRegistry = class _KindRegistry {
+  families = /* @__PURE__ */ new Map();
+  static of(...extensions) {
+    const r = new _KindRegistry();
+    for (const e of extensions)
+      r.register(e);
+    return r;
+  }
+  register(extension) {
+    for (const definition of extension.kinds) {
+      if (!FAMILIES.includes(definition.family)) {
+        throw new Error(`extension '${extension.name}': unknown family '${definition.family}'`);
+      }
+      const table = this.families.get(definition.family) ?? /* @__PURE__ */ new Map();
+      const existing = table.get(definition.kind);
+      if (existing) {
+        throw new Error(`extension '${extension.name}': ${definition.family} kind '${definition.kind}' is already registered by '${existing.extension}'`);
+      }
+      table.set(definition.kind, { definition, extension: extension.name });
+      this.families.set(definition.family, table);
+    }
+    return this;
+  }
+  /** True when at least one kind is registered for the family, so kinds in it are checked. */
+  governs(family) {
+    return (this.families.get(family)?.size ?? 0) > 0;
+  }
+  get(family, kind) {
+    return this.families.get(family)?.get(kind)?.definition;
+  }
+  kinds(family) {
+    return [...this.families.get(family)?.keys() ?? []].sort();
+  }
+};
+function checkKind(registry, family, element) {
+  if (!registry || !registry.governs(family))
+    return [];
+  const kind = element.kind;
+  if (kind === void 0)
+    return [];
+  if (typeof kind !== "string")
+    return [["kind", `${family} kind must be a string`]];
+  const def = registry.get(family, kind);
+  if (!def)
+    return [["kind", `unknown ${family} kind '${kind}'; registered: ${registry.kinds(family).join(", ")}`]];
+  const out = [];
+  for (const [name, decl] of Object.entries(def.properties)) {
+    const value = element[name];
+    if (value === void 0) {
+      if (decl.required)
+        out.push([name, `${family} kind '${kind}' requires '${name}'`]);
+      continue;
+    }
+    if (typeof value !== decl.type) {
+      out.push([name, `'${name}' on ${family} kind '${kind}' must be a ${decl.type}`]);
+      continue;
+    }
+    if (decl.enum && !decl.enum.includes(value)) {
+      out.push([name, `'${name}' on ${family} kind '${kind}' must be one of ${decl.enum.join(", ")}; got '${String(value)}'`]);
+    }
+  }
+  return out;
+}
+
 // ../core/dist/resolve.js
 function resolve(model, options = {}) {
-  const r = new Resolver();
+  const r = new Resolver(options.kinds);
   const root = r.declare(model, model.system, void 0, { file: options.file ?? "", prefix: "" });
   r.bind(root, void 0);
   r.check(root);
   return { root, diagnostics: r.diagnostics };
 }
 var Resolver = class {
+  kinds;
   diagnostics = [];
+  constructor(kinds2) {
+    this.kinds = kinds2;
+  }
   /** Scopes by interior identity, so a shared file is one scope. */
   scopes = /* @__PURE__ */ new Map();
   locs = /* @__PURE__ */ new Map();
@@ -10855,6 +10925,8 @@ var Resolver = class {
         return;
       }
       scope.entities.set(entity.id, entity);
+      for (const [suffix2, message] of checkKind(this.kinds, "entity", entity))
+        err(`${path}.${suffix2}`, message);
     });
     eachListed(node.journeys, "journeys", err, (journey, path) => {
       if (scope.journeys.has(journey.id)) {
@@ -10868,6 +10940,8 @@ var Resolver = class {
         err(`${path}.id`, `duplicate container id '${child.id}'`);
         return;
       }
+      for (const [suffix2, message] of checkKind(this.kinds, "container", child))
+        err(`${path}.${suffix2}`, message);
       const link = child[LINKED];
       const childLoc = link ? { file: link.file, prefix: "" } : { file: loc.file, prefix: `${loc.prefix}${path}.` };
       scope.children.set(child.id, this.declare(child, child.id, child, childLoc, scope.path));
@@ -10881,6 +10955,8 @@ var Resolver = class {
         err(`${path}.id`, `duplicate endpoint id '${endpoint.id}' in container '${container.id}'`);
       }
       endpointIds.add(endpoint.id);
+      for (const [suffix2, message] of checkKind(this.kinds, "endpoint", endpoint))
+        err(`${path}.${suffix2}`, message);
     });
     const stateIds = /* @__PURE__ */ new Set();
     eachListed(container.state, "state", err, (state, path) => {
@@ -10937,6 +11013,21 @@ var Resolver = class {
     const loc = this.locs.get(scope);
     const err = (path, message) => this.err(loc, path, message);
     const node = scope.container ?? this.rootNode(scope);
+    eachListed(node.containers, "containers", () => {
+    }, (container, cPath) => {
+      if (container[LINKED])
+        return;
+      eachListed(container.endpoints, `${cPath}.endpoints`, () => {
+      }, (endpoint, ePath) => {
+        for (const key of ["accepts", "returns"]) {
+          if (endpoint[key] === void 0)
+            continue;
+          const entity = ref(endpoint[key], `${ePath}.${key}`, err);
+          if (entity)
+            this.lookupMember(scope, entity, "entity", `${ePath}.${key}`, err);
+        }
+      });
+    });
     eachListed(node.journeys, "journeys", err, (journey, path) => {
       const hasSteps = journey.steps !== void 0;
       const hasScenarios = journey.scenarios !== void 0;
@@ -10985,20 +11076,30 @@ var Resolver = class {
         this.lookupContainer(scope, from, `${p}.from`, err);
       const to = ref(step.to, `${p}.to`, err);
       const target = to ? this.lookupContainer(scope, to, `${p}.to`, err) : void 0;
+      let endpointDecl;
       if (step.endpoint !== void 0) {
         const endpoint = ref(step.endpoint, `${p}.endpoint`, err);
         if (endpoint && target) {
           if (endpoint.includes(".")) {
             err(`${p}.endpoint`, `endpoint '${endpoint}' must be a bare id on the 'to' container, not a path`);
-          } else if (!(target.container?.endpoints ?? []).some((e) => e.id === endpoint)) {
-            err(`${p}.endpoint`, `container '${to}' has no endpoint '${endpoint}'`);
+          } else {
+            endpointDecl = (target.container?.endpoints ?? []).find((e) => e.id === endpoint);
+            if (!endpointDecl)
+              err(`${p}.endpoint`, `container '${to}' has no endpoint '${endpoint}'`);
           }
         }
       }
       if (step.payload !== void 0) {
-        const entity = isRecord(step.payload) ? ref(step.payload.entity, `${p}.payload.entity`, err) : ref(step.payload, `${p}.payload`, err);
-        if (entity)
-          this.lookupMember(scope, entity, "entity", `${p}.payload`, err);
+        const entityRef = isRecord(step.payload) ? ref(step.payload.entity, `${p}.payload.entity`, err) : ref(step.payload, `${p}.payload`, err);
+        const payload = entityRef ? this.lookupMember(scope, entityRef, "entity", `${p}.payload`, err) : void 0;
+        if (payload && endpointDecl?.accepts !== void 0 && target) {
+          const owner = this.ownerScope(target);
+          const accepted = owner ? this.lookupMember(owner, endpointDecl.accepts, "entity", `${p}.payload`, () => {
+          }) : void 0;
+          if (accepted && accepted !== payload) {
+            err(`${p}.payload`, `endpoint '${step.endpoint}' on '${to}' accepts '${endpointDecl.accepts}', not '${entityRef}'`);
+          }
+        }
       }
       if (!STEP_KINDS.includes(step.kind)) {
         err(`${p}.kind`, `kind must be one of ${STEP_KINDS.join(", ")}; got '${String(step.kind)}'`);
@@ -11029,19 +11130,27 @@ var Resolver = class {
     }
     return cur;
   }
-  /** Resolve `a.b.name` as container path `a.b` plus a member id. */
   lookupMember(scope, pathStr, kind, at, err) {
     const segments = pathStr.split(".");
     const name = segments.pop();
     const owner = segments.length === 0 ? scope : this.lookupContainer(scope, segments.join("."), at, err);
     if (!owner)
-      return false;
-    const table = kind === "entity" ? owner.entities : owner.journeys;
-    if (!table.has(name)) {
+      return void 0;
+    const found = kind === "entity" ? owner.entities.get(name) : owner.journeys.get(name);
+    if (!found) {
       err(at, segments.length === 0 ? `unknown ${kind} '${name}'` : `unknown ${kind} '${name}' in '${segments.join(".")}'`);
-      return false;
+      return void 0;
     }
-    return true;
+    return found;
+  }
+  /** The scope a container is declared in: where its endpoint contracts resolve from. */
+  ownerScope(target) {
+    for (const s of this.scopes.values()) {
+      for (const child of s.children.values())
+        if (child === target)
+          return s;
+    }
+    return void 0;
   }
 };
 function loadedFile(req, loc) {
@@ -11098,6 +11207,36 @@ var EXIT = {
   usage: 2
 };
 
+// ../ext-http/dist/index.js
+var http = {
+  name: "@visigraph/ext-http",
+  kinds: [
+    {
+      family: "endpoint",
+      kind: "http",
+      description: "An HTTP endpoint: a method and a path on a container.",
+      properties: {
+        method: {
+          type: "string",
+          tier: "advanced",
+          required: true,
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+          category: "transport"
+        },
+        path: {
+          type: "string",
+          tier: "advanced",
+          required: true,
+          category: "transport"
+        }
+      }
+    }
+  ]
+};
+
+// src/kinds.ts
+var kinds = KindRegistry.of(http);
+
 // src/commands/validate.ts
 function registerValidate(program3) {
   program3.command("validate").argument("<model>", "path to a model file (YAML)").description("check a model and every model it links or requires; every identifier must resolve").addHelpText(
@@ -11115,7 +11254,7 @@ async function validate(file) {
   const parsed = await loadModel(file);
   let diagnostics = parsed.diagnostics;
   if (parsed.model) {
-    diagnostics = diagnostics.concat(resolve(parsed.model, { file }).diagnostics);
+    diagnostics = diagnostics.concat(resolve(parsed.model, { file, kinds }).diagnostics);
   }
   for (const d of diagnostics) {
     const where = d.path ? `${d.file ?? file}:${d.path}` : d.file ?? file;
@@ -11388,11 +11527,21 @@ function relaunch() {
 }
 
 // src/main.ts
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (e) => {
+    if (e.code === "EPIPE") process.exit(process.exitCode ?? 0);
+    throw e;
+  });
+}
 var program2 = new Command();
 program2.name("visigraph").addHelpText("before", `${DESCRIPTION}
 `).version(VERSION, "-v, --version", "print the version and exit").helpOption("-h, --help", "print help and exit").helpCommand("help [command]", "print help for a command").showHelpAfterError("(run with --help for usage)").exitOverride();
 registerValidate(program2);
 var INSTANT = /* @__PURE__ */ new Set(["-v", "--version", "-h", "--help", "help"]);
+var [flag, maybeCommand] = process.argv.slice(2);
+if ((flag === "-h" || flag === "--help") && maybeCommand && program2.commands.some((c) => c.name() === maybeCommand)) {
+  process.argv.splice(2, 2, "help", maybeCommand);
+}
 try {
   if (process.argv.length <= 2) {
     program2.outputHelp();