@fitzzero/quickdraw-lint 5.0.1 → 5.1.1

package/README.md

@@ -47,7 +47,7 @@ correct code; each rule's file says what it leaves alone.
 | `no-nested-write`                                                              | a nested relation write (`data: { labels: { create } }`) through the tracked client (`db`, `tx`): only the parent row is tracked                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | everywhere             |
 | `no-raw-sql-write`                                                             | `$executeRaw*`, and `$queryRaw*` running a write, in a function that does not record the rows with `ctx.touch(...)` (or `qd.collections.reset(...)`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | services, jobs, routes |
 | `no-manual-emit`                                                               | `.emit()` on the Socket.IO server or a socket (`io.to(room).emit`), and `qd:` strings, the framework's event and room names                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | services, jobs, routes |
-| `no-inline-auth-guard`                                                         | `if (!ctx.principal) throw ...` and its variants inside a `handler`; declare `access` instead                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | everywhere             |
+| `no-inline-auth-guard`                                                         | `if (!ctx.principal) throw ...` and its variants inside a `handler` (declare `access` instead), and a kind check there that throws, `if (ctx.principal.kind !== "user") throw ...` (declare `kinds` instead)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | everywhere             |
 | `no-unbounded-read`                                                            | `findMany` without `take` (a read by ids, `id` equal, `{ in }` or `{ equals }`, is bounded; `{ not }`, `{ notIn }` and `{ gt }` are not)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | services               |
 | `no-db-call-in-loop`                                                           | a database call per item of a `for`/`for...of`/`for...in` loop or `.map` callback, awaited or sent to `Promise.all` (not `while`, `createMany`, `in:` its own set, `tx` writes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | services, jobs, routes |
 | `no-emit-in-loop`                                                              | `ctx.rooms.emit`, `emitToUser` or a stream's `push` once per item to the same room, user or stream scope (fan-out is fine; batch with `pushMany`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | services, jobs, routes |
@@ -60,19 +60,23 @@ correct code; each rule's file says what it leaves alone.
 | `no-raw-socket`                                                                | `socket.emit`, `socket.on`, `socket.off` and the other raw Socket.IO calls: on a `socket` (or `x.socket`), on whatever `socket.io-client`'s `io()`, `connect()` or `Manager` made under any name (followed through variables and `this` fields), and with a `qd:` event name on any receiver                                                                                                                                                                                                                                                                                                                                                                                       | client code            |
 | `no-v4-api`                                                                    | every 4.x API 5.0 removed or moved; each message names the replacement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | everywhere             |
 | `prefer-kit`                                                                   | a method written by hand that a kit implements (`get`, `list`, `create`, `search`, `share`, `adminList`, or `getTask`, `listTasks`, `createTask`, `updateTask`, `deleteTask` for model `"task"`; `remove` only on a membership model or beside another sharing method) in a `defineService` whose `model` is a string (or a `const` of one) and whose `methods` spread no kit (a spread variable or call counts as one), or that duplicates what a kit spread beside it serves (`crud.handlers`' `access` literal names, `search` for `search.handlers`, every admin method for `admin.handlers`); a `// quickdraw: hand-written because <reason>` comment above it keeps it quiet | everywhere but tests   |
-| `no-todo-schema`                                                               | `todoSchema()`, the placeholder schema the 4.x migration (`@fitzzero/quickdraw-codemod`) leaves where a method had none: it validates nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | everywhere             |
+| `no-todo-schema`                                                               | `todoSchema()`, the placeholder schema the 4.x migration (`@fitzzero/quickdraw-codemod`) leaves where a method had none: it validates nothing; as a `query()` or `mutation()` input without `keys`, it also hides the input's keys from `defineService`'s id-reach (rowless) check, and the message says so                                                                                                                                                                                                                                                                                                                                                                        | everywhere             |
+| `require-describe`                                                             | a contract member without a `describe`: the contract (`defineContract`), each `query` and `mutation`, collection, stream, channel and event, written as an object literal (a spread or a definition built elsewhere is left alone), and a static `describe` under `minWords` words (default 3); the MCP bridge describes a method's tool with it and `quickdraw-docs` leads each section with it                                                                                                                                                                                                                                                                                   | everywhere but tests   |
 | `no-unused-baseline`                                                           | an allowance in the baseline file that no violation uses any more (below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | baselined files        |
 | `no-raw-button-strings`, `no-raw-tooltip-strings`, `no-raw-typography-strings` | raw strings in MUI `Button`, `Typography` and `Tooltip` titles (`oxlint.template.jsonc`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `*.tsx`, `*.jsx`       |
 
 The base config turns on all but the last three, at `error`, except
-`no-unused-baseline`, `no-todo-schema` and `prefer-kit`, which warn.
+`no-unused-baseline`, `no-todo-schema`, `prefer-kit` and `require-describe`,
+which warn. A warning never fails an upgrade's lint; once an app has no
+reports left from one, it can set the rule to `"error"` in its own config
+(`"quickdraw/require-describe": "error"`, say) so new code cannot add any.
 `oxlint.template.jsonc` extends the base and adds the last three.
 
 ### Which files a rule checks
 
 A rule about one layer checks only that layer's files. The defaults follow the
-template's layout. The rules scoped to services, jobs and routes, and
-`no-raw-socket`, skip tests (`__tests__/`, `test/`, `tests/`, `*.test.*`,
+template's layout. The rules scoped to services, jobs and routes,
+`no-raw-socket`, `prefer-kit` and `require-describe` skip tests (`__tests__/`, `test/`, `tests/`, `*.test.*`,
 `*.spec.*`), which seed, inspect and probe on purpose; the other rules check
 tests too.
 
@@ -105,7 +109,8 @@ that look at database calls; `modules` (specifiers of the untracked client's
 modules) on `no-untracked-write`; `emitters` on `no-manual-emit`; `sockets`,
 `allowedEvents` and `allowedPrefixes` on `no-raw-socket`; `clients` (the typed
 client's names, `["qd"]`) on `no-untyped-client` and `no-manual-refetch`;
-`shared` and `allow` (`{ "<service>": ["<service>/<file>"] }`) on
+`minWords` (the fewest words a static describe may have, default 3) on
+`require-describe`; `shared` and `allow` (`{ "<service>": ["<service>/<file>"] }`) on
 `no-cross-service-internal-imports`. Each rule's options are in its schema,
 so a misspelled option fails oxlint at startup.
 

package/oxlint.base.jsonc

@@ -116,6 +116,9 @@
     "quickdraw/no-v4-api": "error",
     // The migration's placeholder schema, until a real schema replaces it.
     "quickdraw/no-todo-schema": "warn",
+    // A describe on every contract member: MCP tool descriptions and the API docs.
+    // A warning so an upgrade never breaks lint; set it to "error" once the app has caught up.
+    "quickdraw/require-describe": "warn",
   },
   "overrides": [
     // Client/React code: relax server-oriented strictness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-lint",
-  "version": "5.0.1",
+  "version": "5.1.1",
   "description": "oxlint plugin, base config and baseline command for quickdraw apps",
   "keywords": [
     "lint",

package/plugin/index.mjs

@@ -29,6 +29,7 @@ import noUntypedClient from "./rules/no-untyped-client.mjs";
 import noUnusedBaseline from "./rules/no-unused-baseline.mjs";
 import noV4Api from "./rules/no-v4-api.mjs";
 import preferKit from "./rules/prefer-kit.mjs";
+import requireDescribe from "./rules/require-describe.mjs";
 
 const rules = {
   // Tracked writes
@@ -54,6 +55,8 @@ const rules = {
   "no-raw-socket": noRawSocket,
   // The kits
   "prefer-kit": preferKit,
+  // Documentation
+  "require-describe": requireDescribe,
   // Migration from 4.x
   "no-v4-api": noV4Api,
   "no-todo-schema": noTodoSchema,

package/plugin/rules/no-inline-auth-guard.mjs

@@ -6,8 +6,16 @@
 // `principal`, either side of `||`). A guard that returns instead of
 // throwing (a public method answering anonymous callers differently) is not
 // reported.
+//
+// The kinds of principal that may call are declared beside `access`, as
+// `kinds` (section 4.1), so it also reports a guard on the principal's kind
+// that throws: `if (ctx.principal.kind !== "user") throw ...`, a comparison
+// with a kind either way round, `!KINDS.includes(ctx.principal.kind)`, either
+// side of `||`. A kind tested with `&&` beside something else (agents may
+// not set this status) is a check `kinds` cannot make, and a `"public"`
+// method takes no `kinds`, so neither is reported.
 
-import { chainNames, isFunction, keyName, unwrap } from "../lib/ast.mjs";
+import { chainNames, getProperty, isFunction, keyName, memberName, unwrap } from "../lib/ast.mjs";
 
 /** Whether `node` reads the principal: `ctx.principal`, `principal`, or their `userId`. */
 function isPrincipal(node) {
@@ -28,6 +36,49 @@ function isNullish(node) {
   );
 }
 
+/** Whether `node` reads the principal's kind: `ctx.principal.kind` or `principal.kind`. */
+function isKind(node) {
+  const value = unwrap(node);
+  if (value.type !== "MemberExpression") {
+    return false;
+  }
+  const names = chainNames(value);
+  const at = names[0] === "ctx" ? 1 : 0;
+  return names.length - at === 2 && names[at] === "principal" && names[at + 1] === "kind";
+}
+
+function isString(node) {
+  const value = unwrap(node);
+  return value.type === "Literal" && typeof value.value === "string";
+}
+
+/** Whether a condition tests the principal's kind and nothing it must hold beside it. */
+function checksKind(test) {
+  const node = unwrap(test);
+  switch (node.type) {
+    case "LogicalExpression":
+      return node.operator === "||" && (checksKind(node.left) || checksKind(node.right));
+    case "UnaryExpression":
+      return node.operator === "!" && checksKind(node.argument);
+    case "BinaryExpression":
+      return (
+        ["==", "===", "!=", "!=="].includes(node.operator) &&
+        ((isKind(node.left) && isString(node.right)) || (isString(node.left) && isKind(node.right)))
+      );
+    case "CallExpression": {
+      const callee = unwrap(node.callee);
+      return (
+        callee.type === "MemberExpression" &&
+        memberName(callee) === "includes" &&
+        node.arguments.length === 1 &&
+        isKind(node.arguments[0])
+      );
+    }
+    default:
+      return false;
+  }
+}
+
 /** Whether a condition is true when there is no principal. */
 function checksMissingPrincipal(test) {
   const node = unwrap(test);
@@ -57,19 +108,38 @@ function throwsFirst(statement) {
   return statement.type === "BlockStatement" && statement.body[0]?.type === "ThrowStatement";
 }
 
-/** Whether `node` runs inside a method's `handler`. */
-function insideHandler(context, node) {
-  return context.sourceCode.getAncestors(node).some((ancestor) => {
-    if (!isFunction(ancestor)) {
-      return false;
-    }
+/** The `handler` property (or method) whose function `node` runs inside, or `undefined`. */
+function handlerOf(context, node) {
+  for (const ancestor of context.sourceCode.getAncestors(node)) {
     const holder = ancestor.parent;
-    return (
+    if (
+      isFunction(ancestor) &&
       (holder?.type === "Property" || holder?.type === "MethodDefinition") &&
       holder.value === ancestor &&
       keyName(holder) === "handler"
-    );
-  });
+    ) {
+      return holder;
+    }
+  }
+  return undefined;
+}
+
+/** Whether a method entry declares `access: "public"`, beside its `handler`. */
+function isPublicMethod(handler) {
+  const entry = handler.parent;
+  if (entry?.type !== "ObjectExpression") {
+    return false;
+  }
+  const access = getProperty(entry, "access");
+  return access !== undefined && unwrap(access.value).value === "public";
+}
+
+/** Which guard a condition is, if any: a missing principal, or the principal's kind. */
+function guardOf(test) {
+  if (checksMissingPrincipal(test)) {
+    return "inlineGuard";
+  }
+  return checksKind(test) ? "kindGuard" : undefined;
 }
 
 /** @type {import('eslint').Rule.RuleModule} */
@@ -78,25 +148,30 @@ export default {
     type: "suggestion",
     docs: {
       description:
-        "Disallow checking `ctx.principal` by hand in a handler: declare who may call in the method's `access`.",
+        "Disallow checking `ctx.principal` or its kind by hand in a handler: declare who may call in the method's `access` and `kinds`.",
     },
     messages: {
       inlineGuard:
         "Don't check `ctx.principal` by hand: declare it in the method's `access` (`\"authenticated\"`, `{ service }`, `{ entry }`, `{ scope, of, id }` or `custom(fn)`). " +
         "The dispatcher then refuses anonymous callers with `UNAUTHENTICATED` before the handler runs, on every transport, and `ctx.principal` is typed as present.",
+      kindGuard:
+        'Don\'t check `ctx.principal.kind` by hand: declare the kinds that may call beside `access`, as `kinds: ["user"]` on the method, on its service, or on `initQuickdraw` for every service. ' +
+        "The dispatcher then refuses every other kind with `FORBIDDEN` before the handler runs, on every transport and subscription, whatever its grants.",
     },
     schema: [],
   },
   create(context) {
     return {
       IfStatement(node) {
-        if (
-          checksMissingPrincipal(node.test) &&
-          throwsFirst(node.consequent) &&
-          insideHandler(context, node)
-        ) {
-          context.report({ node: node.test, messageId: "inlineGuard" });
+        const messageId = guardOf(node.test);
+        if (messageId === undefined || !throwsFirst(node.consequent)) {
+          return;
+        }
+        const handler = handlerOf(context, node);
+        if (handler === undefined || (messageId === "kindGuard" && isPublicMethod(handler))) {
+          return;
         }
+        context.report({ node: node.test, messageId });
       },
     };
   },

package/plugin/rules/no-todo-schema.mjs

@@ -5,11 +5,18 @@
 // schema replaces it. Found by shape: a call of `todoSchema` imported from
 // `@fitzzero/quickdraw-core` under any local name, or of a namespace import's
 // `todoSchema` member.
+//
+// A placeholder without `keys` that is the `input` of `query()` or
+// `mutation()` gets a second message: its JSON Schema names no keys, so
+// defineService's id-reach (rowless) check cannot see an `id` in it and
+// refuses nothing. Whether the method's access form checks a row is in the
+// service file, which this rule does not read, so it says so for every form.
 
-import { memberName, unwrap } from "../lib/ast.mjs";
+import { getProperty, hasSpread, memberName, unwrap } from "../lib/ast.mjs";
 
 const CORE = "@fitzzero/quickdraw-core";
 const NAME = "todoSchema";
+const METHODS = new Set(["query", "mutation"]);
 
 function importedName(specifier) {
   return specifier.imported.type === "Identifier"
@@ -17,30 +24,81 @@ function importedName(specifier) {
     : specifier.imported.value;
 }
 
-/** Records the local names `todoSchema` and the core namespace go by in this file. */
+/**
+ * Records the local names `todoSchema`, `query`, `mutation` and the core
+ * namespace go by in this file. `names` maps a local name to the imported one.
+ */
 function collectImport(node, names, namespaces) {
   if (node.source.value !== CORE) {
     return;
   }
   for (const specifier of node.specifiers) {
-    if (specifier.type === "ImportSpecifier" && importedName(specifier) === NAME) {
-      names.add(specifier.local.name);
+    if (specifier.type === "ImportSpecifier") {
+      const imported = importedName(specifier);
+      if (imported === NAME || METHODS.has(imported)) {
+        names.set(specifier.local.name, imported);
+      }
     } else if (specifier.type === "ImportNamespaceSpecifier") {
       namespaces.add(specifier.local.name);
     }
   }
 }
 
-/** Whether `callee` is `todoSchema` (by its local name) or `namespace.todoSchema`. */
-function isTodoSchema(callee, names, namespaces) {
+/** The core export `callee` calls (by its local name or as `namespace.name`), if any. */
+function coreName(callee, names, namespaces) {
   if (callee.type === "Identifier") {
-    return names.has(callee.name);
+    return names.get(callee.name);
   }
-  if (callee.type !== "MemberExpression" || memberName(callee) !== NAME) {
-    return false;
+  if (callee.type !== "MemberExpression") {
+    return undefined;
   }
   const object = unwrap(callee.object);
-  return object.type === "Identifier" && namespaces.has(object.name);
+  return object.type === "Identifier" && namespaces.has(object.name)
+    ? memberName(callee)
+    : undefined;
+}
+
+/**
+ * Whether a `todoSchema(...)` call surely names no keys: no options, or an
+ * options literal without `keys` (or with an empty list). Options it cannot
+ * read (a variable, a spread) may name some, so they do not count.
+ */
+function isKeyless(call) {
+  const options = call.arguments[0];
+  if (options === undefined) {
+    return true;
+  }
+  const object = unwrap(options);
+  if (object.type !== "ObjectExpression" || hasSpread(object)) {
+    return false;
+  }
+  const keys = getProperty(object, "keys");
+  if (keys === undefined) {
+    return true;
+  }
+  const list = unwrap(keys.value);
+  return list.type === "ArrayExpression" && list.elements.length === 0;
+}
+
+/** Whether `call` (through any wrapping assertion) is the `input` of a core `query()` or `mutation()`. */
+function isMethodInput(call, names, namespaces) {
+  let value = call;
+  while (value.parent !== null && value.parent !== undefined && unwrap(value.parent) === call) {
+    value = value.parent;
+  }
+  const property = value.parent;
+  if (property?.type !== "Property" || property.value !== value) {
+    return false;
+  }
+  if (getProperty(property.parent, "input") !== property) {
+    return false;
+  }
+  const method = property.parent.parent;
+  return (
+    method?.type === "CallExpression" &&
+    method.arguments[0] === property.parent &&
+    METHODS.has(coreName(unwrap(method.callee), names, namespaces))
+  );
 }
 
 /** @type {import('eslint').Rule.RuleModule} */
@@ -55,19 +113,26 @@ export default {
       todoSchema:
         "`todoSchema()` is a placeholder left by the 4.x migration: it validates nothing, so any value passes as its type. " +
         "Replace it with a real schema (Zod 4.2 or later where JSON Schema is read: MCP tools, admin metadata, projection keys).",
+      keylessInput:
+        "`todoSchema()` is a placeholder left by the 4.x migration: it validates nothing, so any value passes as its type. " +
+        "Without `keys`, it also hides this input's keys from defineService's id-reach (rowless) check, " +
+        "which refuses an `id` input under an access form that checks no row; give it keys " +
+        '(`todoSchema<T>({ keys: ["id", ...] })`) until a real schema (Zod 4.2 or later) replaces it.',
     },
     schema: [],
   },
   create(context) {
-    const names = new Set();
+    const names = new Map();
     const namespaces = new Set();
     return {
       ImportDeclaration: (node) => collectImport(node, names, namespaces),
       CallExpression(node) {
         const callee = unwrap(node.callee);
-        if (isTodoSchema(callee, names, namespaces)) {
-          context.report({ node: callee, messageId: "todoSchema" });
+        if (coreName(callee, names, namespaces) !== NAME) {
+          return;
         }
+        const keyless = isKeyless(node) && isMethodInput(node, names, namespaces);
+        context.report({ node: callee, messageId: keyless ? "keylessInput" : "todoSchema" });
       },
     };
   },

package/plugin/rules/require-describe.mjs

@@ -0,0 +1,195 @@
+// Every contract member says what it is for: a `describe` on each
+// `query(...)` and `mutation(...)`, on the contract itself and on each of its
+// collections, streams, channels and events. The MCP bridge uses a method's
+// describe as its tool's description (without one an agent sees only
+// `service.method (query)`), and `quickdraw-docs` leads each section of the
+// API docs with it. The 4.x codemod writes none, so a migrated contract has
+// one report per member until someone writes them; a warning in the base
+// config, `"error"` once an app has caught up.
+//
+// Found by shape: a call of `query`, `mutation` or `defineContract` imported
+// from `@fitzzero/quickdraw-core` under any local name, or of a namespace
+// import's member. Only object literals are checked: a spread (a kit's
+// contract half supplies its own describes, and so may a shared options
+// object) or a definition built elsewhere is left alone, and so is a
+// describe that is not a static string. A static describe needs `minWords`
+// words (default 3, the length of the kits' shortest). Test files are not
+// checked.
+
+import { keyName, memberName, staticString, unwrap } from "../lib/ast.mjs";
+import { FILE_OPTIONS, TEST_FILES, inScope } from "../lib/files.mjs";
+
+const CORE = "@fitzzero/quickdraw-core";
+const METHODS = new Set(["query", "mutation"]);
+const CONTRACT = "defineContract";
+const NAMES = new Set([...METHODS, CONTRACT]);
+/** The contract's members besides its methods, and what one of each is called in a message. */
+const MEMBERS = {
+  collections: "collection",
+  streams: "stream",
+  channels: "channel",
+  events: "event",
+};
+const DEFAULT_MIN_WORDS = 3;
+
+function importedName(specifier) {
+  return specifier.imported.type === "Identifier"
+    ? specifier.imported.name
+    : specifier.imported.value;
+}
+
+/** Records the local names of `query`, `mutation` and `defineContract`, and of core namespaces. */
+function collectImport(node, locals, namespaces) {
+  if (node.source.value !== CORE) {
+    return;
+  }
+  for (const specifier of node.specifiers) {
+    if (specifier.type === "ImportSpecifier" && NAMES.has(importedName(specifier))) {
+      locals.set(specifier.local.name, importedName(specifier));
+    } else if (specifier.type === "ImportNamespaceSpecifier") {
+      namespaces.add(specifier.local.name);
+    }
+  }
+}
+
+/** Which of the core's builders `callee` calls, if any. */
+function builderOf(callee, locals, namespaces) {
+  if (callee.type === "Identifier") {
+    return locals.get(callee.name);
+  }
+  if (callee.type !== "MemberExpression") {
+    return undefined;
+  }
+  const name = memberName(callee);
+  const object = unwrap(callee.object);
+  return NAMES.has(name) && object.type === "Identifier" && namespaces.has(object.name)
+    ? name
+    : undefined;
+}
+
+function wordCount(text) {
+  return text.split(/\s+/).filter((word) => word !== "").length;
+}
+
+/**
+ * Reports `object`, the definition of `member`, when it has no `describe`
+ * (and spreads nothing that could hold one) or a static one that is too
+ * short. `at` is the node a missing describe is reported on.
+ */
+function checkDefinition(context, object, member, at, minWords) {
+  let describe;
+  for (const property of object.properties) {
+    if (property.type === "SpreadElement") {
+      if (describe === undefined) {
+        describe = null;
+      }
+    } else if (keyName(property) === "describe") {
+      describe = property;
+    }
+  }
+  if (describe === undefined) {
+    context.report({ node: at, messageId: "missing", data: { member } });
+    return;
+  }
+  const text = describe === null ? undefined : staticString(describe.value);
+  if (text !== undefined && wordCount(text) < minWords) {
+    context.report({
+      node: describe.value,
+      messageId: "short",
+      data: { member, count: String(wordCount(text)), minWords: String(minWords) },
+    });
+  }
+}
+
+/** The object literal `node` is, through parentheses and type assertions, if it is one. */
+function objectLiteral(node) {
+  const value = unwrap(node);
+  return value?.type === "ObjectExpression" ? value : undefined;
+}
+
+/** A method call's name: the key it is written under (`get: query(...)`), if any. */
+function methodLabel(call, kind) {
+  const parent = call.parent;
+  const name = parent?.type === "Property" && parent.value === call ? keyName(parent) : undefined;
+  return name === undefined ? `this ${kind}` : `method "${name}"`;
+}
+
+function checkContract(context, call, minWords) {
+  const definition = objectLiteral(call.arguments[1]);
+  if (definition === undefined) {
+    return;
+  }
+  const name = staticString(call.arguments[0]);
+  checkDefinition(
+    context,
+    definition,
+    name === undefined ? "this contract" : `contract "${name}"`,
+    call.callee,
+    minWords,
+  );
+  for (const property of definition.properties) {
+    const kind = property.type === "Property" ? MEMBERS[keyName(property)] : undefined;
+    const members = kind === undefined ? undefined : objectLiteral(property.value);
+    for (const entry of members?.properties ?? []) {
+      const memberDefinition = entry.type === "Property" ? objectLiteral(entry.value) : undefined;
+      const entryName = entry.type === "Property" ? keyName(entry) : undefined;
+      if (memberDefinition !== undefined && entryName !== undefined) {
+        checkDefinition(context, memberDefinition, `${kind} "${entryName}"`, entry.key, minWords);
+      }
+    }
+  }
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Require a `describe` on every contract member: the contract, its methods, collections, streams, channels and events.",
+    },
+    messages: {
+      missing:
+        "{{ member }} has no `describe`. Say what it is for in a sentence or two: the MCP bridge uses a method's describe as its tool's description, and quickdraw-docs leads the member's section with it.",
+      short:
+        "{{ member }}'s `describe` has {{ count }} word(s); write at least {{ minWords }}, a sentence an agent can act on.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          ...FILE_OPTIONS,
+          minWords: {
+            type: "integer",
+            minimum: 1,
+            description: `The fewest words a static describe may have (default ${DEFAULT_MIN_WORDS}).`,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    if (!inScope(context, options, { ignore: TEST_FILES })) {
+      return {};
+    }
+    const minWords = options.minWords ?? DEFAULT_MIN_WORDS;
+    const locals = new Map();
+    const namespaces = new Set();
+    return {
+      ImportDeclaration: (node) => collectImport(node, locals, namespaces),
+      CallExpression(node) {
+        const builder = builderOf(unwrap(node.callee), locals, namespaces);
+        if (builder === CONTRACT) {
+          checkContract(context, node, minWords);
+        } else if (METHODS.has(builder)) {
+          const definition = objectLiteral(node.arguments[0]);
+          if (definition !== undefined) {
+            checkDefinition(context, definition, methodLabel(node, builder), node.callee, minWords);
+          }
+        }
+      },
+    };
+  },
+};