clast-ai 0.1.2 → 0.2.0

package/src/parser/returns.ts

@@ -0,0 +1,137 @@
+import { typeName } from './spec.js';
+
+/**
+ * Best-effort return type of a function from its signature text. Used to
+ * type call chains (`a.b().c()`): the receiver of `c` is whatever `b`
+ * returns. Purely syntactic; returns null when unsure.
+ *
+ * `selfType` is the enclosing class, substituted for Self / self / static /
+ * this (fluent builders).
+ */
+export function returnTypeOf(
+  signature: string,
+  name: string,
+  lang: string,
+  selfType: string | null,
+  allowLowercase: boolean
+): string | null {
+  const raw = rawReturnType(signature, name, lang);
+  if (!raw) return null;
+  const text = raw.trim();
+  if (/^(&\s*(mut\s+)?)?(Self|self|static|\$this|this)\b/.test(text)) return selfType;
+  // Result<T, E> / (T, error): the interesting part is T.
+  const result = /^(?:\w+::)*Result\s*<\s*(.+)$/s.exec(text);
+  const inner = result ? firstTypeArg(result[1]!) : text.startsWith('(') ? firstTypeArg(text.slice(1)) : text;
+  if (/^(&\s*(mut\s+)?)?(Self|self|static)\b/.test(inner.trim())) return selfType;
+  return typeName(inner, allowLowercase);
+}
+
+function firstTypeArg(text: string): string {
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '<' || ch === '(' || ch === '[') depth++;
+    else if (ch === '>' || ch === ')' || ch === ']') {
+      if (depth === 0) return text.slice(0, i);
+      depth--;
+    } else if (ch === ',' && depth === 0) return text.slice(0, i);
+  }
+  return text;
+}
+
+/** Index just past the parameter list that follows `name` in `sig`, or -1. */
+function afterParams(sig: string, name: string): number {
+  let from = 0;
+  for (;;) {
+    const at = sig.indexOf(name, from);
+    if (at === -1) return -1;
+    let i = at + name.length;
+    // optional generic parameters between the name and '('
+    while (i < sig.length && /\s/.test(sig[i]!)) i++;
+    if (sig[i] === '<' || sig[i] === '[') {
+      const open = sig[i]!;
+      const close = open === '<' ? '>' : ']';
+      let depth = 0;
+      for (; i < sig.length; i++) {
+        if (sig[i] === open) depth++;
+        else if (sig[i] === close && --depth === 0) { i++; break; }
+      }
+      while (i < sig.length && /\s/.test(sig[i]!)) i++;
+    }
+    if (sig[i] === '(') {
+      let depth = 0;
+      for (; i < sig.length; i++) {
+        if (sig[i] === '(') depth++;
+        else if (sig[i] === ')' && --depth === 0) return i + 1;
+      }
+      return -1;
+    }
+    from = at + name.length;
+  }
+}
+
+function rawReturnType(sig: string, name: string, lang: string): string | null {
+  switch (lang) {
+    case 'python': {
+      const m = /->\s*([^:]+?)\s*:?\s*$/.exec(sig);
+      return m ? m[1]!.replace(/^["']|["']$/g, '') : null;
+    }
+    case 'rust':
+    case 'swift': {
+      const end = afterParams(sig, name);
+      if (end === -1) return null;
+      // Swift: `func f() async throws -> T`, `throws(MyError) -> T`.
+      const m = /^\s*(?:(?:async|rethrows|throws(?:\([^)]*\))?)\s+)*->\s*(.+?)(?:\s+where\b.*)?$/s.exec(sig.slice(end));
+      if (!m) return null;
+      // `(any Foo)?` / `any Foo` / `some Foo` -> Foo
+      return m[1]!.replace(/^\((?:any|some)\s+([^()]+)\)/, '$1').replace(/^(?:any|some)\s+/, '');
+    }
+    case 'typescript':
+    case 'tsx':
+    case 'php':
+    case 'kotlin': {
+      const end = afterParams(sig, name);
+      const tail = end !== -1 ? sig.slice(end) : (/\)\s*(:.*)$/s.exec(sig)?.[1] ?? '');
+      const m = /^\s*:\s*([^={]+?)\s*(=>)?\s*$/s.exec(tail);
+      return m ? m[1]! : null;
+    }
+    case 'go': {
+      const end = afterParams(sig, name);
+      if (end === -1) return null;
+      const rest = sig.slice(end).trim();
+      return rest ? rest : null;
+    }
+    case 'java':
+    case 'csharp':
+    case 'dart':
+    case 'c':
+    case 'cpp': {
+      // <modifiers> <ReturnType> [Class::]name(...)
+      const at = sig.search(new RegExp('(?:[\\w~]+\\s*::\\s*)*\\b' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*(?:<[^()]*>)?\\s*\\('));
+      if (at <= 0) return null;
+      let head = sig
+        .slice(0, at)
+        .replace(/@\w+(\([^)]*\))?/g, ' ')
+        .replace(/\[[^\]]*\]/g, ' ')
+        .replace(/\btemplate\s*<[^>]*>/g, ' ')
+        .trim();
+      if (!head) return null;
+      // The trailing type expression, balancing <>.
+      let depth = 0;
+      let i = head.length - 1;
+      for (; i >= 0; i--) {
+        const ch = head[i]!;
+        if (ch === '>') depth++;
+        else if (ch === '<') depth--;
+        else if (/\s/.test(ch) && depth === 0) break;
+      }
+      head = head.slice(i + 1);
+      if (/^(public|private|protected|static|final|virtual|inline|override|async|abstract|explicit|constexpr|new|return|void)$/.test(head)) {
+        return null;
+      }
+      return head;
+    }
+    default:
+      return null;
+  }
+}

package/src/parser/spec.ts

@@ -0,0 +1,309 @@
+import type { Node } from 'web-tree-sitter';
+import type { SymbolKind } from '../types.js';
+
+/**
+ * Options for registering a definition found in the syntax tree.
+ */
+export interface DefOpts {
+  name: string;
+  kind: SymbolKind;
+  /**
+   * Outer node used for the symbol's line range and doc-comment lookup, when it
+   * differs from the definition node (e.g. `export_statement`, a decorated
+   * definition, or a `lexical_declaration` wrapping a declarator).
+   */
+  range?: Node | null;
+  /**
+   * Body node. The signature is the source text from the start of the range up
+   * to the start of the body. Defaults to the node's `body` field. Pass `null`
+   * to use the whole (first line of the) node as the signature.
+   */
+  body?: Node | null;
+  /** Explicit signature text (overrides body-based slicing). */
+  sig?: string;
+  /** Explicit doc text (e.g. Python docstrings). */
+  doc?: string | null;
+  /**
+   * Extra qualifier prepended to the qualified name for definitions that are
+   * lexically outside their container: Go receivers, C++ `Foo::bar`, etc.
+   */
+  qualifier?: string | null;
+  exported?: boolean;
+  /**
+   * When false the symbol does not open a scope: nested definitions are not
+   * qualified by it and calls inside are attributed to the enclosing symbol.
+   * Required when defining a symbol for a node other than the one being
+   * visited (e.g. enum members registered from the enum visitor). Default true.
+   */
+  scope?: boolean;
+  /**
+   * Define the symbol as a member of the nearest enclosing container (class,
+   * struct, ...) instead of the innermost scope. Used for instance attributes
+   * assigned inside methods (`self.x = ...` in Python `__init__`).
+   */
+  inContainer?: boolean;
+}
+
+/**
+ * Context handed to language visitors. All methods refer to the node currently
+ * being visited; scopes opened by `def`/`scope` close automatically when the
+ * walker leaves that node.
+ */
+export interface Ctx {
+  readonly src: string;
+  /** Register a symbol. Returns its index. */
+  def(node: Node, opts: DefOpts): number;
+  /** Open a naming-only scope (Rust `impl`, PHP/Java packages, ...). */
+  scope(name: string): void;
+  /**
+   * Record a call made at `node`. `receiverType` may be given when the
+   * receiver's class is evident from the expression itself
+   * (`new Foo().bar()`, casts); otherwise it is derived from type hints.
+   */
+  call(name: string | null | undefined, node: Node, receiver?: string | null, receiverType?: string | null): void;
+  /**
+   * Record an import of `source`. `names` are the names bound in this file;
+   * write `alias=original` when the binding is renamed (`import { a as b }`
+   * -> `b=a`) and `*` for wildcard imports.
+   */
+  imp(source: string | null | undefined, node: Node, names?: string[]): void;
+  /** Record that symbol `sym` extends/implements `name`. */
+  inherit(sym: number, name: string | null | undefined, kind?: 'extends' | 'implements', arity?: number): void;
+  /**
+   * Record an identifier occurrence under a different name than the source
+   * text (e.g. C# `[Authorize]` also references `AuthorizeAttribute`).
+   */
+  ref(name: string | null | undefined, node: Node): void;
+  /**
+   * Record the declared type of a parameter, local, or field so that member
+   * calls on it (`record.topic()`, `this.repo.find()`) can be resolved to
+   * the right class. `type` is raw type text; it is normalised with
+   * typeName(). The hint is attached to the nearest enclosing function (or
+   * class, for field declarations). Pass `onContainer` = true to attach it
+   * to the enclosing class even from inside a method: constructor parameter
+   * properties, `self.x = Foo()` assignments.
+   */
+  typeHint(name: string | null | undefined, type: string | null | undefined, onContainer?: boolean): void;
+  /**
+   * Declare the symbol this file exports as its default
+   * (`export default X`, `module.exports = X`). Importers that bind it to
+   * another local name are then linked to X.
+   */
+  exportDefault(name: string | null | undefined): void;
+  /**
+   * Declared type of a variable / parameter visible at the current node
+   * (as recorded by typeHint), or null. Lets a spec propagate types through
+   * simple assignments such as `this.repo = repo`.
+   */
+  typeOf(name: string | null | undefined): string | null;
+  /** Kind of the innermost enclosing symbol, or null at file level. */
+  parentKind(): SymbolKind | null;
+  /** True if any enclosing symbol is a function or method. */
+  inCallable(): boolean;
+  /** Number of enclosing real symbols (0 = file level). */
+  depth(): number;
+}
+
+/** Return 'skip' to prevent the walker from descending into the node. */
+export type Visitor = (node: Node, ctx: Ctx) => void | 'skip';
+
+export interface LangSpec {
+  /** Language id used in config and in the database. */
+  id: string;
+  /** Grammar file name without the `tree-sitter-` prefix and `.wasm` suffix. */
+  grammar: string;
+  extensions: string[];
+  /** Leaf node types recorded as identifier occurrences (reference index). */
+  identifiers: string[];
+  /** Type names may be lowercase (Go unexported types, C structs); see typeName(). */
+  lowercaseTypes?: boolean;
+  /** Type hints keep a package qualifier (`pkg.Type`, Go); resolved against the file's imports at query time. */
+  packageTypes?: boolean;
+  /** Node types whose text is a comment (for doc extraction). */
+  comments?: string[];
+  /**
+   * Node types that may sit between a doc comment and the item it documents
+   * (Rust attributes, PHP attributes, ...). They are skipped when looking for
+   * the leading comment.
+   */
+  docSkip?: string[];
+  /** Visitors keyed by tree-sitter node type. */
+  visit: Record<string, Visitor>;
+  /**
+   * Optional: pick a different spec id based on file content (used to parse
+   * `.h` files as C++ when they look like C++).
+   */
+  sniff?: (source: string, path: string) => string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers shared by language specs
+// ---------------------------------------------------------------------------
+
+export function field(node: Node | null | undefined, name: string): Node | null {
+  return node ? node.childForFieldName(name) : null;
+}
+
+export function text(node: Node | null | undefined): string {
+  return node ? node.text : '';
+}
+
+/** First named child with one of the given types. */
+export function childOfType(node: Node | null | undefined, ...types: string[]): Node | null {
+  if (!node) return null;
+  for (const c of node.namedChildren) {
+    if (c && types.includes(c.type)) return c;
+  }
+  return null;
+}
+
+export function childrenOfType(node: Node | null | undefined, ...types: string[]): Node[] {
+  if (!node) return [];
+  const out: Node[] = [];
+  for (const c of node.namedChildren) {
+    if (c && types.includes(c.type)) out.push(c);
+  }
+  return out;
+}
+
+/** Nearest ancestor with one of the given types (bounded). */
+export function ancestor(node: Node, types: string[], maxUp = 8): Node | null {
+  let cur = node.parent;
+  for (let i = 0; cur && i < maxUp; i++) {
+    if (types.includes(cur.type)) return cur;
+    cur = cur.parent;
+  }
+  return null;
+}
+
+export function stripQuotes(s: string): string {
+  return s.replace(/^[bru]*(['"`<])/i, '').replace(/['"`>]$/, '');
+}
+
+/** Last segment of a dotted / scoped name: `a.b.C` -> `C`, `a::b` -> `b`. */
+export function lastSegment(s: string): string {
+  const m = /([A-Za-z_$][\w$]*)\s*(?:<[^<>]*>)?\s*$/.exec(s);
+  return m ? m[1]! : s;
+}
+
+/** Receiver marker for member calls whose receiver is a complex expression. */
+export const COMPLEX_RECEIVER = '?';
+
+/**
+ * Receiver text of a member call. Short simple receivers (`this`, `db`,
+ * `Foo`, `this.repo`) are returned as text; anything else (call chains,
+ * literals, indexing) becomes COMPLEX_RECEIVER so the resolver still knows
+ * the call HAD a receiver and is not a bare `foo()` call. Returns null only
+ * when there is no receiver node at all.
+ */
+export function simpleReceiver(node: Node | null | undefined): string | null {
+  if (!node) return null;
+  if (node.endIndex - node.startIndex > 48) return COMPLEX_RECEIVER;
+  // `this.grid!.layout()`, `a?.b.run()`, Rust `x?.go()`: the assertion / optional-chain / try marks
+  // do not change which object it is.
+  const t = node.text.replace(/[!?]+$/, '').replace(/[!?]+(?=\.)/g, '');
+  if (!t || /[\s(\[{"'`]/.test(t) || /^\d/.test(t)) return COMPLEX_RECEIVER;
+  return t;
+}
+
+const TYPE_WRAPPERS = new Set([
+  'Option', 'Optional', 'Arc', 'Rc', 'Box', 'RefCell', 'Mutex', 'RwLock', 'Cell', 'Pin', 'Weak',
+  'Promise', 'Readonly', 'Partial', 'Required', 'NonNullable', 'Awaited', 'Lazy', 'Task', 'ValueTask',
+  'Nullable', 'Future', 'CompletableFuture', 'Supplier', 'Provider', 'Ref', 'Ptr', 'unique_ptr',
+  'shared_ptr', 'weak_ptr', 'Type', 'ClassVar', 'Final', 'Annotated',
+]);
+
+/**
+ * Reduce raw type text to the bare name of the class it denotes, or null:
+ * `*Site` -> Site, `ProducerRecord<K, V>` -> ProducerRecord,
+ * `Option<Arc<Handle>>` -> Handle, `pkg.Foo` / `ns::Foo` -> Foo,
+ * `Foo | null` -> Foo, `const Foo&` -> Foo. Collections and primitives
+ * are not class types and yield null.
+ */
+/** Number of type arguments in `Name<A, B<C>>` (0 when not generic). */
+export function genericArity(text: string): number {
+  const lt = text.indexOf('<');
+  if (lt === -1) return 0;
+  let depth = 0;
+  let n = 1;
+  for (let i = lt; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '<' || ch === '(' || ch === '[') depth++;
+    else if (ch === '>' || ch === ')' || ch === ']') {
+      if (--depth === 0) return n;
+    } else if (ch === ',' && depth === 1) n++;
+  }
+  return n;
+}
+
+export function typeName(raw: string | null | undefined, allowLowercase = false, keepPackage = false): string | null {
+  if (!raw) return null;
+  let t = raw.trim();
+  for (let i = 0; i < 4; i++) {
+    // Strip qualifiers, pointer / reference sigils and lifetimes until stable (`&'a mut Foo`).
+    for (let guard = 0; guard < 6; guard++) {
+      const before = t;
+      t = t
+        .replace(/^(const|readonly|mut|final|volatile|static|ref|out|in|params|dyn|impl|struct|class|enum|typename|unsigned|signed)\s+/, '')
+        .replace(/^[&*?\s:]+/, '')
+        .replace(/^'[a-z_]+\s+/, '');
+      if (t === before) break;
+    }
+    t = t
+      .replace(/[&*?!\s]+$/, '')
+      .replace(/\s*\|\s*(null|undefined|None)\b/g, '')
+      .replace(/^(null|undefined|None)\s*\|\s*/, '')
+      .trim();
+    const m = /^([\w.:\\]+)\s*[<\[](.*)[>\]]$/s.exec(t);
+    if (!m) break;
+    const outer = m[1]!.split(/\.|::|\\/).pop()!;
+    if (!TYPE_WRAPPERS.has(outer)) { t = m[1]!; break; }
+    // Unwrap: first type argument at nesting depth 0.
+    let depth = 0;
+    let end = m[2]!.length;
+    for (let k = 0; k < m[2]!.length; k++) {
+      const ch = m[2]![k];
+      if (ch === '<' || ch === '[' || ch === '(') depth++;
+      else if (ch === '>' || ch === ']' || ch === ')') depth--;
+      else if (ch === ',' && depth === 0) { end = k; break; }
+    }
+    t = m[2]!.slice(0, end).trim();
+  }
+  if (/[|&(){}\[\],<>=\s]/.test(t)) return null;
+  const segs = t.split(/\.|::|\\/);
+  const name = segs.pop() ?? '';
+  if (!/^[A-Za-z_$][\w$]*$/.test(name)) return null;
+  if (name.length < 2) return null;
+  // Go: `pkg.Type` keeps its package so that it is not confused with a same-named type elsewhere.
+  if (keepPackage && segs.length >= 1 && /^[A-Z]/.test(name)) {
+    // Rust `std::io::Error` / `io::Error`: anything under std / core / alloc is marked "std", otherwise
+    // the module the type is taken from (`io`, `crate`, `super`) is kept. Go: `pkg.Type`.
+    const rustPath = t.includes('::');
+    if (rustPath && segs.some(s => s === 'std' || s === 'core' || s === 'alloc')) return 'std.' + name;
+    const q = segs[segs.length - 1]!;
+    if ((rustPath || segs.length === 1) && /^[a-z_][a-z0-9_]*$/.test(q)) return q + '.' + name;
+  }
+  if (!/[A-Z]/.test(name[0]!)) {
+    // Lowercase names are primitives / builtins in most languages (int, string, str, bool, ...).
+    // Go and C name real types in lowercase too, so those specs opt in, minus the builtins.
+    if (!allowLowercase || PRIMITIVE_TYPES.has(name) || /^(u?int|float|complex)\d*(_t)?$/.test(name) || name.endsWith('_t')) return null;
+  }
+  return name;
+}
+
+const PRIMITIVE_TYPES = new Set([
+  'int', 'uint', 'char', 'short', 'long', 'float', 'double', 'void', 'bool', 'boolean', 'byte', 'rune', 'string',
+  'str', 'error', 'any', 'auto', 'var', 'let', 'unsigned', 'signed', 'size', 'uintptr', 'interface', 'struct',
+  'func', 'map', 'chan', 'object', 'number', 'bigint', 'symbol', 'unknown', 'never', 'null', 'undefined', 'dict',
+  'list', 'tuple', 'set', 'bytes', 'usize', 'isize', 'self', 'this', 'array', 'mixed', 'callable', 'iterable',
+  'static', 'const', 'wchar', 'ssize', 'off', 'time', 'file', 'va_list', 'sds',
+  // C++ standard library value types: not classes of the project.
+  'vector', 'deque', 'pair', 'queue', 'stack', 'mutex', 'thread', 'atomic', 'function', 'optional', 'variant',
+  'ostream', 'istream', 'ofstream', 'ifstream', 'stringstream', 'unordered_map', 'unordered_set', 'basic_string',
+  'string_view', 'span', 'bitset', 'complex', 'regex', 'iterator', 'allocator',
+]);
+
+/** UPPER_SNAKE names are treated as constants. */
+export function isConstName(name: string): boolean {
+  return /^[A-Z][A-Z0-9_]*$/.test(name) && name.length > 1;
+}

package/src/query/arity.ts

@@ -0,0 +1,173 @@
+/**
+ * Parameter counts read from a signature, used to tell overloads apart and to
+ * reject call sites that cannot be calls of a definition (`info.partition()`
+ * is not `Partitioner.partition(topic, key, keyBytes, value, valueBytes, cluster)`).
+ *
+ * Everything here is conservative: when a signature cannot be read with
+ * confidence the result is null, which callers treat as "anything fits".
+ */
+export interface ParamRange {
+  /** Required parameters. */
+  min: number;
+  /** All parameters; Infinity for variadic functions. */
+  max: number;
+  /** C# extension method: the first (`this`) parameter is the receiver when called as a member. */
+  ext: boolean;
+  /** TypeScript: the last required parameter has a type-parameter type (`fire(event: T)`), which may be `void`. */
+  voidable?: boolean;
+}
+
+/** Languages whose signatures are checked. Others (PHP, Ruby, JavaScript, Swift, Dart) accept any count. */
+export const ARITY_LANGS = new Set(['java', 'csharp', 'go', 'c', 'cpp', 'typescript', 'tsx', 'python', 'rust']);
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Index of the `)` matching the `(` at `open`, or -1. Skips string literals. */
+function closing(sig: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < sig.length; i++) {
+    const ch = sig[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const end = sig.indexOf(ch, i + 1);
+      if (end === -1) return -1;
+      i = end;
+    } else if (ch === '(') depth++;
+    else if (ch === ')' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Split a parameter list on top-level commas. */
+function splitParams(list: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < list.length; i++) {
+    const ch = list[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const end = list.indexOf(ch, i + 1);
+      if (end === -1) break;
+      i = end;
+    } else if (ch === '(' || ch === '[' || ch === '{' || ch === '<') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') depth--;
+    else if (ch === '>') {
+      // Not the arrow of `=>` / `->`.
+      const prev = list[i - 1];
+      if (prev !== '=' && prev !== '-') depth--;
+    } else if (ch === ',' && depth <= 0) {
+      out.push(list.slice(start, i));
+      start = i + 1;
+      depth = 0;
+    }
+  }
+  out.push(list.slice(start));
+  return out.map(p => p.trim()).filter(Boolean);
+}
+
+/** True when the parameter has a default value (`x = 1`, `x: int = 1`) at its top level. */
+function hasDefault(param: string): boolean {
+  let depth = 0;
+  for (let i = 0; i < param.length; i++) {
+    const ch = param[i];
+    if (ch === '(' || ch === '[' || ch === '{' || ch === '<') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}' || (ch === '>' && param[i - 1] !== '=' && param[i - 1] !== '-')) depth--;
+    else if (ch === '=' && depth <= 0) {
+      const next = param[i + 1];
+      const prev = param[i - 1];
+      if (next !== '=' && next !== '>' && prev !== '=' && prev !== '!' && prev !== '<' && prev !== '>') return true;
+    }
+  }
+  return false;
+}
+
+export function paramRange(signature: string, name: string, lang: string): ParamRange | null {
+  if (!ARITY_LANGS.has(lang) || !signature || !name) return null;
+  let sig = signature;
+  if (lang === 'go') {
+    // func (r *T) Name(...): skip the receiver.
+    const recv = /^func\s*\(/.exec(sig);
+    if (recv) {
+      const end = closing(sig, recv[0].length - 1);
+      if (end === -1) return null;
+      sig = sig.slice(end + 1);
+    }
+  }
+  const m = new RegExp('(?:^|[^\\w$])' + escapeRe(name) + '\\s*(?=[<\\[(])').exec(sig);
+  if (!m) return null;
+  let i = m.index + m[0].length;
+  // Type parameters: <T, U> or Go [T any].
+  if (sig[i] === '<' || sig[i] === '[') {
+    const open = sig[i];
+    const close = open === '<' ? '>' : ']';
+    let depth = 0;
+    for (; i < sig.length; i++) {
+      if (sig[i] === open) depth++;
+      else if (sig[i] === close && sig[i - 1] !== '=' && sig[i - 1] !== '-' && --depth === 0) { i++; break; }
+    }
+    while (sig[i] === ' ') i++;
+  }
+  if (sig[i] !== '(') return null;
+  const end = closing(sig, i);
+  if (end === -1) return null; // truncated signature
+  let params = splitParams(sig.slice(i + 1, end));
+
+  if (lang === 'c' || lang === 'cpp') {
+    if (params.length === 1 && params[0] === 'void') params = [];
+    // `int f()` in C says nothing about the parameters.
+    else if (params.length === 0 && lang === 'c') return null;
+  }
+  if (lang === 'python') {
+    if (params.length && /^(self|cls)\b/.test(params[0]!)) params = params.slice(1);
+  } else if (lang === 'rust') {
+    if (params.length && /^(&\s*('\w+\s+)?)?(mut\s+)?self\b/.test(params[0]!)) params = params.slice(1);
+  } else if (lang === 'typescript' || lang === 'tsx') {
+    if (params.length && /^this\s*:/.test(params[0]!)) params = params.slice(1);
+  }
+
+  let min = 0;
+  let max = 0;
+  let variadic = false;
+  let ext = false;
+  let voidable = false;
+  for (let k = 0; k < params.length; k++) {
+    const p = params[k]!;
+    if (lang === 'python') {
+      if (p === '*' || p === '/') continue; // keyword-only / positional-only markers
+      if (p.startsWith('*')) { variadic = true; continue; }
+    }
+    if (p.includes('...') || (lang === 'csharp' && /^(\[[^\]]*\]\s*)*params\s/.test(p))) {
+      variadic = true;
+      continue;
+    }
+    if (lang === 'csharp' && k === 0 && /^(\[[^\]]*\]\s*)*this\s/.test(p)) ext = true;
+    max++;
+    const optional =
+      hasDefault(p) ||
+      ((lang === 'typescript' || lang === 'tsx') && /^[\w$]+\?\s*(:|$)/.test(p));
+    if (!optional) {
+      min++;
+      voidable = (lang === 'typescript' || lang === 'tsx') && /:\s*(?:[A-Z]|T[A-Z]\w*)\s*$/.test(p);
+    }
+  }
+  return { min, max: variadic ? Infinity : max, ext, voidable };
+}
+
+/**
+ * Can a call with `argc` arguments be a call of a function with this range?
+ * `unbound` marks calls written through a type name (`Base.save(self, x)`,
+ * `Type::method(value, x)`), which pass the receiver as an argument.
+ */
+export function arityFits(range: ParamRange | null, argc: number, lang: string, unbound: boolean): boolean {
+  if (!range || argc < 0) return true;
+  if (argc >= range.min && argc <= range.max) return true;
+  // `emitter.fire()` on an Emitter<void>: a parameter of type T can be left out when T is void.
+  if (range.voidable && argc === range.min - 1) return true;
+  // Extension method called as a member: the receiver fills the `this` parameter.
+  if (range.ext && argc + 1 >= range.min && argc + 1 <= range.max) return true;
+  if (unbound && (lang === 'python' || lang === 'rust') && argc - 1 >= range.min && argc - 1 <= range.max) return true;
+  // Go: f(g()) forwards all results of g.
+  if (lang === 'go' && argc === 1 && range.min > 1) return true;
+  return false;
+}