@suss/adapter-python 0.3.2-0

package/dist/index.js

@@ -0,0 +1,2317 @@
+// src/annotations.ts
+import { createHash } from "crypto";
+
+// src/ast.ts
+function rangeOf(node) {
+  return {
+    start: node.startPosition.row + 1,
+    end: node.endPosition.row + 1
+  };
+}
+function field(node, name) {
+  return node.childForFieldName(name);
+}
+function fields(node, name) {
+  return node.childrenForFieldName(name);
+}
+function isType(node, ...types) {
+  return types.includes(node.type);
+}
+function stringLiteralValue(node) {
+  if (node.type !== "string") {
+    return null;
+  }
+  let content = "";
+  for (const child of node.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "string_content") {
+      content += child.text;
+      continue;
+    }
+    if (child.type === "interpolation") {
+      return null;
+    }
+  }
+  return content;
+}
+function bodyStatements(body) {
+  return body.namedChildren.filter((child) => child !== null);
+}
+function stripDecorators(node) {
+  if (node.type !== "decorated_definition") {
+    return { definition: node, decorators: [] };
+  }
+  const definition = field(node, "definition");
+  if (definition === null) {
+    throw new Error("decorated_definition with no definition field");
+  }
+  const decorators = node.namedChildren.filter(
+    (child) => child !== null && child.type === "decorator"
+  );
+  return { definition, decorators };
+}
+
+// src/scope.ts
+function bindModule(root) {
+  const scopeFor = /* @__PURE__ */ new Map();
+  const openImports = [];
+  const moduleScope = {
+    kind: "module",
+    node: root,
+    parent: null,
+    bindings: /* @__PURE__ */ new Map()
+  };
+  scopeFor.set(root.id, moduleScope);
+  bindBody(root, moduleScope, scopeFor, openImports);
+  return { moduleScope, scopeFor, openImports };
+}
+function bindName(scope, name, binding) {
+  const existing = scope.bindings.get(name);
+  if (existing?.kind === "global" || existing?.kind === "nonlocal") {
+    return;
+  }
+  scope.bindings.set(name, binding);
+}
+function bindBody(bodyOwner, scope, scopeFor, openImports) {
+  const ctx = { scopeFor, openImports };
+  for (const stmt of bodyStatements(bodyOwner)) {
+    bindStatement(stmt, scope, ctx);
+  }
+}
+var STATEMENT_BINDERS = {
+  import_statement: bindImportStatement,
+  import_from_statement: bindImportFromStatement,
+  decorated_definition: bindDecoratedDefinition,
+  function_definition: bindFunctionDefinition,
+  class_definition: bindClassDefinition,
+  expression_statement: bindExpressionStatement,
+  global_statement: bindGlobalStatement,
+  nonlocal_statement: bindNonlocalStatement
+};
+function bindStatement(stmt, scope, ctx) {
+  const binder = STATEMENT_BINDERS[stmt.type];
+  binder?.(stmt, scope, ctx);
+}
+function bindImportStatement(stmt, scope) {
+  for (const nameNode of fields(stmt, "name")) {
+    if (nameNode.type === "aliased_import") {
+      const dotted = field(nameNode, "name");
+      const alias = field(nameNode, "alias");
+      if (dotted !== null && alias !== null) {
+        bindName(scope, alias.text, {
+          kind: "import",
+          module: dotted.text,
+          relativeLevel: 0,
+          localName: alias.text
+        });
+      }
+      continue;
+    }
+    if (nameNode.type === "dotted_name") {
+      const first = nameNode.namedChild(0);
+      if (first !== null) {
+        bindName(scope, first.text, {
+          kind: "import",
+          module: nameNode.text,
+          relativeLevel: 0,
+          localName: first.text
+        });
+      }
+    }
+  }
+}
+function relativeImportParts(node) {
+  let relativeLevel = 0;
+  let module = "";
+  for (const child of node.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "import_prefix") {
+      relativeLevel += child.text.length;
+      continue;
+    }
+    if (child.type === "dotted_name") {
+      module = child.text;
+    }
+  }
+  return { relativeLevel, module };
+}
+function bindImportFromStatement(stmt, scope, ctx) {
+  const moduleNode = field(stmt, "module_name");
+  if (moduleNode === null) {
+    return;
+  }
+  const { module, relativeLevel } = moduleNode.type === "relative_import" ? relativeImportParts(moduleNode) : { module: moduleNode.text, relativeLevel: 0 };
+  const hasWildcard = stmt.namedChildren.some(
+    (child) => child !== null && child.type === "wildcard_import"
+  );
+  if (hasWildcard) {
+    ctx.openImports.push(
+      relativeLevel > 0 ? `${".".repeat(relativeLevel)}${module}` : module
+    );
+    return;
+  }
+  for (const nameNode of fields(stmt, "name")) {
+    if (nameNode.type === "aliased_import") {
+      const original = field(nameNode, "name");
+      const alias = field(nameNode, "alias");
+      if (original !== null && alias !== null) {
+        bindName(scope, alias.text, {
+          kind: "importFrom",
+          module,
+          relativeLevel,
+          importedName: original.text
+        });
+      }
+      continue;
+    }
+    if (nameNode.type === "dotted_name") {
+      bindName(scope, nameNode.text, {
+        kind: "importFrom",
+        module,
+        relativeLevel,
+        importedName: nameNode.text
+      });
+    }
+  }
+}
+function bindDecoratedDefinition(stmt, scope, ctx) {
+  const { definition } = stripDecorators(stmt);
+  bindStatement(definition, scope, ctx);
+}
+function bindFunctionDefinition(stmt, scope, ctx) {
+  const nameNode = field(stmt, "name");
+  if (nameNode !== null) {
+    bindName(scope, nameNode.text, { kind: "functionDef", node: stmt });
+  }
+  const functionScope = {
+    kind: "function",
+    node: stmt,
+    parent: scope,
+    bindings: /* @__PURE__ */ new Map()
+  };
+  ctx.scopeFor.set(stmt.id, functionScope);
+  const parametersNode = field(stmt, "parameters");
+  if (parametersNode !== null) {
+    bindParameters(parametersNode, functionScope);
+  }
+  const bodyNode = field(stmt, "body");
+  if (bodyNode !== null) {
+    bindBody(bodyNode, functionScope, ctx.scopeFor, ctx.openImports);
+  }
+}
+function bindParameters(parametersNode, functionScope) {
+  for (const param of parametersNode.namedChildren) {
+    if (param === null) {
+      continue;
+    }
+    const name = parameterName(param);
+    if (name !== null) {
+      bindName(functionScope, name, { kind: "parameter" });
+    }
+  }
+}
+function parameterName(param) {
+  if (isType(param, "identifier")) {
+    return param.text;
+  }
+  if (isType(
+    param,
+    "typed_parameter",
+    "list_splat_pattern",
+    "dictionary_splat_pattern"
+  )) {
+    const inner = param.namedChildren.find(
+      (child) => child !== null && child.type === "identifier"
+    );
+    return inner?.text ?? null;
+  }
+  if (isType(param, "default_parameter", "typed_default_parameter")) {
+    const nameNode = field(param, "name");
+    return nameNode?.type === "identifier" ? nameNode.text : null;
+  }
+  return null;
+}
+function bindClassDefinition(stmt, scope, ctx) {
+  const nameNode = field(stmt, "name");
+  if (nameNode !== null) {
+    bindName(scope, nameNode.text, { kind: "classDef", node: stmt });
+  }
+  const classScope = {
+    kind: "class",
+    node: stmt,
+    parent: scope,
+    bindings: /* @__PURE__ */ new Map()
+  };
+  ctx.scopeFor.set(stmt.id, classScope);
+  const bodyNode = field(stmt, "body");
+  if (bodyNode !== null) {
+    bindBody(bodyNode, classScope, ctx.scopeFor, ctx.openImports);
+  }
+}
+function bindExpressionStatement(stmt, scope) {
+  const assignment = stmt.namedChildren.find(
+    (child) => child !== null && child.type === "assignment"
+  );
+  if (assignment === void 0 || assignment === null) {
+    return;
+  }
+  const left = field(assignment, "left");
+  if (left === null) {
+    return;
+  }
+  if (left.type === "identifier") {
+    bindName(scope, left.text, {
+      kind: "assignment",
+      value: field(assignment, "right")
+    });
+  }
+}
+function bindGlobalStatement(stmt, scope) {
+  for (const child of stmt.namedChildren) {
+    if (child !== null && child.type === "identifier") {
+      scope.bindings.set(child.text, { kind: "global" });
+    }
+  }
+}
+function bindNonlocalStatement(stmt, scope) {
+  for (const child of stmt.namedChildren) {
+    if (child !== null && child.type === "identifier") {
+      scope.bindings.set(child.text, { kind: "nonlocal" });
+    }
+  }
+}
+function moduleScopeOf(scope) {
+  let current = scope;
+  while (current.parent !== null) {
+    current = current.parent;
+  }
+  return current;
+}
+function resolveName(scope, name) {
+  let current = scope;
+  let first = true;
+  while (current !== null) {
+    if (current.kind !== "class" || first) {
+      const binding = current.bindings.get(name);
+      if (binding !== void 0) {
+        if (binding.kind === "global") {
+          return moduleScopeOf(scope).bindings.get(name) ?? null;
+        }
+        if (binding.kind === "nonlocal") {
+          return resolveNonlocal(current, name);
+        }
+        return binding;
+      }
+    }
+    first = false;
+    current = current.parent;
+  }
+  return null;
+}
+function resolveNonlocal(scope, name) {
+  let current = scope.parent;
+  while (current !== null) {
+    if (current.kind === "function") {
+      const binding = current.bindings.get(name);
+      if (binding !== void 0 && binding.kind !== "nonlocal" && binding.kind !== "global") {
+        return binding;
+      }
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+// src/annotations.ts
+function createAnnotationContext(scopeFor) {
+  return { scopeFor, definitions: /* @__PURE__ */ new Map() };
+}
+function collectedDefinitions(ctx) {
+  const out = {};
+  let any = false;
+  for (const [key, shape] of ctx.definitions) {
+    if (shape !== null) {
+      out[key] = shape;
+      any = true;
+    }
+  }
+  return any ? out : null;
+}
+var BUILTIN_SCALARS = {
+  int: { type: "integer" },
+  float: { type: "number" },
+  str: { type: "text" },
+  bytes: { type: "text" },
+  bool: { type: "boolean" },
+  Any: { type: "unknown" },
+  object: { type: "unknown" }
+};
+var LIST_NAMES = /* @__PURE__ */ new Set(["list", "List", "Sequence", "Iterable"]);
+var DICT_NAMES = /* @__PURE__ */ new Set(["dict", "Dict", "Mapping"]);
+var TUPLE_SET_NAMES = /* @__PURE__ */ new Set([
+  "tuple",
+  "Tuple",
+  "set",
+  "Set",
+  "frozenset",
+  "FrozenSet"
+]);
+function annotationToShape(typeNode, scope, ctx) {
+  const inner = typeNode.namedChild(0);
+  if (inner === null) {
+    return { type: "unknown" };
+  }
+  return shapeFromExpression(inner, scope, ctx);
+}
+var EXPRESSION_SHAPERS = {
+  identifier: (node, scope, ctx) => shapeFromName(node.text, scope, ctx),
+  none: () => ({ type: "null" }),
+  generic_type: shapeFromGenericType,
+  binary_operator: shapeFromBinaryOperator
+};
+function shapeFromExpression(node, scope, ctx) {
+  const handler = EXPRESSION_SHAPERS[node.type];
+  return handler !== void 0 ? handler(node, scope, ctx) : { type: "unknown" };
+}
+function shapeFromName(name, scope, ctx) {
+  const scalar = BUILTIN_SCALARS[name];
+  if (scalar !== void 0) {
+    return scalar;
+  }
+  if (LIST_NAMES.has(name)) {
+    return { type: "array", items: { type: "unknown" } };
+  }
+  if (DICT_NAMES.has(name)) {
+    return { type: "dictionary", values: { type: "unknown" } };
+  }
+  const binding = resolveName(scope, name);
+  if (binding?.kind === "classDef") {
+    return recordShapeRef(name, binding.node, ctx);
+  }
+  return { type: "ref", name };
+}
+function genericTypeArgs(node) {
+  const typeParameter = node.namedChildren.find(
+    (child) => child !== null && child.type === "type_parameter"
+  );
+  return typeParameter?.namedChildren.filter(
+    (child) => child !== null && child.type === "type"
+  ) ?? [];
+}
+function shapeFromGenericType(node, scope, ctx) {
+  const base = node.namedChild(0);
+  const args = genericTypeArgs(node);
+  const shapeOf = (arg) => arg !== void 0 ? annotationToShape(arg, scope, ctx) : { type: "unknown" };
+  const baseName = base?.type === "identifier" ? base.text : null;
+  if (baseName === "Optional") {
+    return { type: "union", variants: [shapeOf(args[0]), { type: "null" }] };
+  }
+  if (baseName === "Union") {
+    return { type: "union", variants: args.map((arg) => shapeOf(arg)) };
+  }
+  if (baseName !== null && LIST_NAMES.has(baseName)) {
+    return { type: "array", items: shapeOf(args[0]) };
+  }
+  if (baseName !== null && DICT_NAMES.has(baseName)) {
+    return { type: "dictionary", values: shapeOf(args[1] ?? args[0]) };
+  }
+  if (baseName !== null && TUPLE_SET_NAMES.has(baseName)) {
+    return { type: "array", items: shapeOf(args[0]) };
+  }
+  return { type: "ref", name: baseName ?? node.text };
+}
+function shapeFromBinaryOperator(node, scope, ctx) {
+  const operator = field(node, "operator");
+  const left = field(node, "left");
+  const right = field(node, "right");
+  if (operator?.text !== "|" || left === null || right === null) {
+    return { type: "unknown" };
+  }
+  return {
+    type: "union",
+    variants: [
+      shapeFromExpression(left, scope, ctx),
+      shapeFromExpression(right, scope, ctx)
+    ]
+  };
+}
+function recordShapeRef(name, classNode, ctx) {
+  const key = `${name}@${shortHash(classNode.text)}`;
+  const ref = { type: "ref", name, def: key };
+  if (ctx.definitions.has(key)) {
+    return ref;
+  }
+  ctx.definitions.set(key, null);
+  const bodyNode = field(classNode, "body");
+  const classScope = ctx.scopeFor.get(classNode.id);
+  ctx.definitions.set(
+    key,
+    bodyNode !== null && classScope !== void 0 ? recordShapeOf(bodyNode, classScope, ctx) : { type: "record", properties: {} }
+  );
+  return ref;
+}
+function recordShapeOf(bodyNode, classScope, ctx) {
+  const properties = {};
+  for (const stmt of bodyNode.namedChildren) {
+    if (stmt === null || stmt.type !== "expression_statement") {
+      continue;
+    }
+    const assignment = stmt.namedChildren.find(
+      (child) => child !== null && child.type === "assignment"
+    );
+    if (assignment === void 0 || assignment === null) {
+      continue;
+    }
+    const left = field(assignment, "left");
+    const typeNode = field(assignment, "type");
+    if (left === null || left.type !== "identifier" || typeNode === null) {
+      continue;
+    }
+    properties[left.text] = annotationToShape(typeNode, classScope, ctx);
+  }
+  return { type: "record", properties };
+}
+function shortHash(text) {
+  return createHash("sha1").update(text).digest("hex").slice(0, 12);
+}
+
+// src/decorators.ts
+function readArg(node) {
+  const literal = stringLiteralValue(node);
+  if (literal !== null) {
+    return { kind: "string", value: literal };
+  }
+  if (node.type === "integer") {
+    const value = Number.parseInt(node.text, 10);
+    if (Number.isFinite(value)) {
+      return { kind: "number", value };
+    }
+    return { kind: "other" };
+  }
+  if (node.type === "none") {
+    return { kind: "none" };
+  }
+  if (node.type === "true" || node.type === "false") {
+    return { kind: "boolean", value: node.type === "true" };
+  }
+  if (node.type === "identifier") {
+    return { kind: "identifier", name: node.text };
+  }
+  if (node.type === "list") {
+    return {
+      kind: "list",
+      items: node.namedChildren.filter((child) => child !== null).map(readArg)
+    };
+  }
+  return { kind: "other" };
+}
+function readCallArguments(argumentList) {
+  const args = [];
+  const keywordArgs = {};
+  if (argumentList === null) {
+    return { args, keywordArgs };
+  }
+  for (const child of argumentList.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "keyword_argument") {
+      const nameNode = field(child, "name");
+      const valueNode = field(child, "value");
+      if (nameNode !== null && valueNode !== null) {
+        keywordArgs[nameNode.text] = readArg(valueNode);
+      }
+      continue;
+    }
+    args.push(readArg(child));
+  }
+  return { args, keywordArgs };
+}
+var UNRESOLVED = {
+  importedName: null,
+  module: null,
+  objectName: null,
+  relativeLevel: 0
+};
+function resolveObjectModule(name, scope) {
+  const binding = resolveName(scope, name);
+  if (binding?.kind === "import") {
+    return { module: binding.module, relativeLevel: binding.relativeLevel };
+  }
+  if (binding?.kind === "assignment" && binding.value?.type === "call") {
+    const callee = field(binding.value, "function");
+    if (callee?.type === "identifier") {
+      const calleeBinding = resolveName(scope, callee.text);
+      if (calleeBinding?.kind === "importFrom") {
+        return {
+          module: calleeBinding.module,
+          relativeLevel: calleeBinding.relativeLevel
+        };
+      }
+    }
+  }
+  return null;
+}
+function resolveCallee(expr, scope) {
+  if (expr.type === "identifier") {
+    const binding = resolveName(scope, expr.text);
+    if (binding?.kind === "importFrom") {
+      return {
+        importedName: binding.importedName,
+        module: binding.module,
+        objectName: null,
+        relativeLevel: binding.relativeLevel
+      };
+    }
+    return UNRESOLVED;
+  }
+  if (expr.type === "attribute") {
+    const object = field(expr, "object");
+    const attribute = field(expr, "attribute");
+    if (object === null || attribute === null || object.type !== "identifier") {
+      return UNRESOLVED;
+    }
+    const origin = resolveObjectModule(object.text, scope);
+    if (origin === null) {
+      return UNRESOLVED;
+    }
+    return {
+      importedName: attribute.text,
+      module: origin.module,
+      objectName: object.text,
+      relativeLevel: origin.relativeLevel
+    };
+  }
+  return UNRESOLVED;
+}
+function classifyDecorator(decoratorNode, scope) {
+  const range = rangeOf(decoratorNode);
+  const expr = decoratorNode.namedChild(0);
+  if (expr === null) {
+    return { ...UNRESOLVED, args: [], keywordArgs: {}, range };
+  }
+  if (expr.type === "call") {
+    const callee = field(expr, "function");
+    const argumentList = field(expr, "arguments");
+    const resolved = callee !== null ? resolveCallee(callee, scope) : UNRESOLVED;
+    const { args, keywordArgs } = argumentList?.type === "argument_list" ? readCallArguments(argumentList) : { args: [], keywordArgs: {} };
+    return { ...resolved, args, keywordArgs, range };
+  }
+  return { ...resolveCallee(expr, scope), args: [], keywordArgs: {}, range };
+}
+
+// src/discovery.ts
+import { dispatchByType, restBinding } from "@suss/behavioral-ir";
+import {
+  absentReading,
+  ambiguousReading,
+  andThenReading,
+  firstWrittenReading,
+  mapReading,
+  unreadableReading,
+  valueToReadFurtherFrom,
+  writtenReading
+} from "@suss/extractor";
+function discoverUnits(root, module, options) {
+  const units = [];
+  for (const stmt of bodyStatements(root)) {
+    if (stmt.type !== "decorated_definition") {
+      continue;
+    }
+    const { definition, decorators } = stripDecorators(stmt);
+    for (const decoratorNode of decorators) {
+      const classification = classifyDecorator(
+        decoratorNode,
+        module.moduleScope
+      );
+      if (classification.module === null) {
+        continue;
+      }
+      const decoratorModule = classification.module;
+      for (const pack of options.packs) {
+        for (const pattern of pack.discovery) {
+          units.push(
+            ...unitsFor(
+              pattern,
+              pack,
+              decoratorModule,
+              classification,
+              definition,
+              module,
+              options
+            )
+          );
+        }
+      }
+    }
+  }
+  return units;
+}
+function unitsFor(pattern, pack, decoratorModule, classification, definition, module, options) {
+  if (!pattern.importModule.includes(decoratorModule)) {
+    return [];
+  }
+  const table = {
+    decoratedClassRoute: (p) => {
+      if (definition.type !== "class_definition" || classification.importedName !== p.decoratorName) {
+        return [];
+      }
+      return classRouteUnits(
+        p,
+        pack,
+        classification,
+        definition,
+        module,
+        options
+      );
+    },
+    decoratedFunctionRoute: (p) => {
+      if (definition.type !== "function_definition") {
+        return [];
+      }
+      const verb = classification.importedName !== null ? p.verbAttributeNames[classification.importedName] : void 0;
+      if (verb === void 0) {
+        return [];
+      }
+      return functionRouteUnits(
+        p,
+        pack,
+        verb,
+        classification,
+        definition,
+        module,
+        options
+      );
+    }
+  };
+  return dispatchByType(table, pattern);
+}
+function readPathArgument(classification) {
+  const first = classification.args[0];
+  if (first?.kind === "string") {
+    return writtenReading(first.value, classification.range);
+  }
+  return unreadableReading(
+    "The path in this route's decorator is not a string literal, so the binding names no path and nothing pairs with it",
+    classification.range
+  );
+}
+var NO_PATH_PARAMS = /* @__PURE__ */ new Set();
+function templateReader(template) {
+  return (path4) => {
+    const names = [];
+    const canonical = path4.replace(template, (_match, name) => {
+      names.push(name);
+      return `{${name}}`;
+    });
+    return { path: canonical, paramNames: new Set(names) };
+  };
+}
+var PATH_TEMPLATE_READERS = {
+  braces: templateReader(/\{([A-Za-z_]\w*)(?::[A-Za-z_]\w*)?\}/g),
+  flaskConverters: templateReader(
+    /<(?:[A-Za-z_]\w*(?:\(.*?\))?:)?([A-Za-z_]\w*)>/g
+  )
+};
+function readPathTemplate(pattern, path4, range) {
+  const syntax = pattern.pathParamSyntax;
+  if (syntax === void 0) {
+    return writtenReading({ path: path4, paramNames: NO_PATH_PARAMS }, range);
+  }
+  const reader = PATH_TEMPLATE_READERS[syntax];
+  if (reader === void 0) {
+    return unreadableReading(
+      `The route's pack declares path-parameter syntax "${syntax}", which this adapter has no reader for, so the binding names no path and nothing pairs with it`,
+      range
+    );
+  }
+  return writtenReading(reader(path4), range);
+}
+function classRouteUnits(pattern, pack, classification, classNode, module, options) {
+  const pathArgument = readPathArgument(classification);
+  if (pathArgument.kind !== "written") {
+    return [];
+  }
+  const className = field(classNode, "name")?.text;
+  const bodyNode = field(classNode, "body");
+  const classScope = module.scopeFor.get(classNode.id);
+  if (className === void 0 || bodyNode === null || classScope === void 0) {
+    return [];
+  }
+  const routePath = readRoutePath(
+    pattern,
+    pathArgument,
+    classification,
+    module,
+    options
+  );
+  const units = [];
+  for (const stmt of bodyStatements(bodyNode)) {
+    const { definition: maybeMethod } = stripDecorators(stmt);
+    if (maybeMethod.type !== "function_definition") {
+      continue;
+    }
+    const methodName = field(maybeMethod, "name")?.text;
+    const verb = methodName !== void 0 ? pattern.verbMethodNames[methodName] : void 0;
+    if (verb === void 0 || methodName === void 0) {
+      continue;
+    }
+    units.push(
+      ...routeUnitOrAbstention(
+        {
+          pack,
+          name: `${className}.${methodName}`,
+          exportPath: [className, methodName],
+          method: verb,
+          routePath,
+          requestBodyFromAnnotatedClass: pattern.annotatedClassIsRequestBody === true,
+          injectedCallees: new Set(pattern.injectedParameterCallees ?? []),
+          definitionNode: maybeMethod,
+          enclosingScope: classScope,
+          module,
+          filePath: options.filePath,
+          skipReceiverParam: true,
+          responseShape: absentReading,
+          statusCode: defaultedStatus(
+            readReturnedStatus(pattern, maybeMethod),
+            pattern
+          )
+        },
+        options
+      )
+    );
+  }
+  return units;
+}
+function readRoutePath(pattern, pathArgument, classification, module, options) {
+  const composed = andThenReading(
+    pathArgument,
+    (literal, range) => composeRoutePath(pattern, classification, module, options, literal, range)
+  );
+  return andThenReading(
+    composed,
+    (path4, range) => readPathTemplate(pattern, path4, range)
+  );
+}
+function composeRoutePath(pattern, classification, module, options, literal, range) {
+  const prefix = readRouterPrefix(
+    pattern,
+    classification,
+    module,
+    options,
+    range
+  );
+  if (prefix.kind === "absent") {
+    return writtenReading(servedSpelling(pattern, literal), range);
+  }
+  return mapReading(
+    prefix,
+    (value) => servedSpelling(pattern, value + literal)
+  );
+}
+var REPEATED_SLASH_READERS = {
+  kept: (path4) => path4,
+  merged: (path4) => path4.replace(/\/{2,}/g, "/")
+};
+function servedSpelling(pattern, path4) {
+  return REPEATED_SLASH_READERS[pattern.pathRepeatedSlashes ?? "kept"](path4);
+}
+function readRouterPrefix(pattern, classification, module, options, range) {
+  if (pattern.routerComposition === void 0 || options.routerIndex === void 0 || classification.objectName === null) {
+    return absentReading;
+  }
+  const resolution = options.routerIndex.resolve(
+    pattern,
+    module,
+    classification.objectName
+  );
+  if (resolution.kind === "abstain") {
+    return unreadableReading(
+      `The router this route is declared on ${resolution.reason}, so the binding names no path and nothing pairs with it`,
+      range
+    );
+  }
+  if (resolution.kind === "composed") {
+    return writtenReading(resolution.value, range);
+  }
+  return absentReading;
+}
+function readStatusCode(pattern, classification) {
+  if (pattern.statusCodeKeyword === void 0) {
+    return absentReading;
+  }
+  const arg = classification.keywordArgs[pattern.statusCodeKeyword];
+  if (arg === void 0) {
+    return absentReading;
+  }
+  if (arg.kind === "number") {
+    return writtenReading(arg.value, classification.range);
+  }
+  return unreadableReading(
+    "The status this route's decorator states is not a literal number, so the response claims no status",
+    classification.range
+  );
+}
+function returnStatements(node, found = []) {
+  for (const child of node?.namedChildren ?? []) {
+    if (child === null) {
+      continue;
+    }
+    if (child.type === "function_definition" || child.type === "lambda") {
+      continue;
+    }
+    if (child.type === "return_statement") {
+      found.push(child);
+    }
+    returnStatements(child, found);
+  }
+  return found;
+}
+function statusFromReturnedValue(node) {
+  if (node === void 0) {
+    return null;
+  }
+  if (node.type === "integer") {
+    const parsed = Number.parseInt(node.text, 10);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  const text = stringLiteralValue(node);
+  if (text === null) {
+    return null;
+  }
+  const digits = /^(\d{3})\b/.exec(text.trim());
+  return digits === null ? null : Number.parseInt(digits[1], 10);
+}
+function statusOfReturn(statement) {
+  const returned = statement.namedChildren[0];
+  if (returned?.type !== "expression_list") {
+    return { kind: "none" };
+  }
+  const status = statusFromReturnedValue(returned.namedChildren[1]);
+  return status === null ? { kind: "unreadable" } : { kind: "status", value: status };
+}
+function readReturnedStatus(pattern, definitionNode) {
+  if (pattern.statusFromReturnedTuple !== true) {
+    return absentReading;
+  }
+  const range = rangeOf(definitionNode);
+  const statuses = /* @__PURE__ */ new Set();
+  let plainReturns = 0;
+  let unreadable = 0;
+  for (const statement of returnStatements(field(definitionNode, "body"))) {
+    const read = statusOfReturn(statement);
+    if (read.kind === "status") {
+      statuses.add(read.value);
+    } else if (read.kind === "none") {
+      plainReturns += 1;
+    } else {
+      unreadable += 1;
+    }
+  }
+  if (unreadable > 0) {
+    return unreadableReading(
+      "This route returns a status this reading cannot resolve to a number, so no status is claimed for it",
+      range
+    );
+  }
+  if (statuses.size === 0) {
+    return absentReading;
+  }
+  const candidates = [...statuses];
+  if (statuses.size > 1 || plainReturns > 0) {
+    return ambiguousReading(
+      candidates,
+      "This route returns more than one status depending on which branch runs, and nothing here reads which, so no status is claimed for it",
+      range
+    );
+  }
+  return writtenReading(candidates[0], range);
+}
+function declaredOrReturnedStatus(declared, returned) {
+  return declared.kind === "absent" ? returned : declared;
+}
+function defaultedStatus(reading, pattern) {
+  return {
+    reading,
+    ...pattern.defaultStatusCode !== void 0 ? { libraryDefault: pattern.defaultStatusCode } : {}
+  };
+}
+function readResponseModel(pattern, classification, module, ctx) {
+  if (pattern.responseModelKeyword === void 0) {
+    return absentReading;
+  }
+  const arg = classification.keywordArgs[pattern.responseModelKeyword];
+  if (arg === void 0) {
+    return absentReading;
+  }
+  if (arg.kind === "identifier") {
+    return writtenReading(
+      shapeFromName(arg.name, module.moduleScope, ctx),
+      classification.range
+    );
+  }
+  return unreadableReading(
+    "The response model this route's decorator states is not a name, so the response claims no body shape",
+    classification.range
+  );
+}
+function readReturnAnnotation(definitionNode, scope, ctx) {
+  const returnTypeNode = field(definitionNode, "return_type");
+  if (returnTypeNode === null) {
+    return absentReading;
+  }
+  return writtenReading(
+    annotationToShape(returnTypeNode, scope, ctx),
+    rangeOf(returnTypeNode)
+  );
+}
+function functionRouteUnits(pattern, pack, verb, classification, functionNode, module, options) {
+  const functionName = field(functionNode, "name")?.text;
+  if (functionName === void 0) {
+    return [];
+  }
+  const ctx = createAnnotationContext(module.scopeFor);
+  return routeUnitOrAbstention(
+    {
+      pack,
+      name: functionName,
+      exportPath: [functionName],
+      method: verb,
+      routePath: readRoutePath(
+        pattern,
+        readPathArgument(classification),
+        classification,
+        module,
+        options
+      ),
+      requestBodyFromAnnotatedClass: pattern.annotatedClassIsRequestBody === true,
+      injectedCallees: new Set(pattern.injectedParameterCallees ?? []),
+      definitionNode: functionNode,
+      enclosingScope: module.moduleScope,
+      module,
+      filePath: options.filePath,
+      skipReceiverParam: false,
+      responseShape: readResponseModel(pattern, classification, module, ctx),
+      statusCode: defaultedStatus(
+        declaredOrReturnedStatus(
+          readStatusCode(pattern, classification),
+          readReturnedStatus(pattern, functionNode)
+        ),
+        pattern
+      ),
+      definitionsCtx: ctx
+    },
+    options
+  );
+}
+function readResponseShape(declared, readAnnotation) {
+  if (declared.kind === "written") {
+    return { reading: declared, passedOver: [] };
+  }
+  return firstWrittenReading([declared, readAnnotation()]);
+}
+function routeUnitOrAbstention(unitOptions, options) {
+  try {
+    return [buildRouteUnit(unitOptions)];
+  } catch (error) {
+    if (options.gapHandling === "strict") {
+      throw error;
+    }
+    return [unbuiltRouteUnit(unitOptions, error)];
+  }
+}
+function nullIfEmpty(value) {
+  return value === "" ? null : value;
+}
+function unbuiltRouteUnit(unitOptions, error) {
+  const range = rangeOf(unitOptions.definitionNode);
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    identity: {
+      name: unitOptions.name,
+      nameKind: "binding",
+      kind: "handler",
+      file: unitOptions.filePath,
+      range,
+      exportName: unitOptions.exportPath[0] ?? unitOptions.name,
+      exportPath: unitOptions.exportPath
+    },
+    boundaryBinding: restBinding({
+      transport: unitOptions.pack.protocol,
+      method: nullIfEmpty(unitOptions.method),
+      path: null,
+      recognition: unitOptions.pack.name
+    }),
+    parameters: [],
+    branches: [],
+    bodyContent: "statements",
+    dependencyCalls: [],
+    declaredContract: null,
+    readings: [
+      unreadableReading(
+        `This route could not be read into a unit (${message}), so the binding names no path and nothing pairs with it`,
+        range
+      )
+    ]
+  };
+}
+function buildRouteUnit(options) {
+  const {
+    pack,
+    name,
+    exportPath,
+    method,
+    routePath,
+    requestBodyFromAnnotatedClass,
+    injectedCallees,
+    definitionNode,
+    enclosingScope,
+    module,
+    filePath,
+    skipReceiverParam,
+    statusCode,
+    definitionsCtx
+  } = options;
+  const template = valueToReadFurtherFrom(routePath);
+  const ctx = definitionsCtx ?? createAnnotationContext(module.scopeFor);
+  const parameters = readParameters(
+    definitionNode,
+    enclosingScope,
+    ctx,
+    template?.paramNames ?? null,
+    requestBodyFromAnnotatedClass,
+    injectedCallees,
+    skipReceiverParam
+  );
+  const responseShape = readResponseShape(
+    options.responseShape,
+    () => readReturnAnnotation(definitionNode, enclosingScope, ctx)
+  );
+  const branches = [];
+  if (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent") {
+    branches.push({
+      conditions: [],
+      terminal: {
+        kind: "response",
+        // These stay null here. The extractor fills them in from
+        // `statusCodeReading` and `bodyShapeReading` below.
+        statusCode: null,
+        body: { typeText: null, shape: null },
+        exceptionType: null,
+        message: null,
+        component: null,
+        renderTree: null,
+        delegateTarget: null,
+        emitEvent: null,
+        location: rangeOf(definitionNode)
+      },
+      statusCodeReading: statusCode,
+      bodyShapeReading: { reading: responseShape.reading },
+      effects: [],
+      location: rangeOf(definitionNode),
+      isDefault: true
+    });
+  }
+  const bodyNode = field(definitionNode, "body");
+  return {
+    identity: {
+      name,
+      nameKind: "binding",
+      kind: "handler",
+      file: filePath,
+      range: rangeOf(definitionNode),
+      exportName: exportPath[0] ?? name,
+      exportPath
+    },
+    boundaryBinding: restBinding({
+      transport: pack.protocol,
+      method,
+      path: template?.path ?? null,
+      recognition: pack.name
+    }),
+    parameters,
+    branches,
+    bodyContent: bodyNode !== null ? bodyContentOf(bodyNode) : "statements",
+    dependencyCalls: [],
+    declaredContract: null,
+    readings: [
+      routePath,
+      ...unreadRoleReadings(parameters, rangeOf(definitionNode)),
+      ...responseShape.passedOver
+    ],
+    ...collectedDefinitions(ctx) !== null ? { definitions: collectedDefinitions(ctx) } : {}
+  };
+}
+function unreadRoleReadings(parameters, range) {
+  if (!parameters.some((parameter) => parameter.role === null)) {
+    return [];
+  }
+  return [
+    unreadableReading(
+      "Nothing read this route's path, so its parameters name no role and a path parameter here does not read as one",
+      range
+    )
+  ];
+}
+function bodyContentOf(bodyNode) {
+  for (const stmt of bodyStatements(bodyNode)) {
+    if (stmt.type === "pass_statement") {
+      continue;
+    }
+    if (stmt.type === "expression_statement" && stmt.namedChild(0)?.type === "string") {
+      continue;
+    }
+    return "statements";
+  }
+  return "empty";
+}
+function readParameters(definitionNode, scope, ctx, pathParamNames, requestBodyFromAnnotatedClass, injectedCallees, skipReceiverParam) {
+  const parametersNode = field(definitionNode, "parameters");
+  if (parametersNode === null) {
+    return [];
+  }
+  const out = [];
+  let position = 0;
+  for (const param of parametersNode.namedChildren) {
+    if (param === null) {
+      continue;
+    }
+    if (skipReceiverParam && position === 0 && isReceiverParam(param)) {
+      position += 1;
+      continue;
+    }
+    const parsed = readParameter(
+      param,
+      scope,
+      ctx,
+      pathParamNames,
+      requestBodyFromAnnotatedClass,
+      injectedCallees,
+      position
+    );
+    if (parsed !== null) {
+      out.push(parsed);
+    }
+    position += 1;
+  }
+  return out;
+}
+function isReceiverParam(param) {
+  return param.type === "identifier" && (param.text === "self" || param.text === "cls");
+}
+function readParameter(param, scope, ctx, pathParamNames, requestBodyFromAnnotatedClass, injectedCallees, position) {
+  const info = parameterNameAndType(param);
+  if (info === null) {
+    return null;
+  }
+  const { name, typeNode } = info;
+  const shape = typeNode !== null ? annotationToShape(typeNode, scope, ctx) : null;
+  const role = isInjectedParameter(param, injectedCallees) ? null : roleOf(name, shape, pathParamNames, requestBodyFromAnnotatedClass);
+  return {
+    name,
+    position,
+    role,
+    typeText: typeNode !== null ? typeNode.text : null
+  };
+}
+function roleOf(name, shape, pathParamNames, requestBodyFromAnnotatedClass) {
+  if (pathParamNames?.has(name) === true) {
+    return "pathParams";
+  }
+  if (requestBodyFromAnnotatedClass && shape !== null && shape.type === "ref" && shape.def !== void 0) {
+    return "requestBody";
+  }
+  if (pathParamNames === null) {
+    return null;
+  }
+  return "queryParams";
+}
+function calleeName(call) {
+  const callee = field(call, "function");
+  if (callee === null) {
+    return null;
+  }
+  if (callee.type === "identifier") {
+    return callee.text;
+  }
+  if (callee.type === "attribute") {
+    return field(callee, "attribute")?.text ?? null;
+  }
+  return null;
+}
+function isInjectedParameter(param, injectedCallees) {
+  if (injectedCallees.size === 0) {
+    return false;
+  }
+  const callsAnInjector = (node) => {
+    if (node === null) {
+      return false;
+    }
+    const name = calleeName(node);
+    return node.type === "call" && name !== null && injectedCallees.has(name);
+  };
+  if (callsAnInjector(field(param, "value"))) {
+    return true;
+  }
+  const containsInjectorCall = (node, depth) => {
+    if (node === null || depth > 6) {
+      return false;
+    }
+    if (callsAnInjector(node)) {
+      return true;
+    }
+    return node.namedChildren.some(
+      (child) => containsInjectorCall(child, depth + 1)
+    );
+  };
+  return containsInjectorCall(field(param, "type"), 0);
+}
+function parameterNameAndType(param) {
+  if (param.type === "identifier") {
+    return { name: param.text, typeNode: null };
+  }
+  if (param.type === "typed_parameter") {
+    const inner = param.namedChildren.find(
+      (child) => child !== null && child.type === "identifier"
+    );
+    return inner !== void 0 ? { name: inner.text, typeNode: field(param, "type") } : null;
+  }
+  if (param.type === "default_parameter") {
+    const nameNode = field(param, "name");
+    return nameNode?.type === "identifier" ? { name: nameNode.text, typeNode: null } : null;
+  }
+  if (param.type === "typed_default_parameter") {
+    const nameNode = field(param, "name");
+    return nameNode !== null ? { name: nameNode.text, typeNode: field(param, "type") } : null;
+  }
+  return null;
+}
+
+// src/moduleResolver.ts
+import fs from "fs";
+import path from "path";
+function isWithinRoot(dir, root) {
+  const relative = path.relative(root, dir);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function isInsideAnyRoot(dir, roots) {
+  return roots.some((root) => isWithinRoot(dir, root));
+}
+function candidatesUnderRoot(root, dotted) {
+  if (dotted === "") {
+    const initFile = path.join(root, "__init__.py");
+    return fs.existsSync(initFile) ? [initFile] : [];
+  }
+  const base = path.join(root, ...dotted.split("."));
+  const found = [];
+  const moduleFile = `${base}.py`;
+  if (fs.existsSync(moduleFile)) {
+    found.push(moduleFile);
+  }
+  const packageFile = path.join(base, "__init__.py");
+  if (fs.existsSync(packageFile)) {
+    found.push(packageFile);
+  }
+  return found;
+}
+function resolveAbsoluteModule(dotted, options) {
+  const byRoot = [];
+  for (const root of options.roots) {
+    const candidates = candidatesUnderRoot(root, dotted);
+    if (candidates.length > 0) {
+      byRoot.push(candidates[0]);
+    }
+  }
+  if (byRoot.length === 0) {
+    return { status: "unresolved", reason: "external" };
+  }
+  if (byRoot.length > 1) {
+    return { status: "unresolved", reason: "ambiguous" };
+  }
+  return { status: "resolved", file: byRoot[0] };
+}
+function resolveRelativeModule(importingFile, spec, options) {
+  let dir = path.dirname(importingFile);
+  if (!isInsideAnyRoot(dir, options.roots)) {
+    return { status: "unresolved", reason: "outsideRoots" };
+  }
+  for (let i = 1; i < spec.relativeLevel; i++) {
+    dir = path.dirname(dir);
+    if (!isInsideAnyRoot(dir, options.roots)) {
+      return { status: "unresolved", reason: "outsideRoots" };
+    }
+  }
+  const candidates = candidatesUnderRoot(dir, spec.module);
+  if (candidates.length === 0) {
+    return { status: "unresolved", reason: "external" };
+  }
+  return { status: "resolved", file: candidates[0] };
+}
+function resolveModule(importingFile, spec, options) {
+  if (spec.relativeLevel > 0) {
+    return resolveRelativeModule(importingFile, spec, options);
+  }
+  return resolveAbsoluteModule(spec.module, options);
+}
+
+// src/facts.ts
+function unitKey(filePath, range, name) {
+  return `${filePath}:${range.start}-${range.end}#${name}`;
+}
+function emitEntryFact(db, filePath, range, name) {
+  db.add("entry", [unitKey(filePath, range, name)]);
+}
+function importedModuleText(module, relativeLevel) {
+  return relativeLevel > 0 ? `${".".repeat(relativeLevel)}${module}` : module;
+}
+function emitModuleImportFacts(db, filePath, module, resolverOptions) {
+  for (const binding of module.moduleScope.bindings.values()) {
+    if (binding.kind !== "import" && binding.kind !== "importFrom") {
+      continue;
+    }
+    const moduleText = importedModuleText(
+      binding.module,
+      binding.relativeLevel
+    );
+    const resolution = resolveModule(
+      filePath,
+      { module: binding.module, relativeLevel: binding.relativeLevel },
+      resolverOptions
+    );
+    db.add("pyImport", [
+      filePath,
+      moduleText,
+      resolution.status === "resolved" ? "resolved" : resolution.reason
+    ]);
+    if (resolution.status === "resolved") {
+      db.add("pyImportResolved", [filePath, moduleText, resolution.file]);
+    }
+  }
+  for (const openModule of module.openImports) {
+    db.add("pyOpenImport", [filePath, openModule]);
+  }
+}
+
+// src/parser.ts
+import fs2 from "fs";
+import path2 from "path";
+import { fileURLToPath } from "url";
+import { Language, Parser } from "web-tree-sitter";
+var GRAMMAR_PATH = path2.join(
+  path2.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "grammar",
+  "tree-sitter-python.wasm"
+);
+var languagePromise = null;
+function loadLanguage() {
+  languagePromise ??= (async () => {
+    if (!fs2.existsSync(GRAMMAR_PATH)) {
+      throw new Error(
+        `Python grammar not found at ${GRAMMAR_PATH}. See grammar/README.md.`
+      );
+    }
+    await Parser.init();
+    return Language.load(GRAMMAR_PATH);
+  })();
+  return languagePromise;
+}
+async function parsePython(source) {
+  const language = await loadLanguage();
+  const parser = new Parser();
+  parser.setLanguage(language);
+  try {
+    const tree = parser.parse(source);
+    if (tree === null) {
+      throw new Error("tree-sitter produced no tree for this source");
+    }
+    return tree;
+  } finally {
+    parser.delete();
+  }
+}
+
+// src/project.ts
+import fs3 from "fs";
+import path3 from "path";
+import { Database } from "@suss/datalog";
+import { assembleSummary } from "@suss/extractor";
+
+// src/routers.ts
+var UNSTATED_PREFIX = { kind: "unstated" };
+var UNREADABLE_PREFIX = { kind: "unreadable" };
+var MODULE_SITE = { kind: "module" };
+var NOT_ROUTER = { kind: "notRouter" };
+function buildRouterIndex(files, packs, resolverOptions) {
+  const byPattern = /* @__PURE__ */ new Map();
+  for (const pack of packs) {
+    for (const pattern of pack.discovery) {
+      if (pattern.routerComposition !== void 0) {
+        byPattern.set(
+          pattern,
+          buildPatternIndex(
+            files,
+            pattern.importModule,
+            pattern.routerComposition,
+            resolverOptions
+          )
+        );
+      }
+    }
+  }
+  return {
+    resolve(pattern, module, objectName) {
+      const index = byPattern.get(pattern);
+      if (index === void 0) {
+        return NOT_ROUTER;
+      }
+      const construction = index.constructions.get(module)?.get(objectName);
+      if (construction === void 0) {
+        return declaredOnMountObject(index, module, objectName);
+      }
+      if (construction.reassigned) {
+        return {
+          kind: "abstain",
+          reason: "shares its variable name with a second router construction"
+        };
+      }
+      const ownPrefix = composedOwnPrefix(
+        construction.prefix,
+        index.composition
+      );
+      if (ownPrefix.kind === "abstain") {
+        return ownPrefix;
+      }
+      const mount = index.mounts.get(construction);
+      if (mount === void 0) {
+        return { kind: "abstain", reason: unmountedReason(index) };
+      }
+      if (mount.kind === "abstain") {
+        return { kind: "abstain", reason: mount.reason };
+      }
+      const rivalled = rivalRegistration(index, mount.site);
+      if (rivalled !== null) {
+        return { kind: "abstain", reason: rivalled };
+      }
+      return {
+        kind: "composed",
+        value: mount.includePrefix + ownPrefix.value
+      };
+    }
+  };
+}
+function declaredOnMountObject(index, module, objectName) {
+  const objectPrefix = index.objectPrefixes.get(module)?.get(objectName);
+  if (objectPrefix === void 0) {
+    return NOT_ROUTER;
+  }
+  if (objectPrefix.kind === "composed" && objectPrefix.value === "") {
+    return NOT_ROUTER;
+  }
+  return objectPrefix;
+}
+function sameSite(one, other) {
+  if (one.kind === "function" && other.kind === "function") {
+    return one.node === other.node;
+  }
+  return one.kind === other.kind;
+}
+function loopsClause(loops, verb) {
+  const locations = loops.map((loop) => loop.location).sort();
+  if (locations.length === 1) {
+    return `a loop at ${locations[0]} ${verb}s`;
+  }
+  return `loops at ${locations.join(", ")} ${verb}`;
+}
+function unmountedReason(index) {
+  const loops = [...index.unenumerableLoops.values()];
+  if (loops.length === 0) {
+    return "is never mounted through a single variable binding in the files read";
+  }
+  return `is not mounted by name in the files read, and ${loopsClause(loops, "mount")} routers read out of a call this reading does not follow`;
+}
+function rivalRegistration(index, site) {
+  if (site.kind === "module") {
+    return null;
+  }
+  const rivals = [...index.unenumerableLoops.values()].filter(
+    (loop) => !sameSite(loop.site, site)
+  );
+  if (rivals.length === 0) {
+    return null;
+  }
+  return `is mounted inside a function, while ${loopsClause(rivals, "mount")} routers this reading cannot name, and which of them the app runs is not written down`;
+}
+function composedOwnPrefix(prefix, composition) {
+  const readings = {
+    stated: (reading) => ({
+      kind: "composed",
+      value: reading.kind === "stated" ? reading.value : ""
+    }),
+    unreadable: () => ({
+      kind: "abstain",
+      reason: "declares a prefix that is not a string literal"
+    }),
+    unstated: () => {
+      if (composition.constructorPrefixRequired === true) {
+        return {
+          kind: "abstain",
+          reason: "states no prefix where it is constructed, and its library derives one from elsewhere"
+        };
+      }
+      return { kind: "composed", value: "" };
+    }
+  };
+  return readings[prefix.kind](prefix);
+}
+function buildPatternIndex(files, importModule, composition, resolverOptions) {
+  const index = {
+    composition,
+    constructions: /* @__PURE__ */ new Map(),
+    mounts: /* @__PURE__ */ new Map(),
+    unenumerableLoops: /* @__PURE__ */ new Map(),
+    carriers: /* @__PURE__ */ new Map(),
+    carrierRegistrations: /* @__PURE__ */ new Map(),
+    handoffs: /* @__PURE__ */ new Map(),
+    objectPrefixes: /* @__PURE__ */ new Map()
+  };
+  const byFile = new Map(files.map((bound) => [bound.file, bound]));
+  const scanOf = (bound) => ({
+    bound,
+    byFile,
+    importModule,
+    composition,
+    resolverOptions,
+    index
+  });
+  const objectPrefix = composition.mountObjectPrefix;
+  for (const bound of files) {
+    collectConstructions(bound, importModule, composition, index);
+  }
+  if (objectPrefix?.carrier !== void 0) {
+    const carrier = objectPrefix.carrier;
+    for (const bound of files) {
+      collectCarrierConstructions(carrier, composition, scanOf(bound));
+    }
+    for (const bound of files) {
+      collectCarrierCalls(carrier, scanOf(bound));
+    }
+  }
+  if (objectPrefix !== void 0) {
+    for (const bound of files) {
+      collectObjectPrefixes(objectPrefix, scanOf(bound));
+    }
+  }
+  for (const bound of files) {
+    collectMounts(
+      bound,
+      byFile,
+      importModule,
+      composition,
+      resolverOptions,
+      index
+    );
+  }
+  return index;
+}
+function constructionOf(name, scope, importModule) {
+  const binding = resolveName(scope, name);
+  if (binding?.kind !== "assignment" || binding.value?.type !== "call") {
+    return null;
+  }
+  const callee = field(binding.value, "function");
+  if (callee?.type !== "identifier") {
+    return null;
+  }
+  const calleeBinding = resolveName(scope, callee.text);
+  if (calleeBinding?.kind !== "importFrom" || !importModule.includes(calleeBinding.module)) {
+    return null;
+  }
+  return { constructorName: calleeBinding.importedName, call: binding.value };
+}
+var PREFIX_TRAILING_SLASH_READERS = {
+  kept: (prefix) => prefix,
+  trimmed: (prefix) => prefix.replace(/\/+$/, "")
+};
+var NO_VALUE_LITERALS = {
+  string: (arg) => arg.kind === "string" && arg.value === "",
+  number: (arg) => arg.kind === "number" && arg.value === 0,
+  boolean: (arg) => arg.kind === "boolean" && !arg.value,
+  none: () => true
+};
+function readPrefixKeyword(keywordArgs, keyword, composition) {
+  const arg = keywordArgs[keyword];
+  if (arg === void 0) {
+    return UNSTATED_PREFIX;
+  }
+  if ((composition.noValuePrefix ?? "unreadable") === "unstated" && NO_VALUE_LITERALS[arg.kind]?.(arg) === true) {
+    return UNSTATED_PREFIX;
+  }
+  if (arg.kind === "string") {
+    return { kind: "stated", value: arg.value };
+  }
+  return UNREADABLE_PREFIX;
+}
+function constructorPrefix(keywordArgs, composition) {
+  const reading = readPrefixKeyword(
+    keywordArgs,
+    composition.prefixKeyword,
+    composition
+  );
+  if (reading.kind !== "stated") {
+    return reading;
+  }
+  const trailingSlash = composition.constructorPrefixTrailingSlash ?? "kept";
+  return {
+    kind: "stated",
+    value: PREFIX_TRAILING_SLASH_READERS[trailingSlash](reading.value)
+  };
+}
+function constructionStatement(stmt, scope, importModule) {
+  if (stmt.type !== "expression_statement") {
+    return null;
+  }
+  const assignment = stmt.namedChildren.find(
+    (child) => child !== null && child.type === "assignment"
+  );
+  if (assignment === void 0) {
+    return null;
+  }
+  const left = field(assignment, "left");
+  const right = field(assignment, "right");
+  if (left?.type !== "identifier" || right?.type !== "call") {
+    return null;
+  }
+  const callee = field(right, "function");
+  if (callee?.type !== "identifier") {
+    return null;
+  }
+  const calleeBinding = resolveName(scope, callee.text);
+  if (calleeBinding?.kind !== "importFrom" || !importModule.includes(calleeBinding.module)) {
+    return null;
+  }
+  return {
+    name: left.text,
+    constructorName: calleeBinding.importedName,
+    call: right
+  };
+}
+function recordConstruction(construction, module, prefixOf, into) {
+  const perModule = into.get(module) ?? /* @__PURE__ */ new Map();
+  into.set(module, perModule);
+  const existing = perModule.get(construction.name);
+  if (existing !== void 0) {
+    existing.reassigned = true;
+    return;
+  }
+  const { keywordArgs } = readCallArguments(
+    field(construction.call, "arguments")
+  );
+  perModule.set(construction.name, {
+    constructorName: construction.constructorName,
+    prefix: prefixOf(keywordArgs),
+    reassigned: false
+  });
+}
+function collectConstructions(bound, importModule, composition, index) {
+  for (const stmt of bodyStatements(bound.root)) {
+    const construction = constructionStatement(
+      stmt,
+      bound.module.moduleScope,
+      importModule
+    );
+    if (construction === null || construction.constructorName !== composition.routerConstructorName) {
+      continue;
+    }
+    recordConstruction(
+      construction,
+      bound.module,
+      (keywordArgs) => constructorPrefix(keywordArgs, composition),
+      index.constructions
+    );
+  }
+}
+function collectCarrierConstructions(carrier, composition, scan) {
+  walkStatements(
+    bodyStatements(scan.bound.root),
+    modulePosition(scan),
+    scan,
+    (stmt, position) => {
+      const construction = constructionStatement(
+        stmt,
+        position.scope,
+        carrier.importModule
+      );
+      if (construction === null) {
+        return;
+      }
+      recordConstruction(
+        construction,
+        scan.bound.module,
+        (keywordArgs) => readPrefixKeyword(keywordArgs, carrier.prefixKeyword, composition),
+        scan.index.carriers
+      );
+    }
+  );
+}
+function constructionNamed(name, scope, scan, constructions = scan.index.constructions) {
+  const binding = resolveName(scope, name);
+  if (binding === null) {
+    return null;
+  }
+  const resolvers = {
+    assignment: () => constructions.get(scan.bound.module)?.get(name) ?? null,
+    importFrom: () => {
+      if (binding.kind !== "importFrom") {
+        return null;
+      }
+      const resolution = resolveModule(
+        scan.bound.file,
+        { module: binding.module, relativeLevel: binding.relativeLevel },
+        scan.resolverOptions
+      );
+      if (resolution.status !== "resolved") {
+        return null;
+      }
+      const target = scan.byFile.get(resolution.file);
+      if (target === void 0) {
+        return null;
+      }
+      return constructions.get(target.module)?.get(binding.importedName) ?? null;
+    }
+  };
+  return resolvers[binding.kind]?.() ?? null;
+}
+var MOUNT_STATE_BY_EFFECT = {
+  prefixes: (statedPrefix, site) => ({
+    kind: "mounted",
+    includePrefix: statedPrefix,
+    site
+  }),
+  replaces: () => ({
+    kind: "abstain",
+    reason: "is mounted under a prefix that replaces the one it was constructed with, which this reading does not follow"
+  })
+};
+function recordMount(index, target, state) {
+  if (index.mounts.has(target)) {
+    index.mounts.set(target, {
+      kind: "abstain",
+      reason: "is mounted more than once"
+    });
+    return;
+  }
+  index.mounts.set(target, state);
+}
+function collectMounts(bound, byFile, importModule, composition, resolverOptions, index) {
+  const scan = {
+    bound,
+    byFile,
+    importModule,
+    composition,
+    resolverOptions,
+    index
+  };
+  walkStatements(
+    bodyStatements(bound.root),
+    modulePosition(scan),
+    scan,
+    recordMountStatement
+  );
+}
+function modulePosition(scan) {
+  return {
+    scope: scan.bound.module.moduleScope,
+    loopBindings: /* @__PURE__ */ new Map(),
+    site: MODULE_SITE
+  };
+}
+var WALK_DESCENTS = {
+  decorated_definition: (stmt, position, scan, visit) => {
+    walkStatements([stripDecorators(stmt).definition], position, scan, visit);
+  },
+  function_definition: (stmt, position, scan, visit) => {
+    const scope = scan.bound.module.scopeFor.get(stmt.id);
+    if (scope === void 0) {
+      return;
+    }
+    walkStatements(
+      nestedStatements(stmt),
+      {
+        scope,
+        loopBindings: /* @__PURE__ */ new Map(),
+        site: { kind: "function", node: stmt.id }
+      },
+      scan,
+      visit
+    );
+  },
+  for_statement: (stmt, position, scan, visit) => {
+    walkStatements(
+      nestedStatements(stmt),
+      { ...position, loopBindings: loopBindingsOf(stmt, position, scan) },
+      scan,
+      visit
+    );
+  }
+};
+function nestedStatements(stmt) {
+  const body = field(stmt, "body");
+  return body === null ? [] : bodyStatements(body);
+}
+function walkStatements(statements, position, scan, visit) {
+  for (const stmt of statements) {
+    const descend = WALK_DESCENTS[stmt.type];
+    if (descend !== void 0) {
+      descend(stmt, position, scan, visit);
+      continue;
+    }
+    visit(stmt, position, scan);
+  }
+}
+function targetNames(node) {
+  if (node.type === "identifier") {
+    return [node.text];
+  }
+  return bodyStatements(node).flatMap(targetNames);
+}
+function sequenceElementNames(node) {
+  if (node === null || node.type !== "list" && node.type !== "tuple") {
+    return null;
+  }
+  const names = [];
+  for (const child of node.namedChildren) {
+    if (child?.type !== "identifier") {
+      return null;
+    }
+    names.push(child.text);
+  }
+  return names;
+}
+function loopBindingsOf(stmt, position, scan) {
+  const bindings = new Map(position.loopBindings);
+  const left = field(stmt, "left");
+  if (left === null) {
+    return bindings;
+  }
+  const elements = sequenceElementNames(field(stmt, "right"));
+  if (left.type === "identifier" && elements !== null) {
+    bindings.set(left.text, { kind: "sequence", elements });
+    return bindings;
+  }
+  const location = `${scan.bound.displayPath}:${rangeOf(stmt).start}`;
+  for (const name of targetNames(left)) {
+    bindings.set(name, { kind: "unenumerable", location });
+  }
+  return bindings;
+}
+function mountCallOf(stmt, scope, scan) {
+  if (stmt.type !== "expression_statement") {
+    return null;
+  }
+  const call = stmt.namedChild(0);
+  if (call === null || call.type !== "call") {
+    return null;
+  }
+  const callee = field(call, "function");
+  if (callee === null || callee.type !== "attribute") {
+    return null;
+  }
+  const objectNode = field(callee, "object");
+  const attributeNode = field(callee, "attribute");
+  if (objectNode?.type !== "identifier" || attributeNode?.text !== scan.composition.includeMethodName) {
+    return null;
+  }
+  const includer = constructionOf(objectNode.text, scope, scan.importModule);
+  if (includer === null) {
+    return null;
+  }
+  return {
+    call,
+    objectName: objectNode.text,
+    includerConstructorName: includer.constructorName,
+    includerCall: includer.call
+  };
+}
+function mountedNames(arg, position, index) {
+  if (arg?.kind !== "identifier") {
+    return [];
+  }
+  const target = position.loopBindings.get(arg.name);
+  if (target === void 0) {
+    return [arg.name];
+  }
+  if (target.kind === "sequence") {
+    return target.elements;
+  }
+  index.unenumerableLoops.set(target.location, {
+    site: position.site,
+    location: target.location
+  });
+  return [];
+}
+function recordMountStatement(stmt, position, scan) {
+  const mountCall = mountCallOf(stmt, position.scope, scan);
+  if (mountCall === null) {
+    return;
+  }
+  const { args, keywordArgs } = readCallArguments(
+    field(mountCall.call, "arguments")
+  );
+  const objectPrefix = mountObjectPrefix(
+    mountCall.objectName,
+    mountCall.includerCall,
+    position.scope,
+    scan
+  );
+  const state = mountStateOf(
+    mountCall.includerConstructorName,
+    keywordArgs,
+    objectPrefix,
+    scan.composition,
+    position.site
+  );
+  for (const name of mountedNames(args[0], position, scan.index)) {
+    const target = constructionNamed(name, position.scope, scan);
+    if (target !== null) {
+      recordMount(scan.index, target, state);
+    }
+  }
+}
+function mountStateOf(includerConstructorName, keywordArgs, objectPrefix, composition, site) {
+  if (includerConstructorName === composition.routerConstructorName) {
+    return {
+      kind: "abstain",
+      reason: "is mounted onto another router, one hop past what this reading follows"
+    };
+  }
+  if (objectPrefix.kind === "abstain") {
+    return {
+      kind: "abstain",
+      reason: `is mounted on an object that ${objectPrefix.reason}`
+    };
+  }
+  const mountPrefix = readPrefixKeyword(
+    keywordArgs,
+    composition.prefixKeyword,
+    composition
+  );
+  if (mountPrefix.kind === "unreadable") {
+    return {
+      kind: "abstain",
+      reason: "is mounted with a prefix that is not a string literal"
+    };
+  }
+  if (mountPrefix.kind === "unstated") {
+    return { kind: "mounted", includePrefix: objectPrefix.value, site };
+  }
+  const effect = composition.mountPrefixEffect ?? "prefixes";
+  const state = MOUNT_STATE_BY_EFFECT[effect](mountPrefix.value, site);
+  if (state.kind === "abstain") {
+    return state;
+  }
+  return { ...state, includePrefix: objectPrefix.value + state.includePrefix };
+}
+function collectCarrierCalls(carrier, scan) {
+  walkStatements(
+    bodyStatements(scan.bound.root),
+    modulePosition(scan),
+    scan,
+    (stmt, position) => {
+      const call = attributeCallOf(stmt);
+      if (call === null) {
+        return;
+      }
+      if (call.attribute === carrier.handoffMethodName) {
+        recordHandoff(call, scan);
+        return;
+      }
+      if (call.attribute === carrier.registerMethodName) {
+        recordRegistrationCall(call, carrier, position, scan);
+      }
+    }
+  );
+}
+function attributeCallOf(stmt) {
+  if (stmt.type !== "expression_statement") {
+    return null;
+  }
+  const call = stmt.namedChild(0);
+  if (call === null || call.type !== "call") {
+    return null;
+  }
+  const callee = field(call, "function");
+  if (callee === null || callee.type !== "attribute") {
+    return null;
+  }
+  const objectNode = field(callee, "object");
+  const attributeNode = field(callee, "attribute");
+  if (objectNode?.type !== "identifier" || attributeNode === null) {
+    return null;
+  }
+  return {
+    objectName: objectNode.text,
+    attribute: attributeNode.text,
+    ...readCallArguments(field(call, "arguments"))
+  };
+}
+function recordHandoff(call, scan) {
+  const perModule = scan.index.handoffs.get(scan.bound.module) ?? /* @__PURE__ */ new Map();
+  scan.index.handoffs.set(scan.bound.module, perModule);
+  const handed = perModule.get(call.objectName) ?? [];
+  if (call.args[0] !== void 0) {
+    handed.push(call.args[0]);
+  }
+  perModule.set(call.objectName, handed);
+}
+function recordRegistrationCall(call, carrier, position, scan) {
+  const arg = call.args[0];
+  if (arg?.kind !== "identifier" || position.loopBindings.has(arg.name)) {
+    return;
+  }
+  const target = constructionNamed(
+    arg.name,
+    position.scope,
+    scan,
+    scan.index.carriers
+  );
+  if (target === null || target.constructorName !== carrier.constructorName) {
+    return;
+  }
+  recordRegistration(
+    scan.index,
+    target,
+    registrationState(call, carrier, position, scan)
+  );
+}
+function registrationState(call, carrier, position, scan) {
+  if (call.keywordArgs[carrier.prefixKeyword] !== void 0) {
+    return {
+      kind: "abstain",
+      reason: "is built from one registered under a prefix stated where it is registered"
+    };
+  }
+  const host = constructionNamed(
+    call.objectName,
+    position.scope,
+    scan,
+    scan.index.carriers
+  );
+  if (host !== null && host.constructorName === carrier.constructorName) {
+    return {
+      kind: "abstain",
+      reason: "is built from one registered inside another, one hop past what this reading follows"
+    };
+  }
+  return { kind: "asBuilt" };
+}
+function recordRegistration(index, target, state) {
+  if (index.carrierRegistrations.has(target)) {
+    index.carrierRegistrations.set(target, {
+      kind: "abstain",
+      reason: "is built from one registered more than once"
+    });
+    return;
+  }
+  index.carrierRegistrations.set(target, state);
+}
+function collectObjectPrefixes(spec, scan) {
+  for (const stmt of bodyStatements(scan.bound.root)) {
+    const construction = constructionStatement(
+      stmt,
+      scan.bound.module.moduleScope,
+      scan.importModule
+    );
+    if (construction === null || construction.constructorName === scan.composition.routerConstructorName) {
+      continue;
+    }
+    const perModule = scan.index.objectPrefixes.get(scan.bound.module) ?? /* @__PURE__ */ new Map();
+    scan.index.objectPrefixes.set(scan.bound.module, perModule);
+    perModule.set(
+      construction.name,
+      readMountObjectPrefix(
+        spec,
+        construction.name,
+        construction.call,
+        scan.bound.module.moduleScope,
+        scan
+      )
+    );
+  }
+}
+function mountObjectPrefix(objectName, constructionCall, scope, scan) {
+  const spec = scan.composition.mountObjectPrefix;
+  if (spec === void 0) {
+    return { kind: "composed", value: "" };
+  }
+  return readMountObjectPrefix(spec, objectName, constructionCall, scope, scan);
+}
+function readMountObjectPrefix(spec, objectName, constructionCall, scope, scan) {
+  const { args, keywordArgs } = readCallArguments(
+    field(constructionCall, "arguments")
+  );
+  const own = spec.prefixKeyword === void 0 ? UNSTATED_PREFIX : readPrefixKeyword(keywordArgs, spec.prefixKeyword, scan.composition);
+  if (own.kind === "unreadable") {
+    return {
+      kind: "abstain",
+      reason: "states a prefix of its own that is not a string literal"
+    };
+  }
+  const carried = spec.carrier === void 0 ? { kind: "composed", value: "" } : carrierPrefix(
+    spec.carrier,
+    args[spec.carrier.argumentIndex],
+    objectName,
+    scope,
+    scan
+  );
+  if (carried.kind === "abstain") {
+    return carried;
+  }
+  return {
+    kind: "composed",
+    value: carried.value + (own.kind === "stated" ? own.value : "")
+  };
+}
+function carrierPrefix(carrier, constructorArg, objectName, scope, scan) {
+  const handed = scan.index.handoffs.get(scan.bound.module)?.get(objectName) ?? [];
+  const candidates = [
+    ...constructorArg === void 0 ? [] : [constructorArg],
+    ...handed
+  ];
+  if (candidates.length > 1) {
+    return { kind: "abstain", reason: "is built from more than one candidate" };
+  }
+  const candidate = candidates[0];
+  if (candidate === void 0) {
+    return { kind: "composed", value: "" };
+  }
+  if (candidate.kind !== "identifier") {
+    return {
+      kind: "abstain",
+      reason: "is built from something this reading cannot follow"
+    };
+  }
+  const construction = constructionNamed(
+    candidate.name,
+    scope,
+    scan,
+    scan.index.carriers
+  );
+  if (construction === null) {
+    return {
+      kind: "abstain",
+      reason: "is built from something this reading cannot follow"
+    };
+  }
+  if (construction.constructorName !== carrier.constructorName) {
+    return { kind: "composed", value: "" };
+  }
+  if (construction.reassigned) {
+    return {
+      kind: "abstain",
+      reason: "is built from one whose variable name holds a second construction"
+    };
+  }
+  const registration = scan.index.carrierRegistrations.get(construction);
+  if (registration?.kind === "abstain") {
+    return { kind: "abstain", reason: registration.reason };
+  }
+  const readings = {
+    stated: () => ({
+      kind: "composed",
+      value: construction.prefix.kind === "stated" ? construction.prefix.value : ""
+    }),
+    unstated: () => ({ kind: "composed", value: "" }),
+    unreadable: () => ({
+      kind: "abstain",
+      reason: "is built from one whose prefix is not a string literal"
+    })
+  };
+  return readings[construction.prefix.kind]();
+}
+
+// src/project.ts
+async function extractPythonProject(options) {
+  const db = new Database();
+  const summaries = [];
+  const gapHandling = options.gapHandling ?? "permissive";
+  const displayPathOf = (file) => options.workspaceRoot !== void 0 ? path3.relative(options.workspaceRoot, file) : file;
+  const bound = [];
+  for (const file of options.files) {
+    const source = fs3.readFileSync(file, "utf8");
+    const tree = await parsePython(source);
+    bound.push({
+      file,
+      displayPath: displayPathOf(file),
+      root: tree.rootNode,
+      module: bindModule(tree.rootNode)
+    });
+  }
+  const routerIndex = buildRouterIndex(bound, options.packs, {
+    roots: options.roots
+  });
+  for (const { file, root, module: moduleBinding } of bound) {
+    const displayPath = displayPathOf(file);
+    const rawUnits = discoverUnits(root, moduleBinding, {
+      packs: options.packs,
+      filePath: displayPath,
+      routerIndex,
+      gapHandling
+    });
+    for (const raw of rawUnits) {
+      const summary = assembleSummary(raw, { gapHandling });
+      summary.confidence = { source: "inferred_static", level: "low" };
+      summaries.push(summary);
+      emitEntryFact(db, file, raw.identity.range, raw.identity.name);
+    }
+    emitModuleImportFacts(db, file, moduleBinding, { roots: options.roots });
+  }
+  return { summaries, facts: db };
+}
+var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
+  "__pycache__",
+  ".venv",
+  "venv",
+  "node_modules",
+  ".git"
+]);
+function findPythonFiles(root) {
+  const found = [];
+  const walk = (dir) => {
+    for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRECTORIES.has(entry.name)) {
+          walk(path3.join(dir, entry.name));
+        }
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith(".py")) {
+        found.push(path3.join(dir, entry.name));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+export {
+  annotationToShape,
+  bindModule,
+  buildRouterIndex,
+  classifyDecorator,
+  discoverUnits,
+  emitEntryFact,
+  emitModuleImportFacts,
+  extractPythonProject,
+  findPythonFiles,
+  parsePython,
+  resolveAbsoluteModule,
+  resolveModule,
+  resolveName,
+  resolveRelativeModule,
+  shapeFromName,
+  unitKey
+};