@fitzzero/quickdraw-core 5.0.1 → 5.1.0

package/dist/cli/quickdraw-docs.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
+import {
+  defaultToolName
+} from "../chunk-XNLWBZIG.js";
 import {
   CHANNEL_DEFAULT_RATE,
   DEFAULT_COLLECTION_LIMIT,
   DEFAULT_COLLECTION_MAX_LIMIT,
   isScopedStream
-} from "../chunk-5YRQ26LF.js";
+} from "../chunk-RT6OILOI.js";
 import {
   hasJsonSchema,
   isStandardSchema
@@ -76,6 +79,12 @@ function recordsOf(value) {
   }
   return value;
 }
+function kindsOf(value) {
+  return Array.isArray(value) && value.every((kind) => typeof kind === "string") ? value : void 0;
+}
+function namesOf(value) {
+  return Array.isArray(value) ? value.filter((name) => typeof name === "string") : [];
+}
 function mapEach(records, read) {
   return new Map([...records].map(([name, record]) => [name, read(record)]));
 }
@@ -94,13 +103,17 @@ function serviceDocOf(value) {
   }
   return Object.freeze({
     name: value.name,
+    model: typeof value.model === "string" ? value.model : void 0,
+    writes: namesOf(value.writes),
+    affects: Array.isArray(value.affects) ? value.affects.map((link) => contractName(isRecord(link) ? link.service : void 0)).filter((name) => name !== void 0) : [],
     policy: value.access,
     adminBypass: value.adminBypass !== false,
+    kinds: kindsOf(value.kinds),
     watchAccess: value.watchAccess,
     methods: new Map(
       Object.entries(methods).map(([name, method]) => [
         name,
-        { access: method.access, rowless: method.rowless === true }
+        { access: method.access, rowless: method.rowless === true, kinds: kindsOf(method.kinds) }
       ])
     ),
     collections: mapEach(collections, (collection) => ({
@@ -140,8 +153,11 @@ function servicesOf(exports) {
     [...found].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, { doc }]) => [name, doc])
   );
 }
+function contractName(contract) {
+  return isRecord(contract) && typeof contract.name === "string" ? contract.name : void 0;
+}
 function serviceName(contract) {
-  return isRecord(contract) && typeof contract.name === "string" ? contract.name : "another service";
+  return contractName(contract) ?? "another service";
 }
 function idOf(id) {
   if (id === void 0) {
@@ -220,13 +236,164 @@ function collectionAccessText(collection) {
   return `${String(collection.level)} or more on the ${code(serviceName(collection.anchor))} row the scope names`;
 }
 
+// src/cli/dependencies.ts
+var KINDS = ["inherit", "writes", "affects", "scope", "anchor"];
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function modelKey(model) {
+  return `${model.charAt(0).toLowerCase()}${model.slice(1)}`;
+}
+var MAX_POLICY_DEPTH2 = 3;
+function inheritsOf(policy, depth = 0) {
+  if (!isRecord2(policy)) {
+    return [];
+  }
+  if (policy.kind === "inherit") {
+    const from = contractName(policy.from);
+    return from === void 0 ? [] : [{ from, via: String(policy.via) }];
+  }
+  if (policy.kind === "anyOf" && Array.isArray(policy.policies) && depth < MAX_POLICY_DEPTH2) {
+    return policy.policies.flatMap((member) => inheritsOf(member, depth + 1));
+  }
+  return [];
+}
+function scopeOf(form) {
+  return isRecord2(form) && typeof form.scope === "string" ? contractName(form.of) : void 0;
+}
+function dependenciesOfService(service, contract, owners) {
+  const found = /* @__PURE__ */ new Map();
+  const add = (target, kind, text) => {
+    if (target === void 0 || target === service.name) {
+      return;
+    }
+    found.set(target, [...found.get(target) ?? [], { kind, text }]);
+  };
+  for (const { from, via } of inheritsOf(service.policy)) {
+    add(from, "inherit", `row policy: ${code("inherit")} through the ${code(via)} column`);
+  }
+  const models = [];
+  for (const model of service.writes) {
+    const serving = owners.get(modelKey(model)) ?? [];
+    if (serving.length === 0) {
+      models.push(model);
+    }
+    for (const owner of serving) {
+      add(owner, "writes", `${code("writes")}: its ${code(model)} model`);
+    }
+  }
+  for (const target of new Set(service.affects)) {
+    add(target, "affects", `${code("affects")}: a write to a row here changes its rows`);
+  }
+  for (const [name, method] of service.methods) {
+    add(scopeOf(method.access), "scope", `method ${code(name)}: ${code("{ scope, of }")}`);
+  }
+  for (const [name, access] of service.channels) {
+    add(scopeOf(access), "scope", `channel ${code(name)}: ${code("{ scope, of }")}`);
+  }
+  for (const [name, stream] of Object.entries(contract?.streams ?? {})) {
+    add(scopeOf(stream.access), "scope", `stream ${code(name)}: ${code("{ scope, of }")}`);
+  }
+  for (const [name, collection] of service.collections) {
+    add(
+      contractName(collection.anchor),
+      "anchor",
+      `collection ${code(name)}: anchored on its rows`
+    );
+  }
+  return {
+    services: [...found].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, reasons]) => ({
+      service: name,
+      reasons: KINDS.flatMap((kind) => reasons.filter((reason) => reason.kind === kind))
+    })),
+    models
+  };
+}
+function dependenciesOf(contracts, services) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const service of services.values()) {
+    if (service.model !== void 0) {
+      const key = modelKey(service.model);
+      owners.set(key, [...owners.get(key) ?? [], service.name]);
+    }
+  }
+  const byName = new Map(contracts.map((contract) => [contract.name, contract]));
+  return new Map(
+    [...services.values()].map((service) => [
+      service.name,
+      dependenciesOfService(service, byName.get(service.name), owners)
+    ])
+  );
+}
+function kindsOf2(dependency) {
+  return KINDS.filter((kind) => dependency.reasons.some((reason) => reason.kind === kind));
+}
+function dependsOnSection(dependencies) {
+  const { services, models } = dependencies;
+  const unserved = models.length === 0 ? [] : [`It also ${code("writes")} models no service's rows live in: ${list(models)}.`];
+  if (services.length === 0) {
+    return section("## Depends on", ["No other service: its declarations name none.", ...unserved]);
+  }
+  return section("## Depends on", [
+    `The other services its declarations name: its row policy, ${code("writes")}, ${code("affects")}, ${code("{ scope, of }")} access forms and collection anchors. A handler's undeclared reads are not listed.`,
+    table(
+      ["Service", "Declared by"],
+      services.map(({ service, reasons }) => [
+        code(service),
+        reasons.map((reason) => reason.text).join("; ")
+      ])
+    ),
+    ...unserved
+  ]);
+}
+function nodeIds(names) {
+  const ids = /* @__PURE__ */ new Map();
+  const taken = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    const safe = name.replace(/\W/g, "_");
+    let id = /^end$/i.test(safe) ? `${safe}_` : safe;
+    for (let n = 2; taken.has(id); n += 1) {
+      id = `${safe}_${n}`;
+    }
+    taken.add(id);
+    ids.set(name, id);
+  }
+  return ids;
+}
+function dependencyGraph(dependencies) {
+  const edges = [...dependencies].flatMap(
+    ([from, { services }]) => services.map((dependency) => ({
+      from,
+      to: dependency.service,
+      label: kindsOf2(dependency).join(", ")
+    }))
+  );
+  if (edges.length === 0) {
+    return section("## Dependencies", ["No service's declarations name another service."]);
+  }
+  const names = [...new Set(edges.flatMap(({ from, to }) => [from, to]))].sort();
+  const ids = nodeIds(names);
+  const id = (name) => ids.get(name) ?? name;
+  const nodes = names.filter((name) => id(name) !== name).map((name) => `  ${id(name)}["${name.replace(/"/g, "#quot;")}"]`);
+  return section("## Dependencies", [
+    `An arrow points from a service to another its declarations name: ${code("inherit")} (its row policy), ${code("writes")} (that service's model), ${code("affects")}, ${code("scope")} (a ${code("{ scope, of }")} access form) or ${code("anchor")} (a collection's anchor). Each service's page lists them.`,
+    [
+      "```mermaid",
+      "graph LR",
+      ...nodes,
+      ...edges.map(({ from, to, label }) => `  ${id(from)} -->|${label}| ${id(to)}`),
+      "```"
+    ]
+  ]);
+}
+
 // src/cli/schemaText.ts
 var NO_JSON_SCHEMA = "unknown (no JSON Schema)";
 var TARGET = "draft-07";
 var MAX_DEPTH = 8;
 var IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 var ROOT = "#";
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function jsonSchemaOf(schema, mode) {
@@ -235,7 +402,7 @@ function jsonSchemaOf(schema, mode) {
   }
   try {
     const json = schema["~standard"].jsonSchema[mode]({ target: TARGET });
-    return isRecord2(json) ? json : void 0;
+    return isRecord3(json) ? json : void 0;
   } catch {
     return void 0;
   }
@@ -247,8 +414,8 @@ function definitionOf(root, ref) {
   }
   const [, group = "", name = ""] = match;
   const definitions = root[group];
-  const found = isRecord2(definitions) ? definitions[decodeURIComponent(name)] : void 0;
-  return isRecord2(found) ? found : void 0;
+  const found = isRecord3(definitions) ? definitions[decodeURIComponent(name)] : void 0;
+  return isRecord3(found) ? found : void 0;
 }
 function literal(value) {
   return value === void 0 ? "undefined" : JSON.stringify(value);
@@ -287,13 +454,13 @@ function requiredOf(schema) {
   return new Set(Array.isArray(schema.required) ? schema.required.map(String) : []);
 }
 function objectText(schema, scope) {
-  const properties = isRecord2(schema.properties) ? schema.properties : {};
+  const properties = isRecord3(schema.properties) ? schema.properties : {};
   const required = requiredOf(schema);
   const members = Object.entries(properties).map(
     ([name, value]) => `${propertyName(name, !required.has(name))}: ${textOf(value, scope)}`
   );
   const extra = schema.additionalProperties;
-  if (isRecord2(extra)) {
+  if (isRecord3(extra)) {
     const value = textOf(extra, scope);
     if (members.length === 0) {
       return `Record<string, ${value}>`;
@@ -351,10 +518,10 @@ function refText(ref, scope) {
   return textOf(target, { ...scope, open: [...scope.open, ref] });
 }
 function textOf(schema, scope) {
-  if (schema === true || isRecord2(schema) && Object.keys(schema).length === 0) {
+  if (schema === true || isRecord3(schema) && Object.keys(schema).length === 0) {
     return "unknown";
   }
-  if (!isRecord2(schema) || scope.depth > MAX_DEPTH) {
+  if (!isRecord3(schema) || scope.depth > MAX_DEPTH) {
     return schema === false ? "never" : "unknown";
   }
   const inner = { ...scope, depth: scope.depth + 1 };
@@ -381,7 +548,7 @@ function textOf(schema, scope) {
   if (typeof type === "string") {
     return typeNameText(type, schema, inner);
   }
-  return isRecord2(schema.properties) ? objectText(schema, inner) : "unknown";
+  return isRecord3(schema.properties) ? objectText(schema, inner) : "unknown";
 }
 function schemaText(schema) {
   return textOf(schema, { root: schema, open: [ROOT], depth: 0 });
@@ -447,7 +614,7 @@ function schemaNotes(schema) {
 }
 function schemaFields(schema) {
   const properties = schema.properties;
-  if (schema.type !== "object" || !isRecord2(properties) || Object.keys(properties).length === 0) {
+  if (schema.type !== "object" || !isRecord3(properties) || Object.keys(properties).length === 0) {
     return void 0;
   }
   const required = requiredOf(schema);
@@ -456,7 +623,7 @@ function schemaFields(schema) {
     name,
     optional: !required.has(name),
     type: textOf(value, scope),
-    notes: isRecord2(value) ? schemaNotes(value) : ""
+    notes: isRecord3(value) ? schemaNotes(value) : ""
   }));
 }
 
@@ -547,6 +714,24 @@ function kindLine(method) {
   }
   return `A query that watches the ${code(method.watch.collection)} collection: a cached result is fetched again when the scope its input names changes.`;
 }
+function described(text) {
+  return text === void 0 ? [] : [paragraph(text)];
+}
+function callableBy(name, access) {
+  const method = access?.service?.methods.get(name);
+  if (method?.kinds === void 0) {
+    return [];
+  }
+  const anonymous = method.access === "public" ? ", or anonymously" : "";
+  return [`- Callable by: ${list(method.kinds)}${anonymous}`];
+}
+function methodFacts(service, name, method, access) {
+  return [
+    `- MCP tool (default name): ${code(defaultToolName(service, name))}`,
+    ...method.kind === "query" ? ["- MCP read-only hint: yes, as on every query's tool"] : [],
+    ...callableBy(name, access)
+  ];
+}
 function methodAccess(name, access) {
   const method = access?.service?.methods.get(name);
   if (method === void 0) {
@@ -557,11 +742,11 @@ function methodAccess(name, access) {
   ] : [];
   return [`Access: ${accessFormText(method.access)}.`, ...rowless];
 }
-function methodSection(name, method, access) {
-  const described = method.describe === void 0 ? [] : [paragraph(method.describe)];
+function methodSection(service, name, method, access) {
   return section(`### ${code(name)}`, [
-    ...described,
+    ...described(method.describe),
     kindLine(method),
+    methodFacts(service, name, method, access),
     ...methodAccess(name, access),
     ...inputBlocks(method),
     `Output: ${outputText(method.output)}.`
@@ -575,7 +760,7 @@ function methodsSection(contract, access) {
   return [
     "## Methods",
     "",
-    ...entries.flatMap(([name, method]) => methodSection(name, method, access))
+    ...entries.flatMap(([name, method]) => methodSection(contract.name, name, method, access))
   ];
 }
 function scopeText(scope) {
@@ -603,6 +788,7 @@ function collectionSection(name, collection, access) {
   const maxLimit = collection.maxLimit ?? DEFAULT_COLLECTION_MAX_LIMIT;
   const served = access?.service?.collections.get(name);
   return section(`### ${code(name)}`, [
+    ...described(collection.describe),
     optionTable([
       ["Scope", scopeText(collection.scope)],
       ["Item", code(collection.item)],
@@ -673,6 +859,7 @@ function streamSection(name, stream, access) {
   const scoped = isScopedStream(stream);
   const served = access?.service?.streams.get(name);
   return section(`### ${code(name)}`, [
+    ...described(stream.describe),
     optionTable([
       ["Item", code(typeOf(stream.item, "output"))],
       ["Scope", scoped ? `one feed per ${code(stream.scope ?? "")}` : "one global feed"],
@@ -700,6 +887,7 @@ function channelSection(name, channel, access) {
   const rate = channel.ratePerSecond ?? CHANNEL_DEFAULT_RATE;
   const served = access?.service?.channels.has(name) === true;
   return section(`### ${code(name)}`, [
+    ...described(channel.describe),
     optionTable([
       ["Payload", code(typeOf(channel.payload, "input"))],
       [
@@ -717,6 +905,7 @@ function channelSection(name, channel, access) {
 }
 function eventSection(name, event) {
   return section(`### ${code(name)}`, [
+    ...described(event.describe),
     optionTable([["Payload", code(typeOf(event.payload, "output"))]])
   ]);
 }
@@ -745,6 +934,10 @@ function accessSection(contract, access) {
         "Service-wide Admin",
         service.adminBypass ? "passes every check of the service" : `passes only the forms that name ${code("service")} (${code("adminBypass: false")})`
       ],
+      [
+        "Principal kinds",
+        service.kinds === void 0 ? void 0 : `${list(service.kinds)}: its methods, subscriptions and channels refuse every other kind`
+      ],
       ["Change topic", watchAccessText(service.watchAccess)],
       ["Field levels", fieldLevelsText(contract)]
     ]),
@@ -757,7 +950,9 @@ function renderService(contract, access) {
     "",
     `# ${contract.name}`,
     "",
+    ...described(contract.describe).flatMap((text) => [text, ""]),
     ...accessSection(contract, access),
+    ...access?.dependencies === void 0 ? [] : dependsOnSection(access.dependencies),
     ...entitySection(contract),
     ...projectionsSection(contract),
     ...methodsSection(contract, access),
@@ -787,10 +982,12 @@ function renderService(contract, access) {
 function fileOf(contract) {
   return `${contract.name.replace(/[^\w.-]/g, "-")}.md`;
 }
-function renderIndex(contracts) {
+function renderIndex(contracts, dependencies) {
   const count = (members) => String(Object.keys(members).length);
+  const hasDescribe = contracts.some((contract) => contract.describe !== void 0);
   const rows = contracts.map((contract) => [
     `[${contract.name}](${fileOf(contract)})`,
+    ...hasDescribe ? [contract.describe ?? ""] : [],
     count(contract.methods),
     count(contract.collections),
     count(contract.streams),
@@ -804,9 +1001,21 @@ function renderIndex(contracts) {
     "",
     "One page per service, generated from its contract by `quickdraw-docs`.",
     "",
-    ...table(["Service", "Methods", "Collections", "Streams", "Channels", "Events"], rows)
+    ...table(
+      [
+        "Service",
+        ...hasDescribe ? ["Description"] : [],
+        "Methods",
+        "Collections",
+        "Streams",
+        "Channels",
+        "Events"
+      ],
+      rows
+    ),
+    ...dependencies === void 0 ? [] : ["", ...dependencyGraph(dependencies)]
   ];
-  return `${lines.join("\n")}
+  return `${lines.join("\n").trimEnd()}
 `;
 }
 
@@ -815,7 +1024,8 @@ var USAGE = `Usage: quickdraw-docs <module> [--services <module>] [--out <dir>]
 
   <module>              a module exporting the app's contracts: each one, or a map of them
   --services <module>   a module exporting the services (each, or a list of them): the pages
-                        then also say who may call each method, from the services' access
+                        then also say who may call each method, from the services' access,
+                        and which services each depends on, with a graph on the index
   --out <dir>           where the pages go: one per service, plus README.md (default: docs/api)
   --check               write nothing; exit 1 when the pages on disk differ from the contracts
 `;
@@ -829,11 +1039,11 @@ var CONTRACT_KEYS = [
   "channels",
   "events"
 ];
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isContract(value) {
-  return isRecord3(value) && Object.isFrozen(value) && typeof value.name === "string" && "entity" in value && CONTRACT_KEYS.every((key) => isRecord3(value[key]));
+  return isRecord4(value) && Object.isFrozen(value) && typeof value.name === "string" && "entity" in value && CONTRACT_KEYS.every((key) => isRecord4(value[key]));
 }
 function contractsOf(exports) {
   const found = /* @__PURE__ */ new Map();
@@ -847,7 +1057,7 @@ function contractsOf(exports) {
   for (const value of Object.values(exports)) {
     if (isContract(value)) {
       add(value);
-    } else if (isRecord3(value)) {
+    } else if (isRecord4(value)) {
       Object.values(value).filter(isContract).forEach(add);
     }
   }
@@ -864,6 +1074,7 @@ function generateDocs(contracts, options = {}) {
       );
     }
   }
+  const dependencies = services === void 0 ? void 0 : dependenciesOf(contracts, services);
   const files = /* @__PURE__ */ new Map();
   for (const contract of contracts) {
     const file = fileOf(contract);
@@ -874,11 +1085,14 @@ function generateDocs(contracts, options = {}) {
       file,
       renderService(
         contract,
-        services === void 0 ? void 0 : { service: services.get(contract.name) }
+        services === void 0 ? void 0 : {
+          service: services.get(contract.name),
+          dependencies: dependencies?.get(contract.name)
+        }
       )
     );
   }
-  files.set(INDEX_FILE, renderIndex(contracts));
+  files.set(INDEX_FILE, renderIndex(contracts, dependencies));
   return files;
 }
 function readText(path) {