Skip to main content
Glama

ripple

Know what breaks before you change it. ripple is an MCP server that gives a coding agent (Claude Code, Cursor, anything that speaks MCP) the call graph of a Python, TypeScript, JavaScript, Go, Rust or Java repository, so the agent can ask "who calls this, and which tests reach it?" before it edits, and run just those tests after.

Why

A coding agent dropped into unfamiliar code edits blind. It greps for a function name, sees a few hits, and changes the signature. The callers that reach it through an import alias, a self. call in a subclass or a re-export in a package __init__ don't match the grep, and the first sign of trouble is a failing test, or a failure in production. ripple answers the structural question directly and says plainly where static analysis runs out.

Related MCP server: repo-atlas-mcp

Quickstart

Requires Python 3.10+ and uv.

uv tool install git+https://github.com/xtelos/ripple   # puts `ripple` on your PATH

Claude Code, from your project directory:

claude mcp add ripple -- ripple serve --repo "$PWD"

Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "ripple": { "command": "ripple", "args": ["serve", "--repo", "${workspaceFolder}"] }
  }
}

Or from a terminal: ripple index ., then ripple impact price_order.

The five tools

Tool

What it answers

Read-only

callers(symbol)

Who calls this directly, with the file:line of each call site

yes

callees(symbol)

What this calls, plus the calls ripple could not resolve and why

yes

impact(symbol, depth=5, limit=100)

Every transitive caller grouped by file, the tests that reach it listed separately as test ids (pytest node ids; file_test.go::TestName for Go), and same-named call sites ripple could not rule out

yes

path(source, target)

The shortest call chain from one symbol to another

yes

check(tests=None, lang=None)

Runs the test command (default python -m pytest -q, using the repo's .venv or venv if present, for a repo with only Python files; go test -json in every module for a Go repo, see Go; cargo test in every top-level workspace for a Rust repo, see Rust; mvn test for a Maven repo, see Java; a TypeScript-only repo, or --lang typescript, has no default; a repo of several languages is refused until lang names one, unless the server has a --lang or a test command), or just the given test paths (for Python, pytest node ids too; for Go, file_test.go::TestName[/subtest]; for Rust, a .rs file, a directory or file.rs::module::test_name; for Java, the id impact lists, a test .java file or a directory), and returns pass/fail, the summary line and the first failures, never the full log

no, it runs code

A symbol can be a full dotted path (shop.pricing.price_order), a suffix (OrderService.place_order) or a bare name (price_order); in TypeScript it is a path and a member (src/util/math:clamp, see TypeScript). An ambiguous name returns the candidates rather than picking one.

A bare name (no dot, slash or colon) that matches a module is never answered as the module with no callers, with one exception below. What answers when:

  • The module declares a function or class of that name (src/foo.ts defining foo): that symbol.

  • The module exports the name as a memo, forwardRef or alias of a function or class (export const SubMenu = forwardRef(SubMenuFR), export { Impl as Name }, a barrel's export { SubMenu as Menu } from "./SubMenu"): that function, and the note of the answer says how (SubMenu is exported by src/components/SubMenu as forwardRef(SubMenuFR); showing src/components/SubMenu:SubMenuFR; a barrel's note names each hop and the wrapper at the end of it), in the text, the --json output and the tool result.

  • Anything that leaves two readings of the name is ambiguous, and the answer lists them: a module that declares a render and also exports render as something else (export { renderV2 as render }, or a wrapper ripple cannot name) lists the declared symbol, the exported one when ripple can name it, and the module; two modules that export or define the name as different symbols (a Card in src/Card and another in src/legacy/Widgets, wrapped or not) list both, whatever the files are called; a module and a symbol of some other module list both.

  • The module has no symbol of that name: an error that lists what the module defines and exports and names the full module id (shop.tax, src/util/math) to ask about the module itself. A full module id, or any path, is answered as before.

A TypeScript id written as the module, a colon and an exported name (src/components/SubMenu:SubMenu) resolves the same way when no symbol has that id and the module exports the name as a memo, forwardRef, alias or re-export of a function or class: the answer is that function, with the same note, for callers, callees, impact and path, in the text, the --json output and the tool result. The module may be written as a path (components/SubMenu, src/components/SubMenu.tsx), and default is a name a module can export (website/pages/_app:default). When a path ends more than one module (components/SubMenu in a monorepo, or x for x.ts and x.tsx), the symbols the modules declare under the name and what each of the others exports under it are all counted, and when they are more than one symbol the answer is ambiguous and lists them, whether the modules declare the name, export it as a wrapper or alias, or one of each. An id that is a symbol is never reinterpreted: src/render:render is the function render the module declares, even if the module also exports render as something else (the bare name render is the ambiguous answer). When the module exists and exports no such name, the answer is still no symbol named ..., and its suggestions begin with the module's own top-level symbols and exports as the module:Name ids that resolve, closest to the name asked first (at most 100; when it lists fewer than the module has, the error says how many there are, and for a path that ends several modules how many modules match and how many symbols and exports they have in all), followed by the five closest names in the repo (those not already listed) as before. A module that does not exist keeps the old suggestions. Python ids use dots, so a Python query with a colon in it is answered as it always was.

The exception is a module at the repo root, whose whole id is the bare name (SubMenu.tsx is the module SubMenu, tax.py is tax): the name cannot be told from a question about the module. If the module also defines or exports a symbol of that name, the answer is ambiguous and lists the module and the symbol (in Python too, as it already was for a module in a package, shop/foo.py defining foo); if it has none, the answer is about the module. A symbol that is not exported by name is not found by it: export const Name = Inner is not an alias, because ripple does not read a call of Name as a call of Inner, and const Card = memo(Inner); export default Card is not read either: the module's candidates list Inner.

The four graph tools advertise readOnlyHint: true, which lets a client run them without prompting. check is marked destructive instead, because a test suite can do anything its tests do.

callers, callees, impact and path also take kinds (--kinds on the command line): which edges to follow, from calls, renders, renderer and implements, comma separated, default all. Only a TypeScript repo with JSX has renders and renderer (see JSX), only a Go repo has implements (see Go); in a Python repo every edge is a call and nothing is labelled. implements is never a call: a Go call through a repo interface may dispatch to the methods of the repo types that provably satisfy the interface, so callers lists them under may_be_called_through_interface, impact under may_be_reached_through_interface and callees under may_dispatch_to, each with a note, and --kinds calls leaves them out. Those lists are possible, never complete, and not counted in count, affected, the affected tests or the edges statistic (ripple index prints their number apart).

A TypeScript symbol that is applied as a decorator also lists where, apart from its callers (see TypeScript), and callers and impact of a symbol that a class ripple does not read may call say so.

impact lists at most limit callers and limit tests (100 by default, up to 1000 over MCP). When it found more, it says so: truncated is true and omitted_callers / omitted_tests give the counts (the CLI prints "... and N more callers not listed"). Decorator sites are bounded the same way: decorations_omitted and decorations_of_callers_omitted give how many sites were found and not listed (the CLI prints "... and N more decorator sites not listed"), and impact counts them in truncated too, so a true truncated with both omitted_* counts at zero means decorator sites were left out. callers and path have no truncated: they carry decorations_omitted alone. Each test comes with its pytest node id (tests/test_x.py::test_y, or tests/test_x.py::TestZ::test_y for a method), found by pytest's default collection rules: test* functions at module level in test_*.py and *_test.py files, test* methods of Test* classes that have no __init__, and every test* method of a unittest.TestCase subclass whatever its name. A class runs the test methods it inherits, so a method defined on a base is listed once for each class that runs it, under that class's node id (TestChild::test_shared). Pass those node ids to check to run just those tests. Helpers in test files that are not tests themselves are listed with the other callers, since they may need updating.

check(tests=[...]) accepts only test file paths and node ids inside the repository. Anything that starts with - or @ (pytest reads options from an @file) or points outside the repo is refused, so a caller cannot slip in a pytest option (--basetemp=DIR deletes DIR). Output is read from a temporary file and the timeout covers the whole run, so a test that leaves a process running in the background cannot hold up the result. The summary and each failure or output line check returns are cut to 240 characters, ending in [truncated N chars] when something was cut.

Example, trimmed:

$ ripple impact tax_for --repo bench/fixtures/shop
impact of shop.tax.tax_for (depth 5): 6 callers
  shop/pricing.py
    shop.pricing.price_order  line 8  (1 hop)
  shop/service.py
    shop.service.OrderService.place_order  line 17  (2 hops)
    shop.service.OrderService.reprice  line 26  (2 hops)
tests that reach it (3):
  tests/test_pricing.py::test_percent_discount_and_tax
  ...

$ ripple check tests/test_pricing.py::test_percent_discount_and_tax --repo bench/fixtures/shop
{
  "passed": true,
  "summary": "1 passed in 0.01s",
  ...

TypeScript

TypeScript is read by tree-sitter, which is an optional extra: it adds tree-sitter and tree-sitter-typescript and nothing else (the base install needs only the mcp SDK).

uv tool install "ripple-code[typescript] @ git+https://github.com/xtelos/ripple"   # or pip install 'ripple-code[typescript]'

--lang auto|python|typescript|javascript|go|rust|java (default auto; RIPPLE_LANG sets it for every command, and build_server takes a lang argument) chooses how the repo is read. auto looks at the file names: .py for Python, .ts, .tsx, .mts and .cts for TypeScript, .js, .jsx, .mjs and .cjs for JavaScript (see JavaScript below), .go for Go, .rs for Rust, .java for Java, skipping .d.ts, node_modules and virtualenvs. A repo with none of them, or one that does not exist, is an error (exit status 2), not "0 files".

check does not pick a language for you. With files of two or more languages (found by the same walk, so node_modules, virtualenvs, build output and declaration files count for nothing), no --lang and no test command, it refuses with exit status 2 (a tool error from the server) and names the languages and the flag: cannot choose which tests to run in <repo>: it has Python and Go source files, and a verdict from one language's tests says nothing about the others. Pass --lang python or --lang go .... A passed that covers one language of several is a guess, so the answer is to say which: --lang go or RIPPLE_LANG on the command line, and for the server's check tool its optional lang argument (check(lang="go"), the same names as --lang; the refusal names it, and ripple serve --lang go fixes one for the session). A lang on a call overrides the server's --lang for that call only, and an unknown one is the "unknown language ... choose one of" error. An explicit --lang always wins. A test command (--test-command, RIPPLE_TEST_COMMAND) is not refused: with one, check takes its exit code as the verdict and the language (--lang, or the tool's lang) only chooses which output lines are listed as failures. A command that comes to nothing (empty, only blanks, '') is no command, and is refused like none. TypeScript and JavaScript count as one language here (neither has a runner or a default command, and both list failures the same way). index, impact, path and the other graph commands read every language and are not affected.

Symbols are the file's path without the extension, a colon and the member: src/util/math:clamp, src/cart/cart:Cart.add (an index file is its directory, a second declaration of a name under one parent gets #2, a test callback is tests/a.test:suite > case). Any of these finds it, when it names one symbol: that id, the path with its extension (src/util/math.ts:clamp), the tail of the path (math:clamp), Class.method or the bare member (a bare name that is also a module's or a re-export's is answered as described above). A path is read through the id the indexer gave that file, never folded by a rule (with src/a.ts beside src/a/index.ts, the index file is src/a/index); src/util/ is the index file of that directory. More than one match returns the candidates; ripple never picks.

$ ripple impact clamp --repo bench/fixtures/ts/warehouse-ts --limit 4
impact of src/util/math:clamp (depth 5): 16 callers
  src/models/item.ts
    src/models/item:normalise  line 7  (1 hop)
    src/models/item:Item.quantity  line 22  (2 hops)
  ...
  ... and 12 more callers not listed; raise --limit to see them
tests that reach it (0):

Resolved: a name declared or imported (relative imports, tsconfig baseUrl, paths and a relative extends, barrels, export *, with the tsconfig scoping below), this and super, new C(), a value annotated with a class, a call result whose function has a return annotation, a namespace import, and a function passed by name as the first argument of map, forEach and the other array methods that run it at once. Unresolved, with the reason: an interface-typed value, table[key](), a method chosen by name, a loop variable, a value of no stated type, require and a tsconfig that extends a package. Class fields holding arrow functions, object literal methods, enums and namespaces are not supported: their calls stay unresolved, or the code is skipped. A call ripple cannot prove is listed as unresolved, never guessed, and impact lists the same-named ones under possible_missed_callers as it does for Python.

Which tsconfig a file gets. A config's baseUrl and paths are the aliases of the files it governs and of no other. Every tsconfig.json above an indexed file is read, and a file belongs to the nearest one whose files, include and exclude cover it, read the way the compiler reads them: with neither files nor include, every source file under the config's directory; exclude removes files (its ** reaches hidden directories, which an include's ** and the default include do not), a \ in a path a config writes is a / as it is for the compiler, and when exclude is not written it defaults to node_modules, bower_components, jspm_packages and outDir. When a nested config (an app's) governs a file, its paths decide and the root's are not consulted. A relative extends contributes paths, baseUrl, files, include and exclude, each pattern relative to the config that wrote it (a ${configDir} in baseUrl, paths, files, include, exclude, rootDir or outDir is the directory of the config being compiled, the extending one), and a list the extending config writes replaces the base's. references are followed: a config that does not cover a file hands it to the first project it references that does (the layout of a Vite or shadcn app, where the root tsconfig.json is "files": [] plus references to tsconfig.app.json and the like), and that project's paths and baseUrl apply. A reference is a path relative to the config that lists it: a .json path is that config and any other is a directory holding a tsconfig.json. References are read four levels down, each config once (so a cycle ends), a path that names no config is ignored, and a config does not inherit the references of one it extends. A file no config governs has no aliases, so a bare import in it is a package, never a file of the repo, with two exceptions. When a config above the file lists references and a config in that tree maps the specifier (a paths entry it matches, or a repo file its baseUrl reaches), the import is left unresolved with the reason (which project owns the file is the open question), and a call through it is listed as an unresolved call, not counted as code outside the repo. That is the case that matters in a monorepo: an app the root include leaves out, which depends on a published copy of a package the root paths maps to its own source, is not given the source (the app runs the published copy). And when a config's include names the file but a same-named file of higher extension priority (x.tsx beside x.ts) takes its place in the program, the file is in no project yet is built like its twin, so an alias that config maps is unresolved, with the reason, never a package and never an edge. A file that no include names has no aliases at all. A bare import whose package name is the name of a package.json in the repo (a package importing itself, or a workspace package named by another: "pkg": "workspace:*") is unresolved, with the reason: it reaches repo code through that package's exports, which ripple does not read. Ripple reads nothing else of a package.json, and only the name of those in a directory above or holding a source file; that costs those edges, and none is guessed. A config that cannot be read governs everything under it with no aliases and is listed with the files that did not parse. The JSX settings (jsxFactory and the others, under JSX) are those of the config that governs the file, and the root config's too. A jsconfig.json is a config like any other and beside a tsconfig.json it governs the files that one does not hold (see JavaScript). A relative import that names no file is unresolved, not missing, under a config that sets rootDirs, which ripple does not follow.

Decorators. A decorator (@tag, @route("/x")) written on a class, a method, a property or a parameter is not a call edge: what it does to the thing it decorates is not followed, and a member it decorates is never resolved. It stays an unresolved call of the scope that holds the class. When its name resolves to a symbol of the repo, callers, impact and path for that symbol list each place it is applied under decorations, with a note that these are not calls and are not modelled. A decorator written through a receiver typed as a base class (@reg.add() with reg: Base) is listed for the subclass methods that override add too, as a call through that receiver gets an override edge. A name that did not resolve but ends the way the symbol's does goes under possible_decorations, and a name proven to come from outside the repo is never listed. callees of the scope that writes the decorators lists them under applies_decorators, naming the decorator only when its name resolved. impact also lists, under decorations_of_callers, each place where one of the callers it found is itself applied as a decorator (with decorator, the caller it applies, and its distance): such a caller runs again each time a decorated class is defined, so the reach of the change continues past it. The decorated classes are not followed or counted as callers, affected and more_beyond_depth are unchanged, and only sites whose name resolved to the caller are listed. The keys exist only when there is something to list, and the callers and affected count of a symbol are what the call edges prove, whatever its decorations. A factory call @registry(args) is one of these sites. The call of registry does run when the class is defined, but the benchmark fixture has no decorator for its ground truth to confirm an edge, so it is only listed. A call inside a decorator's arguments is an ordinary call, made by the scope that holds the class (the module, or the function or method the class is written in). When the class is written inside another class (a field initializer, a static block, a method of an object literal), the scope that runs the call is not provable, so no edge is made: the call is an unresolved call with the reason "a decorator on a class written inside another class", and callers and impact of what it calls list it under possible_missed_callers.

Class expressions (the class a decorator returns) and export default class {} are not read. Each call written inside one is an unresolved call of the scope around it, with the reason "inside a class that ripple does not read". impact lists the same-named ones under possible_missed_callers with that reason, and callers, which lists no unresolved calls of its own, lists exactly these under the same key. In a repo of both languages, a decoration or a class-expression call is only ever listed for a TypeScript symbol, never for a Python one of the same name.

$ ripple callers src/decorators/registry:registry --repo tsyringe
callers of src/decorators/registry:registry (0):
applied as a decorator (12), not calls; what a decorator does is not modelled:
  src/__tests__/global-container.test:doesn't blow up with empty args  src/__tests__/global-container.test.ts:577  written @registry()
  ...

Measured, the same way as the Python benchmark (python -m bench.ts_score): on the fixture (bench/fixtures/ts/warehouse-ts, ground truth from a run of its jest and vitest tests) precision 1.000, recall 0.967 (88 of 91 calls). Held out, on seven real libraries the indexer was never developed against (neverthrow, tsyringe, superstruct, react-accessible-accordion, react-error-boundary, react-hot-toast and react-pro-sidebar), recorded at runtime: 328 library edges, 312 seen at runtime, none false (precision 312 of 312, so the false-edge rate is below about 1.2%, not zero); recall of the pairs that ran is 0.84 (302 of 359), and 45 percent of call sites stay unresolved. That is the honest cost of not guessing. An eighth, ts-pattern, could not be recorded: 138 edges were indexed and 15 of them checked by hand, all correct, and it is in none of those figures. The held-out figures were recorded before ripple read parameter decorators and flagged the calls inside class expressions, and were not recorded again. On tsyringe those changes add two edges (delay(...) written in the argument of a parameter decorator, now made by the module that holds the class) and 43 unresolved calls, and remove or change none. The fixture figures above are measured on the current code.

Not yet: jest or vitest collection. impact lists every TypeScript caller, tests included, as code to update, so its tests list is empty, and check refuses a TypeScript-only repo until it is given the command (--test-command or RIPPLE_TEST_COMMAND, for example npx vitest run), with the refusal as an ordinary error. A repo of TypeScript and another language is refused until --lang or a command says what to run (see --lang above). It takes TypeScript test file paths only: ripple's own test ids (tests/a.test:suite > case) and a runner's line filter (tests/a.test.ts:12) are refused.

JavaScript

JavaScript is its own language, read by the same front end and the same tree-sitter extra as TypeScript (no new dependency): the tsx grammar parses .js, .jsx, .mjs and .cjs, JSX included, because JSX is legal in a .js file. Its ids are paths like TypeScript's (lib/app:helper, and lib/app.js:helper, app:helper or lib/app.js find the same things). --lang javascript reads only the JavaScript files, --lang typescript only the TypeScript ones, and auto reads both, each into a graph of its own, cached under its own key, with TypeScript first. ripple index counts each by its label (TypeScript: 21 files, JavaScript: 1 file).

ES modules only. import and export are followed (default, export *, export { a as b } from, a directory's index.js, .. and ../ for the directory above). CommonJS (require, module.exports) is not modelled yet: a call through one is unresolved with its reason, never an edge. That includes an ES import of a file that assigns module.exports or exports.x (Node gives it named exports), whose reason says the module is CommonJS.

Which file an import names is the TypeScript compiler's answer where Node and the bundlers agree with it, and unresolved, with the reason, where they do not. The compiler tries every TypeScript extension (.ts, .tsx, then the directory's index) across all the places an alias names, and only then the JavaScript ones (.js, .jsx), for a JavaScript importer too; .mjs and .cjs are named in full. A TypeScript importer takes the x.ts that ./x and ./x.js name (the x.js beside it is what the build makes of it). Node and the bundlers run the x.js a JavaScript importer names, so a JavaScript importer of ./x or ./x.js with an x.ts beside is unresolved. An extensionless ./dual beside dual.js and dual.mjs is dual.js for the compiler and for Node's require and dual.mjs for Vite and Rollup (whose resolve.extensions put .mjs first, and .js before .ts), so it is unresolved too, as is ./x with an x.mjs beside x/index.js, and a TypeScript importer's ./x with an x.mts beside the x.ts. A trailing slash names a directory. A package that ships one source as x.js, x.mjs and x.cjs has one id for all three, which the first of them keeps (.js, then .mjs, then .cjs); the others are read in full under their own path (x.mjs:f), and ripple index says so in a note rather than listing them as unparsable.

What a package.json decides, ripple leaves open. A specifier that names a directory of the repo (written relative, through paths or baseUrl, or reached by any of an alias's targets) is never a package and never a missing path: when the directory has a package.json its main, module, types or exports picks the file, and the compiler, Node and a bundler each read them their own way, so the import is unresolved with the reason even when an index.js is there (a package.json with a main that is not index.js is the case that draws a wrong edge, and the one without a main the case that merely loses a right one). A directory with no package.json and no index file ripple reads is unresolved too. A .js file found beside such a directory (x.js beside x/package.json) is unresolved, for the compiler's TypeScript pass enters the directory first. A # specifier is mapped by the nearest package.json's imports and is always unresolved. A bare specifier is a package unless a config maps it or it names a package of the repo (see "Which tsconfig a file gets"). These rules apply to TypeScript importers too.

A path that may name a file of the repo is never a package. A relative import is never a package where it reaches source of the repo: a file in a hidden directory or in the root dist, build or env (the walk skips them) is unresolved with the reason, as is a path that leaves the repo by .. and walks back in (../repo/a.mjs from the root of repo, found on the file system, a link back in included), for either language. An entry of the repo whose name starts with two dots (./..x/a.mjs, ./..lib.mjs) does not leave it and is read like any other relative path: the file at the root is an edge, one in a skipped directory is unresolved. A path that leaves for good, a JSON, CSS or image file, and a file of a package in node_modules are packages as before, by the same rule for a relative path and for an alias (./data.json and @/data.json are both packages). A relative import of a .vue, .svelte or .astro file, which ripple does not read, is unresolved (an alias that names one, or a file the walk skips, is too), and a path with no extension, or a directory's /index, that a resolver gives one (.js, .d.ts, .vue) to such a file names that file and is never "missing"; only a path that names nothing is. A relative specifier with a ?, a # or a % (./a.mjs?v=1, ./%61.mjs) is unresolved, for ESM and the bundlers read it as a URL and the compiler and Node's require as a path, and so is an alias with one (@/a.mjs?v=1, Vite's ?worker and ?raw) when the part before it is mapped. A bare name that is a Node builtin (util, fs/promises, but not test) is the builtin to Node whatever baseUrl or paths map it to, and a bundler may load the repo's file instead (esbuild for the browser does, for node:util as well), so for either language it is unresolved when a config maps it into the repo; node:util with no such file is the builtin. An absolute path (/abs/x.mjs), a file: URL (any case, any spaces the URL parser drops), a data: URL (code written in the file, which may import a file of the repo by its file: URL) and a specifier written with an escape sequence (not decoded: '\x2fabs/x' is /abs/x) are unresolved in JavaScript and TypeScript alike, because where the repo is on a machine is not known. A bare alias with a trailing slash (import 'lib/' under baseUrl: "src") names the directory to the compiler and to Node's require (its index file) and the file of that name to a bundler (esbuild), so it is unresolved when lib.js, lib.json or another file a resolver adds an extension to is there, and keeps the index edge when only lib/index.js is. A call through exports, module or require followed by a member (exports.f(), module.exports.f(), require.main.exports.f(), new exports.C(), <exports.C />, process.mainModule.exports.f(), require.resolve(...)) reaches the modules' own objects (this file's exports, the loader, the entry module), which ripple does not follow, so in a JavaScript or TypeScript file it is unresolved and never counted as outside the repo. Only a declaration of the name that gives it a value of its own makes it that value (a parameter, var, let, const, function, class or an import, in a function or block around the call or at the top of the file): a bare assignment (exports = new K()) does not, since the name holds the module's own object until the assignment runs, a var at the top of the file does not for the same reason (in a CommonJS file it redeclares the parameter Node runs the file with), and at the top of the file an enum, a namespace and import x = require() do not either. Inside a function or block, what exists at run time decides: an enum and a namespace that holds a value are bindings of their block (or of the function, at its top level), so the call is unresolved with the reason that the name is declared there (a const enum is erased by tsc and kept by Node's transform and by esbuild, so that is not known either), while an interface, a type alias, anything after declare and a namespace of types only exist in no form, hide nothing, and leave the call a member of the module's own objects. A var belongs to the function (or the file) around its block, whatever else of that name is declared in the block (an interface, a namespace, anything), and a function declared in a block is also taken for a name of the function, as in code that is not strict; a let, const, class, enum and namespace stop at their block. STATEMENT_KINDS in ripple/ts_indexer.py states the scope of each kind of statement, and tests/test_js_module_names.py runs each kind, in each position, in Node. A call of require(...) itself is a call of the builtin loader, as before. The same objects spelled another way are unresolved too, never outside the repo: globalThis.process.mainModule.exports.f(), global.process.mainModule..., and process (or ns.default, or mainModule) imported from process or node:process reach the entry module. globalThis.module, globalThis.exports and globalThis.require do not reach anything in a file Node runs (they are parameters of the file's wrapper function, so the call throws) unless code of the repo stores a module object on the global object, so they are unresolved with a reason that says that. A globalThis or global that a declaration gives a value of its own (a parameter, let, const, a top-level var, an import) is that value, and the call is read as written.

The two languages do not follow each other. A TypeScript file that imports a .js file (or the reverse, through a relative path, baseUrl or paths) has an unresolved call with the reason "names src/x.js, a JavaScript file, whose calls ripple does not follow from TypeScript": not a package, so not counted as code outside the repo, and not an edge. That holds for a file that only the other language's index reads (a .js file in dist/ is no file to either). An export * from such a file leaves the barrel's export set unknown: a name the barrel does not declare itself is unresolved with that reason, never taken from another export * (two stars that both provide it are an error to the compiler and fail to link at runtime). Where both define an id (x.ts beside x.js), the TypeScript symbol is kept and the JavaScript one left out, with the warning and exit status 3 described under "Both languages in one repo".

Config. A jsconfig.json is read like a tsconfig.json (baseUrl, paths, extends, include, and the JSX settings under JSX), for a file of either language. tsserver tries a directory's tsconfig.json and then its jsconfig.json, so a jsconfig.json is the project of every file the tsconfig.json beside it does not hold: a .js file, when the tsconfig.json has no allowJs, or a file its include leaves out. A config governs a .js file only when it allows JavaScript (allowJs or checkJs, and a jsconfig.json always does). A .ts file is the build's: the nearest tsconfig.json that holds it governs it, however near a jsconfig.json is (tsc builds it with that tsconfig.json's paths, where tsserver would open it in the nearer jsconfig.json), and only a file no tsconfig.json holds goes to the jsconfig.json above it that does, which is the project tsserver gives it. A wildcard include also drops a file when a same-named file of a higher extension priority is in it (m.js beside m.ts, p.jsx beside p.js, r.mjs beside r.mts): the compiler holds the other, so the dropped one is in no project (a name in files is always held). In JavaScript f < a > (b) is two comparisons, so a .js call that carries type arguments is left unresolved (the same text in a .ts file is a call), and so is a call inside or right after a syntax error: a name the grammar takes for a TypeScript keyword (abstract.foo(), using.foo()) breaks its statement and the grammar then reads a call of foo. Flow annotations in a .js file are read as the TypeScript annotations they look like, at the same trust: ripple checks neither. mocha's before and after are known globals.

Compiled output is not source. A directory that a tsconfig.json or jsconfig.json names as outDir (through the configs it extends and the ones it references in the repo, ${configDir} meaning the directory of the config that extends the base) is skipped at any depth in the TypeScript and JavaScript walks, and listed with the skipped directories, for the compiler leaves it out of the program: packages/core/dist/math.js beside packages/core/src/math.ts would otherwise define every function twice and make find_symbol("clamp") ambiguous. It is not skipped when it is, or is above, the directory of the config that names it, its rootDir, or a root of its include or files (emit in place, or the sources themselves), nor when it holds a .ts file that is no declaration (a compiler writes none), and the Python walk never skips it (a Python package may live where a TypeScript config writes its output; the directory is still listed, as skipped for TypeScript and JavaScript). The root build and dist are skipped as before. Emitted code that no config names (a build run with --outDir, or emit in place beside the sources) is read, and an id both languages define is the ambiguity warning described above.

JSX

A component element in a .tsx file (<Child />) is not a call, so it makes two other kinds of edge, and they answer different questions:

  • renders, the creator. The function whose body writes <Child />: who is running when the element is made. The tag is read the way a call's callee is (block scopes, imports, barrels, a namespace import <ui.Panel />), so a local Child hides the import. An element written in an arrow, a .map callback or a render prop belongs to the named function around it, as a call does. Host tags (<div />, anything that starts with a lowercase letter, <svg:rect />) are never components and make no edge. A tag that is a variable of unknown value, or a member of this, is unresolved. A component from outside the repo is counted as outside the repo.

  • renderer, the component React was rendering when it ran Child. For <Layout><Child /></Layout> written in Page, Page creates Child and Layout renders it. A renderer edge is reported only when the source proves it, and otherwise the element is listed as unresolved with the reason, so a missing renderer edge costs recall and never makes a wrong one. It is proven when

    • the element is part of what a component returns, through host elements, fragments (<>, React's Fragment, Suspense, StrictMode, Profiler), cond && <X />, ||, ??, conditionals, and the callback of a .map on a value known to be an array: that component is the renderer, and also the creator;

    • the element is a child of <P>...</P>, and P is a function component that puts its children prop (children, props.children, { children: kids }) where it returns it the same way: P is the renderer, not the component that wrote the child. When P hands its children to another component Q that places them (<Q>{children}</Q>), Q is the renderer and P is not (P is the renderer of Q);

    • the element is what a function written as a prop returns, <List render={(row) => <Item />} />, and List calls that prop where it places the result ({render(row)}, props.render(row)): List is the renderer. A call in an event handler or an effect is not render time and proves nothing.

    A function is a component, so that what it returns is rendered inside it, when some element in the repo names it and nothing in the repo calls it as a function or hands it on by name as a prop (render={Home}). Not proven, so unresolved: the element passed to a function (mount(<Page />)), assigned or stored first, children given to a wrapper from outside the repo (styled.ul), a context consumer, a component that does not place the prop, a .map whose receiver is not known to be an array, and any file the parser had to recover from. The children of an element that is itself an argument of cloneElement, createElement or Children.map (and forEach, toArray, only) get no renderer edge, because those calls may replace them; the renders edges stay. A prop the component assigns anywhere in its body, in any order (children = x, props = { ...props }, props.children = x, delete props.x, Object.assign(props, x), in a loop or in a function declared below), is not what the caller passed, so nothing the component does with it is proven.

    All of this is React's order of work: a component runs when React renders it, not when its element is made. A file whose JSX is compiled by another runtime (a @jsx h or @jsxImportSource pragma that is not React's, or a tsconfig jsxFactory, jsxFragmentFactory or jsxImportSource that is not) gets renders edges only, and its elements are unresolved with a reason that names the runtime. A bundler's own JSX setting outside tsconfig is not read.

Class components, memo, forwardRef, lazy, styled wrappers, Context.Consumer and cloneElement are not in the benchmark fixture, which has function components only, so they are checked only by small inline snippets (tests/test_ts_jsx.py), and implemented to resolve only what is provable. A class component's creator edges come from its render method (Box.render -> Child) and the renderer is the class React instantiates (Box -> Child), when it extends React's Component or PureComponent (imported as Component, React.Component, * as React or under an alias). That is the class a tag names, so a class that inherits render from a base is the renderer, never the base that defines it, and a class no element names, or whose render is called by hand (this.render(), super.render(), card.render()), is not proven. memo, forwardRef and lazy are named by the variable the tag uses: const X = memo(f) resolves to f when f is a function ripple can see (a function written inside the call is named X), and lazy(...) is never resolved. A wrapper from outside the repo between a parent and its child leaves the renderer unresolved, never the outer component.

Every query follows all kinds by default, and an entry with a JSX edge says which kinds it has and where each was written (edge_kinds, and sites_by_kind in the JSON; in the text, renders at a.tsx:3; renderer at a.tsx:3). ripple index counts the JSX edges apart ("93 resolved calls, 21 JSX edges, ...") and only when there are some. A renderer edge is placed at the line where the element is written, which can be in another file than its caller. impact follows every kind: a function that writes <Child /> is affected when Child changes (it can break what it renders), and so is the component that renders it. --kinds calls gives the answer without JSX, and --kinds renders the creators alone. Elements whose tag or renderer is unresolved are in the unresolved list of callees (and in the count of unresolved calls) with a reason that starts "the JSX tag is not a component ripple can name" or "the component that renders it is not proven"; impact does not list an unproven renderer as a possible missed caller, since its creator is already a caller.

Measured on the fixture, against ground truth derived by hand from the source and checked against a React 19 run of its tests (python -m bench.ts_score): renders 12 expected, 12 reported, precision 1.000, recall 1.000; renderer 9 expected, 9 reported, precision 1.000, recall 1.000. The fixture has the cases where the two kinds differ on purpose (children placed by a wrapper, a render prop). Read by hand against the source, with no runtime recorder behind it, on four real libraries (react-pro-sidebar, react-hot-toast, react-accessible-accordion, react-error-boundary): 69 renderer edges, grouped by the pattern each is written in, and well over 20 renders edges, none found false; the edges ripple left out there are the cost of not guessing, such as children handed to a component that spreads its props. That reading is evidence of the patterns it covers and nothing more.

At runtime, on a library outside the fixture. react-day-picker v10.0.2 (commit 1bfd4f0): its tests, and a smoke test that renders every example, ran under a recorder of which component React was rendering for each element. Before the paths fix above, ripple stated 446 JSX edges there: 445 true and 1 false, and the false one was that defect (an app that pins a published react-day-picker was resolved to the repo's own DayPicker; the same defect gave false calls edges). In detail:

  • renderer: 87 of 87 true. 80 were seen at runtime, and at each stated element line every runtime instance had ripple's component as its renderer; 7 are in the website app and were read by hand.

  • renders: 358 of 359 pairs true. 277 were seen at runtime (every stated site observed) and 82 were read by hand. The fix removes two pairs, the false one and a true one (the app that depends on the package as workspace:*, which ripple now leaves unresolved). That is arithmetic on the judgments above, not a second run.

  • Following references (the shadcn apps' tsconfig.json is "files": [] plus references to their tsconfig.app.json) adds 68 edges after that fix, all inside apps/shadcn-app-v9 and apps/shadcn-app-workspace, 34 in each (31 calls, 2 renders, 1 renderer): an app's @/components/ui/button and @/lib/utils now resolve to its own files. None reaches packages/react-day-picker. They were read neither by hand nor at runtime, so they are not in the figures above.

  • Recall in the tested scope (packages, examples, test): renders 277 of 314 pairs and renderer 80 of 163. The misses are mostly <components.X /> tags, members of an object a caller can override, which ripple does not resolve.

  • 28 synthetic React 18.3.1 cases of render props and of children handed to a second component produced no false edge: ripple stated 70 renderer edges and all 70 agreed with runtime. The cases were written by the person who measured, so they test the rules as stated, not shapes found in other code.

The limits: one library, and it had been read from source once before (a later commit, with no false edge found), so it is not a library nobody had looked at; the runtime was React 19.2.5, which the recorder was not validated on (it agreed at the element line everywhere it was checked); the website app was not run, so its 7 renderer and 76 renders edges are hand-judged. One false edge in 446 is 0.2 percent for this library and a weak guide to another library's configuration, which is where the false edge came from.

Both languages in one repo are indexed each with its own profile and merged into one graph; the cache keeps one entry per language (the Python one is named as it always was, so a Python repo's cache and output are what they were), and an edit to one language rebuilds only that language's graph. Python ids are dotted and TypeScript and JavaScript ids are paths, so nearly always no symbol or edge can be confused with the other language's. But any id can be defined by both: a root app.config.ts is the dotted module app.config, the id of def config in app.py, and util.py and util.ts are both util. For such an id ripple keeps the Python symbol and its edges, leaves out the TypeScript symbol and every TypeScript call that names it (so no chain runs from one language into the other through it), and no query answers for the id. The ids are counted and the first few named in the warnings. A .ts file that is Qt Linguist XML or binary (a video) is not TypeScript, and does not make a Python project mixed. ripple index prints each language's files read, with how many of them could not be parsed in brackets (the same for both languages), and the unparsable files one per line (the first 10, then a count). When part of the repo is left out, every result says so: the CLI exits 3 and prints the warning on stderr (a warnings list in --json), and each MCP tool result carries the same warnings list. That happens for ids both languages define, and when TypeScript cannot be indexed: a TypeScript-only repo is then refused with the install command and the reason, and a mixed repo is indexed as Python. The parser is "unavailable" whether it is missing or installed but does not fit (an ABI or version mismatch), and the reason is in the message. A result with no warnings key covers everything the repo has.

Go

Go is read by tree-sitter as well (pip install 'ripple-code[go]', which adds tree-sitter and tree-sitter-go; without it a Go-only repo is refused and a mixed repo is answered without its Go files, with a warning). --lang go or auto (.go). It has a resolver of its own (ripple/go_indexer.py), because Go has no overriding and a call T(x) is a conversion.

Symbols are import paths: github.com/spf13/cobra:Command.Execute (package, colon, Type.Method; value and pointer receivers are one method set), a package is github.com/spf13/cobra, and every file of a directory is that one package. An external test package is github.com/spf13/cobra_test, a second declaration of a name under build constraints is #2. The id is found by Command.Execute, cobra:Command.Execute, command.go:Command.Execute, or a directory (doc/).

Which module governs an import. The MAIN module of a build decides what an import path names: its replace and exclude directives apply to the whole build, and the replace directives of every other module are ignored (so a program that imports a module a whose go.mod replaces other with a checkout still gets the published other, unless its own module replaces it too). go.work says which modules are the main modules (a workspace applies the replaces of every member, its own first, and a module two members replace differently is refused). A module of the repo that is neither replaced nor in the workspace is built from its published version, so it counts as outside. A replace M v1.2.0 => ./b applies only when the build selects exactly v1.2.0: ripple reads that from the main module's require line when it states go 1.17 or later (go lists the selected version there, and refuses "updates to go.mod needed" when another is selected) unless the version is excluded; under an older go directive, in a workspace, or with two requires, a versioned replace is not known to apply and the import is unresolved, never external and never the checkout. A main module with a committed vendor/modules.txt builds from vendor/ by default, so its imports of other modules are unresolved too. go.mod is read by its grammar (blocks, quotes, comments, // indirect, retract). A call edge is resolved by the module its file is in, and drawn only when every module whose build contains that file (itself, and each module that replaces it or shares its go.work) names the same package for the import, so a file that one build links against the checkout and another against a published version has no callee. For an implements edge each program and test binary is resolved under its own root's module, closure and all, and a library call, which has no single main module, is held to every unit separately: one unit's module is enough, because each unit is a real build.

Proven: a function called by name or through an import (go.mod, replace to a local directory and go.work say which directory an import names, by the rule above), and a method called on a value whose type is written in the source (receiver, parameter, x := T{}, NewT(), a field, an element, a range variable, a type assertion, embedded structs by the language's depth rule; a method declared on an alias is its target's, and keeps the alias's name). Unresolved, each with its reason: an interface method call (the reason names the interface; it may also get implements edges, below), function values (a parameter, a local, a field, a package variable), type parameters, a value whose type is not written, anything that depends on which of several build-constrained definitions wins. Build constraints are never evaluated: a function defined under several has an edge to each variant, and a variable, a type, a result that the variants read differently, a method that only some builds declare (a //go:build line, a _linux.go name, a _test.go file) while another is promoted, or a method declared on an alias that is itself declared twice, is unresolved. A _test.go method counts only for a call in a _test.go file of the same directory (its package and its external _test package); a call in another directory's tests, whose binary links the package without its test files, runs the promoted method.

Interface implementers, the implements edge. A call v.M() through a repo interface stays unresolved, and also gets an edge of a kind of its own, implements, to T.M for each repo type T that provably satisfies the whole interface (*T's method set, the largest: a T or a *T is what an interface can hold). It is never a call edge and never joins one: the answers list it under may_be_called_through_interface (callers), may_be_reached_through_interface (impact) and may_dispatch_to (callees), in the words "may" and "possible", with a note that the list is never complete: a type from outside the repo, a type declared in a function, or any type ripple cannot prove can satisfy the interface too, and the call is still listed as unresolved. Each edge claims one thing, that the method belongs to a repo type that satisfies the interface in a build that contains the call, and ripple leaves a candidate out unless the source proves it by the spec: the interface and what it embeds are declared once, read whole, with no type parameters and nothing from outside the repo; every parameter and result of each method is one canonical type on both sides (aliases resolved, byte is uint8; a function type, a generic instance, a name a dot import binds, an array length that is not an integer or rune literal in Go's own grammar ([010] is 8, [0x10] is 16) and an import of an outside package that is not the standard library and has no alias are refused; channel directions are read as Go reads them, so chan<- chan int and chan (<-chan int) are two types); the type is declared once, is not generic, is not a defined pointer type (type P *S has no methods, not even S's) and is in no build-constrained or cgo file; each method is found by the depth rule with no outside embedded type that could provide it first, is declared once in every build, and an unexported name belongs to the interface's own package.

Which builds contain the call is one rule, for the three places a call can be. A program links exactly its import closure, and a test binary links its package with the _test.go files, its external test package and what those import, never another package's test files. The closure counts only what every build of a package imports: a file under a build constraint, a platform file name, or a file that imports "C" (CGO off leaves it out) adds its imports to the builds that have it and to no other, so none of them is counted; a blank import links its package. A call in a _test.go file (with or without a constraint) is in its directory's test binary and in no other build, so a type is a candidate only when that binary links its package, and a _test.go type only for a call in the same directory's tests. A call in a package main is in that program and in its directory's test binary and nowhere else (nobody imports a main package), so only a type those two link is a candidate. A call in any other package is in every program and test binary that links it, and in a program of another repository that imports it, so the claim is that some build has both: a type is a candidate when a program or test binary of the repo links both packages (a type of a package main is in its program and its test binary alone, so that is its only way in), or when both packages can be imported from outside (neither is a main package or has an internal element in its import path) and one module of the repo builds against both modules, which is the rule an import across modules already follows (the same module, or a replace or a go.work joins them). A module of the repo that is neither replaced nor in the workspace is built from its published version, which may differ from the checkout, so none of its types is a candidate for a call of a module that does not build against it. Where no build can be shown to hold both (an internal package nothing links with the call's package), the candidate is left out.

bench/go_oracle (-implementers) writes what types.Implements and the method sets say for each interface call, per build unit and never as a union of programs: the universe of a call in a package main is that program's closure, of a call in a test file that test binary's, and of a call in a library the packages some unit links with it plus the packages that a program outside could import with it (the modules the go tool's own build list says the run builds against are loaded with it). A candidate is agreed when some build has it and no build that has its package lacks it. tests/test_go_implements.py holds ripple to that and to the // want: comment on each call of the impl_* probes, and tests/test_go_build_units.py fails if the oracle's answer for a call in a package main lists a type of a package that program does not link. Run against that oracle on linux, windows and darwin: gin 175 edges (all 175 confirmed, 27 of the 87 interface calls ripple recognises have one, 175 of the 238 candidates the compiler agrees on), etcd as one go.work run 6,689 edges (all 6,711 site and method pairs confirmed, 3,704 of 6,059 calls, 6,711 of 11,356 candidates; the rest are left out for an interface or method signature ripple does not follow, 3,024, a test binary or program whose imports are not provable, 1,399, a signature, 124, a method the depth rule cannot place, 98; a second run with -tags cluster_proxy confirms the 5 edges of the one file the first run does not build), cobra none, and none unconfirmed on bubbletea, chi, fzf, lo, testify, urfave-cli, viper or zap. The version before this rule drew 6,708 etcd edges: 19 of them were a call in a package main given the type of a program it does not link, 12 contradicted by this oracle and 7 in files the go.work run does not build (the old oracle merged every program into one build, so it confirmed such edges, and a probe wrote them into its // want:). Call edges and the externals are unchanged: with the implements edges taken out the graphs of gin, cobra, the Python warehouse fixture and the TypeScript warehouse fixture equal what the version before gave, and no call edge of etcd, bubbletea, chi, fzf, lo, testify, urfave-cli, viper or zap moved with the // +build reading below.

A call in a constrained file (a platform file name or a build constraint, not a plain _test.go) is only in the builds that have the file, so the type's package must build in one of them: for some GOOS/GOARCH pair (and the custom tags the call file's header names) the package and every repo package it imports there must have a non-test file in that build that does not import "C", and no import may be unresolved; otherwise the candidate is left out. The compiler cannot answer this by a probe (the oracle stops at the package error), so tests/test_go_platform_package.py holds it.

Build constraints. A file's constraint is read as go/build reads it, and a committed table proves it: bench/go_oracle/go_build_table.py writes go_build_table.json, the verdict of go list (Go 1.27.4) for 70 header forms against 36 file-name forms on twelve GOOS/GOARCH/tag runs (a byte order mark, no-break space, vertical tab, a second dot in x_linux.pb.go, an old-style line of more than 100 operators, //go:build after the package clause, ...), and tests/test_go_build_table.py (no Go needed) holds ripple's port of parseFileHeader, shouldBuild, constraint.Parse, goodOSArchFile and matchTag to every cell. A //go:build line decides alone; otherwise every old-style // +build line must hold (spaces are or, commas and, ! not; a term that is not a tag, !!x or an empty line is the tag ignore, which no build has), and a line counts only when it is above the last blank line of the file's leading comment stretch, so one with no blank line after it (package documentation), one after a block comment, or one after the package clause is no constraint. The file-name suffixes _GOOS, _GOARCH, _GOOS_GOARCH and _test, and the files the go tool ignores (a name that starts with _ or ., a testdata or vendor directory, a file no build includes), are read as before. This also fixes a call edge: a method declared in a // +build linux file while another is promoted is now unresolved (it was the edge to the linux one, wrong on every other platform), as a //go:build one always was.

External (a call that provably cannot reach repo code, which an agent may skip) is only what the Go standard library's own source proves: a func declaration of a standard library package, a method of a standard library type that is not an interface, a method of a standard library interface that no repo type declares, a builtin. Ripple reads no package outside the repo, so a member of one it cannot prove is unresolved, not external: pkg.F(x) of any other outside package (a function, or a variable holding one), flag.Usage() (a variable), tp.DialContext(...) or cmd.RunE(...) (a field of function type, which can hold a repo function), a value whose type ripple cannot write. The proof is ripple/go_stdlib.py, generated from GOROOT by bench/go_stdlib/generate.py over every platform go tool dist list names. A C.f(x) call is unresolved as well: C code may call back into an //export-ed function of the repo. On cobra, gin, zap, chi and etcd the external count fell by 286, 2617, 814, 272 and 12419 and the unresolved count rose by 286, 2598, 808, 109 and 12274 (the rest are conversions such as http.HandlerFunc(f), which are no call and are no longer counted); no edge changed.

vendor, testdata and _x directories (wherever a go.mod sits: a module fixture under testdata is not read) and files no build includes (//go:build ignore) are skipped as the go tool skips them, and ripple index lists the directories (.x ones, which no language reads, are left out like the other languages'); generated files are read, because the rest of the package calls into them. A file tree-sitter-go 0.25 cannot parse (Go 1.26 new(expr)) is listed. If the broken code is inside a function body whose braces, read with Go's lexical rules, close it at its last byte, only that function's calls are unresolved. If it is anywhere else, tree-sitter loses the declarations after it, so the whole package is treated as having unread declarations, whatever the layout or comments around them: a name or method is still proven when a declaration of it is built in every build (no constraint, no platform file name), because a second one would not compile, but a name or method declared only in constrained files, a promoted method, a missing member or a universe name (len) in that package (or in a package that imports it) is unresolved with a reason naming the file, and a call on an outside type is not counted external when the file's text declares a method of that name.

check for Go runs go test -json -count=1 -skip= -list= -c=false -fuzz= -run= (-count=1: a verdict of a run made now, never a cached one; the rest is explained under GOFLAGS below, and -skip needs Go 1.20 or later) and reads the verdict from the event stream (ripple/go_check.py), never from the exit code alone or from the log text. With no arguments it runs ./... in every module of the repo (a nested go.mod is its own run, since the parent's ./... leaves it out; vendor, testdata and .x/_x directories are skipped as Go skips them). go must be on PATH (otherwise a refusal that names --test-command). The arguments:

  • a directory (./dir/... in the module that holds it, when that module has a package below the directory outside the nested modules, and ./... in every module below it: a directory of nested modules is only their runs, since go test fails on a pattern that matches no package. That holder run is also planned when the directory has only .go files Go leaves out of the build (a //go:build ignore generator next to the nested modules), where go test says matched no packages and exits 1 with no event: that run is an empty run, not a failure, but only when a nested module below the directory ran packages of its own. With nothing below it having run, the message stays a problem), a _test.go file (the tests it declares that go test runs: an Example with no // Output: or // Unordered output: comment is compiled and never run, so it is left out, and refused by name), or file_test.go::TestName and file_test.go::TestName/sub/case (a space in a subtest's name is written _, as Go names it);

  • the id impact lists for a test function, file_test.go::TestName (see "Go tests in impact" below). check also takes the symbol id of a test, example.com/mod/pkg:TestName (.../pkg_test:TestName in an external test package), which an older impact listed among the callers, and finds the file that declares it.

Ids become go test -run '^(TestA|TestB)$' <package dirs> (with the flags above), run in the module that holds the package, with the pattern built per package: a test name two packages share runs only in the package it was asked for in, and subtests are levels of the pattern (regexp-quoted), one pattern per parent with only the last level alternated (TestGrid/x/1 and TestGrid/y/2 are ^TestGrid$/^x$/^(1)$ and ^TestGrid$/^y$/^(2)$, two runs, never (x|y)/(1|2), which would also run x/2 and y/1), so no run is broader or narrower than the ids. An id for a test the file does not declare is refused before anything runs. Nothing a caller supplies is read from outside the repo: paths and symbol ids are resolved and contained before any file is listed or read, and a go.mod or _test.go that links out is not read.

What is never reported as passed (each has a stream captured from the real toolchain in tests/fixtures/go_check/, with the module that made it and the command): a build or vet failure, a package with no test files when nothing else ran, a -run pattern that matches nothing (Go exits 0 and says "no tests to run"), a panic or Go's own timeout, a test that started and never finished, a test binary that exits early or is killed (syscall.Exit(0) in a test exits 0 and the package never reports at all), a requested test or subtest with no result of its own (the parent passing does not count) and a requested test that was skipped. Whatever go test exits with, a failing event is a failure, and an exit status with no failing event is reported too. The result has the usual keys plus problems (why a run is not a clean pass), counts (top-level tests, subtests and packages apart) and notes; failures read FAILED file_test.go::TestName: first message or panic line, and a failed subtest is listed after its parent. A package that reports ok has to show that its tests ran to the end or that it had none: a test binary that ran them prints PASS, and one that exited 0 before m.Run, from a TestMain or an init that calls os.Exit(0), prints only the ok line, a problem in every run shape (with other packages, as a directory argument or alone). A package with no test event needs Go's own word that there was nothing to run, testing: warning: no tests to run or the [no tests to run] suffix on its ok line (or [no test files]): benchmarks only, helpers only, output-less examples only and a build-excluded test file print it and pass (a note when other tests ran, "no tests ran" when none did), while a TestMain that prints PASS itself and exits 0 prints no such notice and is a problem. A directory argument none of whose packages ran a test (no test files, or all skipped) is "no test ran there". A benchmark has a run event and never a pass or fail one, so it is neither counted nor reported (a benchmark that fails is a failure). When a request splits into several runs (two subtests of one test with different parents), each package, test and subtest is counted and listed once, a test the runs disagree about is the worse of the two (a parent that passes in one run and fails in another is a failure), and a problem two runs share is said once. An argument over a file system's limits (a name over 255 bytes, a path over 4096, a NUL, a string that does not encode) is a refusal, not an exception.

GOFLAGS reaches every go test, from the environment or from the go env file (go env -w GOFLAGS=...), in spellings ripple does not try to read (-run, -test.run, quoted, --run). So it does not read them: the flags that decide which tests run, or whether any does, are on the command line, which wins over GOFLAGS for every spelling. -skip= leaves no test out, -list= and -c=false stop go test from only listing or only compiling, -fuzz= from fuzzing in place of the tests, and -run= (a run with no pattern of its own, where an id gives its own -run) runs everything, examples with an output comment included. They change nothing in an ordinary run (the event streams are the same, checked live against a run without them). What stays yours is your build configuration: -tags, -short, -vet, -shuffle, -failfast, -timeout, -race, -bench, -o, -json and -exec, which can leave a test out (a //go:build !foo file under -tags=foo, a test that returns under -short) the way a go test ./... by hand would. They are named in a note when go env GOFLAGS (asked for within the run's timeout, and no note when it fails or hangs) says anything. -exec is your runner: one that never runs the test binary leaves a package with no events, which is not a pass. With -bench, Go prints no "no tests to run" notice, so a helpers-only package is reported as a problem there, the same as a TestMain that prints PASS (a false failure under an unusual GOFLAGS, never a false pass). --test-command still means exactly that command, read the generic way. check picks the Go runner from the profile (--lang go, or a repo whose only language is Go: a stray Python or TypeScript file makes auto refuse and name the languages, so pass --lang go there). A second language's runner goes in checker.RUNNERS (profile name to a module with normalize and run), so that adding one leaves the profile, whose fields are hashed into the cache key, alone. Every stream was captured with Go 1.27.4; no older Go was run, so its event shapes are unverified (a package that fails with no failing test and no build event is reported as such, never as a pass).

Go tests in impact. A Go test that reaches the symbol is listed under tests as file_test.go::TestName (the file is the repo-relative path, a/a_test.go::TestSame), the form check takes first, so the ids go straight into check: ripple check --lang go a/a_test.go::TestSame. The ids follow the go command's own selection rules (checked against go test -list, tests/test_go_impact_tests.py): TestXxx(t *testing.T), FuzzXxx(f *testing.F) (plain go test runs only its seeds, so it is listed only when the target has an f.Add(...) statement before f.Fuzz) and ExampleXxx() whose last comment is // Output: or // Unordered output:, in a _test.go file (an external test package, package m_test, included: it is built into the same test binary), where the name after the prefix does not start with a lowercase letter. TestMain(m *testing.M) is not a test. A t.Run subtest is not collected on its own; a change reached only through one lists the parent test, whose closure holds the call. A helper that takes *testing.T but is not named like a test is a caller, as before. What impact gives no id, it says: tests_not_listed holds each caller that looks like a test, with the reason, and it stays among the callers too. The rule behind it: every caller impact reaches that runs in a test binary without being called by a listed test is named. So it also holds:

  • TestMain, an init and a package variable's initializer in a _test.go file, which run before every test of the directory's binary (the package and its external test package): one entry names the directory, and check takes the directory (with the symbol broken, go fails the directory's tests, checked on a module for each of the three);

  • an init or a package variable's initializer in any other file, which runs in every binary that links the package: one entry says so, and does not list those tests;

  • a method named like a test in a _test.go file (a suite runs it by reflection), and any other symbol of a _test.go file that no listed test is known to call within the depth asked.

A call through a function value (f := pkg.Fn; f(1)) is not an edge, so a test that does that is not reached at all and is not named: this is the call graph's recall gap, the same as for any other caller. The cases with no id:

  • a benchmark (go test runs it only with -bench, and check does not take one);

  • an example with no output comment (compiled, never run), or whose output comment check cannot read (/* */, or after code on its line);

  • a test in a file only some builds have (a //go:build line, x_linux_test.go): which of its tests your go test runs is not known;

  • every test of a directory where go test fails the package: a Test, Benchmark or Fuzz function with a signature go refuses, a malformed name (Testfoo(t *testing.T)) or an // Output: that is not the last comment, which go vet fails;

  • a fuzz target with no visible seed (without -fuzz go runs no input, so the fuzz function never executes and a pass proves nothing; testdata/fuzz is not read, since the cache does not fingerprint it);

  • a name declared more than once in the directory, in any _test.go file whatever its constraint (go test -run runs each);

  • a directory with no go.mod above it, with a file ripple could not read completely, or a test file that imports "C".

Not modelled: what go vet makes of an example's name (an ExampleFoo where Foo does not exist fails vet, and so check, with go's own message), and which tags or platform your build has (a file with any constraint is left out, never guessed). An unconstrained test file is assumed to build, as the rest of the package does. The ids live in the graph (Graph.test_ids, decided where the files are read), so the cache moved with this change.

bench/fixtures/go/probes holds 157 small legal Go modules, each with what the Go compiler's type checker says every call site calls on linux, windows and darwin (bench/go_oracle/generate.py, run by hand with Go installed), plus the cgo ones that state their own answer. tests/test_go_probes.py needs no Go: an edge ripple makes must be the compiler's callee, declared in the file ripple edged to, on every platform that builds the file, and a call it counts external must have no callee inside the probe and must not be a function value, each checked at the call's own position (so two calls on one line are each held to their own answer). tests/test_go_layout.py writes every probe and golden fixture again with comments after every token, with the indentation stripped or doubled and with CRLF line ends, and requires the same graph.

Rust

Rust is read by tree-sitter too, as an optional extra that adds tree-sitter, tree-sitter-rust (and tomli before Python 3.11, to read Cargo.toml). The base install is unchanged, and a repo of any other language is read without it (a Rust-only repo is refused with the install command; a mixed repo is answered without its Rust files, with a warning).

uv tool install "ripple-code[rust] @ git+https://github.com/xtelos/ripple"   # or pip install 'ripple-code[rust]'

--lang rust (or auto, which finds .rs files) reads the repo. The crate graph comes from Cargo.toml and the source: every package and the crates it builds (the library, binaries, tests, examples, benches and build.rs, with [lib] and [[bin]] path overrides), the dependencies each can name (path dependencies, renamed ones, hyphens as underscores, a library under its own name), and the mod tree from each crate root (mod x;, #[path], inline modules, mod.rs). A .rs file no mod reaches and a mod that names no file are listed as not read (a note of their own, apart from the files ripple could not parse), and so is a Cargo.toml that cannot be read; one with a field of the wrong type costs its package, and whatever depends on it finds its library unread, never the rest of the repo. A target directory beside a Cargo.toml is not walked.

Symbols are the file's path without .rs (x/mod.rs is x; lib.rs and main.rs are not folded), a colon and the member joined by ::: src/cli:parse_args, src/x:Foo::new, src/lib:tests::it_works, src/x:Tr::m (a trait's declaration), src/x:<Foo as Display>::fmt (a trait impl: its file is the impl block's, not the type's). A second definition of one id (two fn imp under different cfgs) gets #2. Any of these finds a symbol when it names one: the id, the file with or without .rs, Foo::new, or the bare new.

Resolved: a call by path: f(), m::f(), crate::, self::, super::, Type::f(), Self::f(), Trait::f(x) (the declaration, with each impl in the repo as an override edge) and <T as Trait>::f(), through use lists, aliases, globs (only the names visible to the importing module) and pub use re-exports, and the arguments of the standard macros (println!, format!, vec!, assert_eq!, ...), which are parsed again as expressions. A constructor (Some(x), Pair(1, 2)) runs no code and is neither an edge nor unresolved. Type::f() is an edge for an inherent function of a repo type, and for a function of a repo trait that has one impl for the type and no blanket impl; a trait from outside the repo is never one (the standard library may implement it for the type in ways ripple does not read). A method call recv.m() is an edge in one case only, the first step of rustc's method probe: the receiver is self, or a name bound once in the function by a parameter or a let that writes its type as a struct, enum or union of the repo (S, &S, &mut S, Self, through an alias or a renamed import too), the call is where that let is in effect (after it, in its block), and an inherent method m of that type takes the receiver in the form the receiver has: self for an S, &self for a &S, &mut self for a &mut S. rustc tries a type by value before it takes a reference and an inherent method before a trait's, so that method is found first, whatever traits are in scope and whatever other types the receiver derefs to. The type arguments written must select the one impl (impl W<u8> and impl W<u16> are told apart; a generic receiver W<T> selects only an impl for every T). A type name in that proof is resolved where it is written, never compared as text: arguments are compared only when each is built of primitive types (u8, (u8, bool), [u8; 4], &u8) and every primitive name, looked up in the scope of the impl and of the call, is the primitive (a struct, an enum, an alias, an import, a glob, a generic parameter or a macro that may make a name called u8 there makes W<u8> another type; probe method_type_names, compiled and run, for a method call and for a path call W::<u8>::m(w), which had the same defect). A prelude type (Vec<u8>, Option<u8>, String), a std path, Self and every other type are never compared: the scope may have replaced them. An impl ripple did not see is not a reason to refuse: rustc rejects a second inherent method of one name for a type (E0592) whatever its receiver form, and takes the inherent method before every trait's and every Deref's at this step, so an impl a macro made cannot change which function the call finds (compiled cases in bench/fixtures/rust-probes/crates/method_macros, method_rebind_*). What can change it is source ripple did not read, which rebinds the receiver or the type name where no rule of a scope sees it (a textual macro_rules! println in an unread #[macro_use] module makes println!(s); bind s: probe method_unread_macro_use), so a crate (or one that can name the type) is refused wherever part of its source is unread: a mod that names no file, a file of the crate's source directory that no mod reaches, a #[path] or a cfg_attr(.., path = ..) ripple does not follow (the latter whether or not a default file exists), modules nested beyond what ripple follows, a mod written in a block, a file the parser could not read whole, include! (a build script's generated file too), and a macro invoked where an item may stand that may expand to mod x; or include!(..) (probes: both build at the module level; neither in an impl or a trait body, nor in the statements of a block, where a mod needs a #[path] and is a block module, nor in an expression): an attribute macro or a derive that is not a standard one or a trusted one on an item of a module, and an invocation of a macro that is not a standard one unless it is a macro_rules! of the repo that provably brings none. That proof is for two forms only: a bare name that a macro_rules! written earlier in the same module reaches (not itself under an attribute that may remove it), or a path from crate, self or super where no #[macro_use] extern crate and no glob from outside the repo may bring another macro of the name. The name is the repo's alone (no procedural macro, and a use that gives it is the macro's own path), the body and the invocation's tokens have no mod, include or macro_rules token, and every macro the body invokes is named so that one macro is meant: std::, core:: or alloc:: and a macro of a short written list (println!, format!, concat!, stringify!, vec!, ...), or the same bare where no use of the crate gives the name (use std::include as concat; makes concat! bring a file: probe method_unread_alias_std; pub(crate) use declare as stringify; is the same with a repo macro: method_unread_alias_repo) and no #[macro_use] extern crate may, or a bare macro of the repo whose macro_rules! is in textual scope at the invocation and is proven the same way (one defined in another module may be another macro there: method_unread_nested_ext). A path through $crate, crate, self, super or another crate inside a body is not followed. A macro invoked in a block, an impl or a trait body, or in expression position, costs nothing crate-wide: its reach is the block (rustc reports a macro_rules! that a macro made and that redefines a standard macro as ambiguous, E0659), and the receiver rules below see it. The receiver name and the type name are trusted only where a rule of the scope says nothing rebinds them, with no crate-wide refusal behind it (the tests run every probe with it off): a macro invoked as a statement in a block around the call (or in a pattern: let bind!() = x;, an arm, an if let, a for, a closure parameter), a name bound twice, and anything in a block around the call that may give the name another meaning: an item of the name in the value namespace (a fn, a const, a static, a unit or tuple struct, a foreign item), an import that gives the name (use m::s;, use m::t as s;, in a list), any glob import (it may give any name), a macro that may have made the name, or a statement of a kind with no rule (the allow-list is BLOCK_DECLARES, BLOCK_IMPORTS, BLOCK_TYPE_ONLY and BLOCK_NO_NAMES: a type, trait, impl, macro or extern crate item, a let, an expression statement and a comment cannot give a value name; probe method_block_names, each compiled and run), a glob or a macro that may have made the type's name, an attribute macro on the function, the impl or the module, and the standard macros' own names (println! and the rest are the standard ones only where no macro_rules! of the repo, no use and no #[macro_use] extern crate gives the name, and no block holds a #[macro_use] mod; a glob that gives one is ambiguous with the prelude's, E0659). And only when nothing the proof reads is conditional or hidden. Conditional compilation anywhere between the crate root and the thing read refuses the call (but for a cfg the call is under too, below): the read things are the method (with its parameters, generics and body's inner attributes), its impl (its generics, type and inner attributes, and every function, impl, trait, block, match arm, statement, array, tuple or call element, struct-expression field and inline or file module around it), the receiver type's generics and where clause, the receiver's own let or parameter (#[cfg(..)] let s: &S), and an argument of the call. An attribute is read as harmless only if it is on a written list (INERT_ATTRS: allow, warn, deny, forbid, expect, doc, must_use, inline, cold, deprecated, track_caller, repr, non_exhaustive, automatically_derived, derive, tool attributes such as rustfmt::skip, and plainly path, macro_use, macro_export); a cfg_attr is harmless if every attribute it adds is. Every other attribute (cfg, test, an attribute macro, a cfg_attr that adds one of those, cfg_attr(.., path = ..)) is conditional, in any position the grammar gives one (outer or inner; ATTRIBUTE_PARENTS; a position it does not parse is a file the crate refuses whole). A cfg on the call's own statement, block or function is no reason (an edge says "if this call exists, it calls that"). Probes method_cfg_places and method_cfg_bindings build every position. This is the same reading for path calls: an inherent function the impl, a function body, an arm or a module file removes with an inner #![cfg(..)] (impl S { #![cfg(any())] fn m }, which main drew an edge to, wrongly) or whose impl is inside any conditional node is no longer chosen over a trait's function that would stand in its place, unless the call is under that cfg too (next paragraph). Not private to another module, not in an impl with bounds (impl<T: Bound> W<T>, a where clause, ?Sized), which a receiver may not meet. A method call is never an override edge and never counted as outside the repo. A cfg that governs both the call and the declaration does not make the declaration conditional for that call (method calls and path calls alike, Index.shares_cfg): an edge is drawn only if every conditional attribute on the path from the crate root to the declaration (the method, its impl, the type, and everything enclosing them: modules, a mod x; declaration's attributes for a file module, a file's own #![cfg(..)], functions, blocks, arms) is also on the path from the crate root to the call, as the same attribute on the same syntactic ancestor in the same crate (an attribute is its crate, file and byte). The call then exists only if the declaration does, and the program is read as if those attributes were not there; a second definition under another cfg is still counted and refuses (SEVERAL), and one the tool does not see is a duplicate rustc rejects (E0592) wherever both exist. An attribute on the impl or the method when the call is outside it, on a generic parameter of the impl, on the receiver's own let or parameter (never an ancestor of the call), or in another crate's copy of a file is not shared; nor is an attribute that does more than make its host exist or not (head_shared: cfg, and a cfg_attr of those and inert attributes; test, path, no_implicit_prelude and attribute macros are not). A path call (Self::f(), <Self>::f(), T::f()) into an inherent function that is not shared in that way is never an edge (CFG_UNKNOWN), as for a method call. Where the function is not built, the call finds whatever else gives the name, and ripple cannot close that set: an impl of the type under the opposite cfg (for W<A> with type A = u8, or an impl for every T, or a call that writes no type arguments, ripple cannot say which impl applies), a repo trait (a blanket impl too), a provided method of a standard or foreign trait the type implements (Iterator::count, PartialEq::ne), the reflexive From and TryFrom, a foreign crate's extension trait. Where nothing else gives the name the crate does not build with the function off, so no edge is lost that a build with the call has; on ripgrep, clap, serde, mini-redis, fd and bat no site changes. Before, the edge was drawn when no trait impl written for the type gave the name, which is wrong for each of those (probes path_self_cfg groups A and D and path_self_cfg_ext, compiled and run under each feature setting; their oracle is rust-analyzer's). The call and the function under one predicate, and an unconditional function, stay edges (group B). CACHE_FORMAT -42. The type arguments of an impl and of a call are compared as the type they name (canonical_type): (u8) is u8, & u8 is &u8, and [u8; 4usize], [u8; 0x4] and [u8; 04] are [u8; 4]. Compared as written, a trait impl for W<(u8)> was another type than W<u8>, so W::<(u8)>::f() got an edge to the trait impl where the inherent function of W<u8> runs (group E). A type argument that is not built of primitives, tuples, arrays and references of them is still never compared. Two rules satisfy a conditional attribute of the declaration's path: the same attribute on the call's path (above), and the same predicate (cfg_covers): another attribute on the call's path whose predicate is the identical tokens, so ripgrep's #[cfg(test)] mod testutil; holding the impl and its sibling #[cfg(test)] mod tests holding the calls is an edge (SearcherTester::new and its like: 69 of the path edges that the shared-attribute rule alone lost in ripgrep), under five conditions, each one a probe that refuses when it is broken. (1) One crate reads both: a file that is a module of the library and of the binary is two crates (cfg(test) is on in the binary's test build and off in the library it links), and so are an integration test, an example, a bench, a build script, a procedural macro crate and every other member of a workspace (a feature is a crate's own too). (2) Both are plain #[cfg(..)] or #![cfg(..)] written in place: never a cfg_attr, cfg!, a predicate a macro made, or an item an attribute macro rewrites (#[stripcfg] deletes the cfgs inside it). (3) The predicates are compared token by token: comments and white space between tokens are nothing, every literal is compared byte for byte ("a b" is not "a b", r"x" and "\x61" are not "x" and "a"), and the order matters (all(a, b) is not all(b, a): no boolean reasoning; recall lost, never an edge drawn). (4) Every other conditional attribute on the declaration's path is matched, one by one, by identity or by this rule, and one that is not refuses; an attribute in the header of the impl or the method (a generic, a parameter, a where clause) is matched by identity only. (5) A second definition that could win is refused as before: two under one predicate are an error rustc rejects (E0592), one under not(P) or another predicate beside the one under P is SEVERAL, and a trait method found at an earlier probe step, a use or glob that gives the receiver another type, and a type under another predicate than the call's refuse. Probes method_cfg_shared, method_cfg_shared_macro, method_cfg_crates (one file that is a module of both the library and the binary), method_cfg_predicate, method_cfg_predicate_crates (a workspace: the targets of a package, another member, a procedural macro crate) and method_cfg_predicate_macros (compiled and run: cargo test has cfg(test) on, cargo run --bin show is the build without it, and a feature off is --no-default-features) and the E0592 programs in bench/fixtures/rust-probes/shared_cfg_errors answer each case. A macro in a pattern of a function (a let, an arm, an if let, a for, a parameter) may bind any name (a procedural macro binds helper for a call of helper()), so the function's receivers, and its single-name path calls, are unresolved. A block is a scope of its own wherever a body holds one: a function, a const or static initializer (also inside a function), the initializer of an associated const of an impl or a trait, an inline const { .. }, an array length or const generic argument written in an expression (a name the block declares or imports comes before a glob's, as rustc does; each position built). A call in an enum discriminant, or in an array length or const generic default of a signature or type, is read by no body, so it has no verdict. Calls outside the repo are counted with the reason (the standard library, a crate from outside, the prelude, a primitive, a derive), and only when nothing of the repo can be what runs: a path through a trait (fmt::Display::fmt(&x, f), FromStr::from_str(s)) that a repo impl of that trait could answer is unresolved. None of the standard library's own names is taken as the library's in a crate whose standard prelude, or std, core or alloc, may be another crate (a dependency of that key or library name, a patch, a config of the repo, a path outside the repo, or the crate's own #[prelude_import]; each built with rustc): a name only the prelude gives (Vec, Default, drop, Some, a primitive type's name, the blanket S::to_string(&s)), and a path that starts at std, core or alloc (also a macro written from them), are unresolved, and #[test], #[bench], #[derive] and #[global_allocator] are read as macros that may have made names. The macros written bare (println!, vec!, assert_eq!) stay the library's: they come from the sysroot whatever the prelude is, unless the crate says #[macro_use] extern crate std; (or core or alloc, with an alias, under a #[cfg] or cfg_attr, the #![no_std] idiom) where that name may be another crate: the extern crate is then that crate, its #[macro_export] macros come before the sysroot's, and a bare macro is read as one ripple has not read, so its arguments are not calls (each built with rustc). Where std is the real crate that line changes nothing. A [patch], a [replace] or a paths override is never an edge; it makes a dependency unresolved (Rule P). Whether cargo applies one depends on more than a manifest reader can follow: the source it patches, the version it has against the requirement, a Cargo.lock that pins the dependency, which root governs the package, members against exclude, a package.workspace, a git dependency with no version taking a pre-release, a config that is read only from below its .cargo (each built with cargo, the probes in bench/fixtures/rust-probes/crates/_patch_source and _redirect_reach pass only when cargo does what they say), so ripple does not decide it. It refuses instead, by what it can read of each redirect, and in every case where it can see a redirect and cannot read it. A dependency that is not a path dependency (a registry or git one) is unresolved, never an edge through the redirect and never external, when it may be redirected: (1) its package name (the dependency's key, or its package =) is named by any [patch.<anything>] or [replace] entry ripple can read in the analysed directory, in any manifest (a root, a member, a lone package, an excluded one, a member's own that cargo ignores, one in a directory with no source file) or any cargo config of it, whether or not cargo would apply that entry (a name is a word of a [replace] key, so foo, foo:1.0.0, url#foo:1.0.0); or a vendored source directory inside the analysed directory holds a package of that name (below); or (2) a manifest that may govern the package was not read (a package.workspace naming one outside the analysed directory, a Cargo.toml above the analysed directory, one that cannot be read, a config that cannot be read) and the name is that of a package of the repo, which an unseen patch could point at. Otherwise it is the fetched crate, outside the repo. A vendored source is the one way besides a [patch] and a [replace] that a name becomes a package of the repo: [source.<name>] directory = "dir" in a cargo config, what cargo vendor prints, makes cargo build the package of a registry or git dependency from that directory (built, with the table written as a header, as dotted keys, as inline tables and through a chain of replace-with, and for a git source). Ripple indexes that package, so a registry or git dependency that has a package of its name at or below such a directory inside the analysed directory is unresolved: never external, and no edge is drawn into vendor/. The name is the one in the package's Cargo.toml, not its directory's (vendor/foo-1.0.0 holds foo). Which source replaces which is not asked, and every directory below it is read, a dot directory excepted (cargo reads only its direct children, so reading more only refuses more). A link is not entered, so that a loop ends, except where cargo follows one (it keeps a direct child whose Cargo.toml exists, following links; built): a direct child that is a link to a directory inside the analysed directory is a package of the repo, whose code runs, so its name counts; one that points outside the analysed directory is a crate from outside it, and the dependency stays external; a link that dangles, loops or names a file holds no package; the configured directory may itself be a link, read where it really is; and a Cargo.toml that is a link is read through it. A dependency with no package of its name there stays external, and so does every dependency when the directory is outside the analysed directory (the crates there are crates from outside the repo). A [source] table ripple cannot read, or a vendored directory holding a Cargo.toml it cannot read, makes every registry or git dependency unresolved; a path dependency into vendor/ is an edge, as any path dependency is. A path dependency is an edge to the directory its path names unless it may be redirected, which cargo does in two ways ripple reads by name (each built): an entry of a [patch.<key>] table of the dependency's name (the key, or its package =), unless the key is crates-io or an http, https, ssh or git url, which cannot be a path source's url (cargo leaves such a patch unused), where a file: url is the url of a path source and a registry name or anything else is read as one, since ripple cannot tell which index url a name stands for; an entry of a [replace] of that name whose key holds file: or path+, the id of a package of a path source, which cargo applies when the entry has a source of its own (foo:1.0.0, foo@1.0.0 and the id of a registry or git source are not a path package's, and cargo leaves the path dependency alone: the edge is right there). A [patch.crates-io] therefore leaves a path dependency an edge. A third redirect is the config's paths, and ripple does not follow it at all. A paths = ["dir"] entry makes cargo load every package at or below dir and also every path dependency of each of those packages, transitively, in every dependency table and wherever the path points (built: a registry dependency becomes the package a nested path names, a path dependency is replaced by a package outside dir that a package below it reaches, through a [dev-dependencies] and a second hop too), and a dependency of the name of any package so loaded is that package, whatever its source. Following that reach was missed in part three reviews running, so ripple does not try: any paths entry in any cargo config of the analysed directory makes every dependency of every package unresolved, a path dependency too, whatever the entry holds (a package of another name, no package, a directory outside the analysed directory) and wherever the config sits among the directories the walk of the repo reads: a config inside a .git, node_modules or __pycache__ directory, or a target beside a Cargo.toml, is never read, so an entry there refuses nothing, though cargo run from inside such a directory would apply it (the assumption at the walk of the configs, below). An empty paths = [] names no directory and is no entry (built: cargo overrides nothing for it). A paths that is no list of strings is a form ripple cannot read, and refuses the same way as an entry. Where ripple sees a redirect and cannot read it, every dependency is unresolved, a path dependency too: an include key in any form in a cargo config (cargo applies the [patch] and the paths of the included file, built; ripple does not read it); a cargo config that cannot be read (for a registry or git dependency, only as rule (2) says). A manifest that governs a package and cannot be read (its own, one above it inside the analysed directory, or the root its package.workspace names when that root is inside the analysed directory) makes its path dependencies unresolved as well. A [patch] or [replace] of a form ripple does not read makes every registry or git dependency unresolved (cargo rejects those forms, so a path dependency keeps its edge). What cargo is given from outside what ripple reads is not seen, and is assumed to redirect nothing: a --config on the command line, the CARGO_* environment (a config key set there), a cargo config in a directory above the analysed one or in CARGO_HOME, and for a path dependency a manifest above the analysed directory or named by a package.workspace that points outside it (a [patch."file:///..."] or a [replace] in it; for a registry or git dependency that manifest is rule (2)). A manifest in .git, node_modules, a target directory beside a Cargo.toml or __pycache__ is not read for a [patch], which only matters where a build reaches an indexed package by it. Unresolved, with the reason: every method call recv.m() that is not that one case, each with a reason of its own that begins a method call: (impact lists same-named ones under possible_missed_callers): a receiver that is an expression (a call, a field, a literal, self.field), a local whose binding writes no type, a name bound twice in the function (a parameter and a let, a closure parameter, a match arm), a name a statement macro or a pattern macro may bind, an item, an import or a glob that may give that name in a block around the call, a binding under a #[cfg], a generic or impl Trait or trait object receiver (what its bounds give is not followed), a receiver of a type from outside the repo, a method the form of the receiver does not match (an inherent &self method called on a value is found after a trait's by-value method of the same name, so it is not proven), a method no inherent impl defines (a trait method, one reached through a Deref, one a macro made), and every guard above. These are never counted as outside the repo, since a trait or a Deref of the repo may be what runs. Also unresolved: a name two definitions share (cfg twins), a name a pattern or closure binds, a call inside a macro other than the standard ones, a glob from outside the repo in a block, a generic parameter used as a path (T::new()), any path that goes through the use items of a crate of edition 2015 (and every call written in one), a file that several crates share (mod common; in each integration test) that they do not resolve alike, and any name looked up in a scope where a macro may define names (a module or a block that invokes a macro other than the standard ones that define nothing, or an attribute macro): the macro's expansion is not visible, so it can neither be proven absent nor chosen between. The same goes for what a #[cfg] or #[cfg_attr] guards (ripple evaluates no condition, so a definition that may not exist is not chosen over what would stand in its place), and for an item under an attribute that is not a built-in one (#[tracing::instrument], #[pm::attr], any attribute macro, bar the three below): calls inside it and the name it declares are unresolved, though a name beside a derive that no use brings in is that derive's helper (#[serde(..)]) and rewrites nothing. A derive can still emit items beside the type, so a derive ripple does not know (#[derive(Arbitrary)]; seven of the crates.io derives are the exception, below), or a standard derive's name (Debug, Clone, ...) that something other than the standard library could supply (a use of another path such as use derive_more::Debug; in the derive's own module or in a block around it, since rustc reads the bare name in the scope of the item and a use of another module, another function body or a sibling block is not seen there; a #[macro_use] extern crate, a macro of the repo, a #[prelude_import] or the #![feature(prelude_import)] of the crate root, or anything that may make the crate's std or core another crate (which makes its prelude another crate's: a dependency of that key in any table, dev_dependencies and build_dependencies spelled with an underscore and [target] tables included, or a dependency or library whose library is called so, also one a [patch] or [replace] anywhere in the repo may supply (Rule P); a path dependency outside the repo whose Cargo.toml (the one file of it that ripple reads, and fingerprints) names its library std or core, or cannot be read; a [replace]; a .cargo/config of the repo that sets a [patch], paths, include, [unstable], a compiler or wrapper, an [env] entry that names one, or rustflags other than codegen, lints and --cfg; not an [alias], [source] (cargo vendor's), [registries], registry or a [profile] without rustflags, which cannot make std another crate), anywhere in the crate), makes its scope one where a macro may have generated names, so a name found only through a glob import or the prelude is unresolved there. A use of the standard library's own derive (use std::fmt::Debug;) is not such a supply when ripple proves it: std or core is the real crate there (not a module, alias, dependency or block item of that name) and the path is one the library exports the derive under, unrenamed. #[test], #[bench], #[derive] and #[global_allocator] are the standard library's attribute macros, not the compiler's, so a use that gives one of those names in the item's module or in a block around it, or a #[macro_use] extern crate, makes the attribute another macro, and ripple reads it as one (a glob import cannot: rustc rejects it as ambiguous with the prelude's macro). #[rustfmt::skip], #[clippy::..] and #[diagnostic::..] are tool attributes, which a mod, a use, an extern crate alias or a dependency key of that name makes another macro: they are read as inert only when nothing of that name is declared, imported, aliased or depended on anywhere in the crate. A mod written inside a block shadows the items of its name around it and its contents are not read, so a path that starts at it, from inside that block, is unresolved. What such a mod holds still acts outside it: it taints the impls of its crate like any item ripple does not read, and a #[macro_use] one makes every macro name used in its block possibly the repo's. Type::f() and <T as Trait>::f() also need the impls ripple read to be all there are: a macro invoked anywhere in a crate that can name the type (an item, an impl or trait body, a block), an attribute macro, a derive that is not a standard one, or an impl header that names a path ripple could not resolve, may add an impl, so the call is unresolved with the macro or the impl named, except an inherent function (rustc accepts one impl of a name for a type) and the one impl of a trait with no parameters that a path names. An inherent function is the target only when its impl is for every instantiation of the type or for the one the call writes, it is visible at the call and it is a function. Calls that happen with no call site (Drop, Display through format!, ? through From, operators) are not edges, so a trait impl's method can show no callers. check for Rust runs cargo test (ripple/rs_check.py). Stable cargo has no JSON test output (libtest's --format json is refused on a stable compiler), so the verdict is read from the two things that are stable and structured: --message-format json (a compiler-artifact for each test binary built, compiler-message for each compiler error, build-finished) and libtest's own output, which cargo's Running and Doc-tests lines divide into one section per binary (running N tests, a test NAME ... ok|FAILED|ignored line each, a closing test result: line). A section can hold more than one such run: on edition 2024 rustdoc merges the doc tests it can and runs the others (compile_fail, standalone_crate, an edition2018-style override, an ignore snippet that is not Rust syntax) as a second run under the same Doc-tests line (measured on cargo 1.99, each case captured; edition 2021 prints one run whatever the doc tests are, and on 2024 no_run, should_panic and crate attributes are merged), and a test binary can print a run of its own. Each run is judged by itself, a run with no result line is a problem whichever it is, and the section counts as the sum of its runs. The counts of a result line are checked against its own lines, every binary the JSON says was built must have a section with a result, and cargo's exit status can only take a pass away. Each section was captured from cargo 1.99 (tests/fixtures/rs_check/, with the crate that made it and the exact command); no older cargo was run. cargo must be on PATH (otherwise a refusal that names --test-command).

With no arguments it runs cargo test --workspace in each top-level cargo workspace (a workspace inside another's directory that is not a member of it, an excluded fixture, is named in notes and run only when a path names it; a Cargo.toml cargo cannot read inside a workspace is named too). The arguments:

  • a directory, a .rs file or file.rs::module::test_name (tests::adds as written in the file). The path is read from the sources only to find the crate and the module path (util, net::tests) libtest names its tests by. What is IN that module is never read from the sources, because a test a macro or an attribute macro writes (case!(..), #[rstest], #[test_case]) is no #[test] function in any file: the test binary is asked (cargo test <target> -- --list, stable; it builds the binary once, the run after it finds it built), and the run is exactly the listed tests under that module path, -- --exact, judged against that list. A directory is the modules whose files are below it; a package directory, or a directory that holds whole packages, is those packages whole (doc tests included); a crate root file (src/lib.rs, src/main.rs), a directory that holds one and an example's file are that whole target, and a note says so; so is the root of an integration test (a file of tests/), with no note. A file is the tests of its module and its submodules (a note names the submodules in other files). A path whose module path cannot be taken as certain (#[path], a file the crate declares twice, include!, a macro that may declare a module, modules ripple could not read) is the whole target, and a note says why. A harness = false target has no list, so the whole target runs, with a note;

  • the id impact lists for a test function: a Rust repo has no collected tests, so impact's tests is empty and a test function is listed among the callers as src/lib:tests::adds (file path without .rs, mod.rs folded into its directory) under its file. check takes that id and the file.rs::tests::adds form (r#match as written). A name the list does not have is "no test named X exists in TARGET (its test binary lists N tests)", a problem, and nothing is run for it; a function written with no attribute at all is refused before anything runs, since no attribute means no test.

Everything is one cargo test per package and target (-p PACKAGE with --lib, --bin NAME, --test NAME or --example NAME), run from the workspace root, because a filter is shared by every binary of a run, a name is not unique across packages and targets, and cargo's default is a substring match (adds would run adds_zero too). A file that two test targets include is a run per target. Afterwards the tests that ran must be the tests asked for: each listed name needs its own result line in the target, a test that ran without being asked for is a problem, an ignored one asked for by name is a problem (one below a file or directory is a note unless every one of them is ignored), and the result line's filtered out has to be what the list leaves over. Refused before cargo runs: an option, an @file, a path outside the repo (links resolved), a function with no attribute, a module the file does not have (only where the source is certain: a file with a macro called among its items, an attribute that is not an inert one such as #[cfg] or #[test], or an include! may have modules ripple cannot see, so the test binary's list decides and a name it lacks is "no test named X exists"), a bench, a target with test = false (an example is run all the same: cargo calls it test = false by default), one whose required-features are off, a name for a harness = false target, a directory with no source of a target, and a directory whose Cargo.toml cargo cannot read (with what cargo said). cargo metadata --no-deps (read-only) is the one process that may run before the last of these.

What is never reported as passed (each has a capture): a build failure (including a test target that does not build, a build script that fails and a manifest cargo cannot read), running 0 tests or a filter that matches nothing, an ignored test that was asked for, a run in which nothing ran or only ignored tests ran, an integration test target with no test in it, a doctest failure, a test binary that exits early (std::process::exit(0) in a test exits 0 and its result line never prints), aborts or is killed, a harness = false target whose own harness failed, ripple's timeout, a binary the JSON says was built but that never ran, and a result line whose counts disagree with its tests, a test line ripple cannot read (libtest 1.99 writes test NAME[ - should panic | - compile | - compile fail] ... ok|FAILED|ignored[, REASON], and a line outside that grammar is a problem naming it), a binary that exits 0 before libtest starts (no libtest output, no result), and a listing that is empty or does not add up. An integration test target (a file of tests/) with no test is a problem, unless another target of the package reads its file as a module (mod util;, a shared helper): then it is a note. A harness = false target has no libtest output and is judged on its exit status alone, with a note. The result has the usual keys plus problems, counts and notes; failures read FAILED src/lib.rs::tests::bad: panicked at src/lib.rs:6:21: message, an id check takes back, and a failed doctest FAILED doctest src/lib.rs - add (line 3). What the environment can change is either overridden or named in notes: --config term.quiet=false term.verbose=false and --color never outrank CARGO_TERM_QUIET, CARGO_TERM_VERBOSE and CARGO_TERM_COLOR (measured: the first two remove or rewrite the Running lines); RUSTFLAGS, CARGO_BUILD_TARGET, a compiler wrapper, a target runner, a rust-toolchain file and a repo's .cargo/config that sets flags, a target, a runner or [env] are named; RUST_TEST_NOCAPTURE glues a test's output to libtest's lines (measured), which the count check reports as a problem and the notes explain. A user-level ~/.cargo/config.toml is not read. Not done: cargo nextest, benches, --features (a test behind an off feature is refused when named, and listed in notes in a whole run), and a doc test as a named id. --test-command still means exactly that command, read the generic way.

What check for Rust cannot promise: stable cargo gives no structured test results, so the output is libtest's text, cross-checked but not authenticated. A test binary that deliberately imitates libtest's output (writes test x ... ok and a test result: ok. line to stdout itself) and then exits with status 0 can still be read as passed wherever the run is the whole of a binary, which has no list to compare with: no arguments, a package, a test target, and every request that maps to a whole target (an integration test file such as tests/it.rs, a crate root file such as src/lib.rs, a directory that holds one, an example's file, and each fallback to the whole target: #[path], a file declared twice, include!, a macro that may declare a module, modules ripple could not read, harness = false). The forgery is caught only where the run is narrower than the binary's list: an id, or a file or directory below a crate root that ripple maps to a module path. There the result line's counts must agree with what the binary listed before it ran (filtered out is what the list leaves over), which a binary that only imitates libtest's output does not know. A test author who wants a green can also delete the assertion.

Attribute macros ripple trusts. Three attribute macros are the exception to the rule above: #[tokio::main], #[tokio::test] and #[serial_test::serial] (also written #[serial] after use serial_test::serial;). The published expansions wrap the body of the function in an async block or a closure of the same function and add no name the body can see and no item beside it. So on a free function (not an impl or trait method, not a module) ripple reads the calls in the body as it reads any function's, but only where the repo proves that the macro is the one on crates.io. serial is trusted only on a function that is not async and has no inner_attrs argument, and any other attribute macro on the same item cancels the trust. The name the function declares stays unresolved, since old versions of both macro crates drop its pub. A site the repo does not prove is read as under any other attribute macro, with the same reason.

Ripple trusts a site only when all of these hold:

  • Every dependency section of the package (its own, dev-dependencies, build-dependencies and each [target.*]) names the crate plainly: a version, with at most features, default-features or optional, and no path, git, registry, package or other key. workspace = true counts when the workspace's entry is plain. The package depends on the crate at all.

  • No [replace] entry and no [patch.*] entry, of any crate and written in any way, is in the package's manifest, in a manifest above it or in its workspace root. A patch of quote, syn or proc-macro2 reaches the macro crates too.

  • Every Cargo.toml at or above the package can be read. A package.workspace names a manifest that ripple has read and that has a [workspace]. The workspace does not exclude the package (an exclude entry that is its directory, one above it or a glob), since cargo then builds it as a workspace of its own, with its own Cargo.lock.

  • Every cargo config file ripple finds can be read and sets only keys from an allowlist, because cargo reads the ones above the directory it is run in, which may be any directory of the repo. The walk looks for a file called config or config.toml in a directory called .cargo, with the names matched in any case (cargo on a case-insensitive file system reads .Cargo/Config.toml). It follows a link to a directory that stays inside the repo (each directory once, so a loop ends) and reads a .cargo that is a link wherever it points. It does not enter a link that leaves the repo. It skips .git, node_modules and a target directory with a Cargo.toml beside it (build output, where the source walk reads no file either); a target directory with none beside it is walked, because a package may sit in it. The allowed keys are: build (jobs, target, target-dir, build-dir, artifact-dir, incremental, dep-info-basedir, pipelining, warnings, rustflags), target.<triple or cfg> (rustflags, linker, runner, ar), resolver (incompatible-rust-versions, feature-unification), future-incompat-report.frequency, doc.browser, [env] entries that do not name a compiler, a wrapper, flags or a search path (names that start with RUSTC, RUSTFLAGS, RUSTDOC, RUSTUP, CARGO, PATH, LD_ or DYLD_), and the term, cache, net (retry, git-fetch-with-cli, offline), http (not proxy or cainfo) and install.root settings. Rustflags may hold only -C codegen options, lint levels and --cfg. Anything else refuses every package of the repo, a key ripple does not know included: paths, [source], [patch], include, [registries], [registry], [alias], [profile], build.rustc*, resolver.lockfile-path, a [target.<triple>.<links>] build-script override, --extern, -L.

  • A Cargo.lock in the workspace root, when there is one, can be read and takes the crate and its macro crate (tokio-macros, serial_test_derive) from crates.io.

  • No package of the repo is named tokio, tokio-macros, serial_test or serial_test_derive.

  • The crate that uses the attribute is of edition 2018 or later.

  • The attribute as written reaches the crate. tokio is not a local module, an alias, a glob from outside the repo or a mod written in a block. serial is brought in by exactly one use serial_test::serial; that is not under a #[cfg], and no macro of the repo is called serial.

  • Nothing can make a #[test], #[bench], #[derive] or #[global_allocator] on the item another macro: no use that gives one of those names is in the item's module or a block around it, no #[macro_use] extern crate is in the crate and no macro of the repo has the name.

  • Nothing can make a #[rustfmt::..], #[clippy::..] or #[diagnostic::..] beside the attribute another macro: no mod, use, extern crate or dependency key of that name exists anywhere in the crate. A path that starts at any other built-in name (#[doc::x]) or a bare tool name is a macro whenever the program builds, so it is read as one.

What ripple cannot prove, and so assumes:

  • What the published macros expand to. It was read for every version published when this was written (tokio-macros 0.2 to 2.7, serial_test_derive 0.1 to 4.0) and is assumed for later ones: nothing checks the version, not even the one in a Cargo.lock.

  • What lives outside the repo: RUSTFLAGS, RUSTC_WRAPPER, --extern, a cargo config file above the repo (including the one in CARGO_HOME), a workspace manifest above the repo, and a registry mirror that serves other code under the same names.

  • A fetched dependency (from a registry or a git repository) does not name its library std, core or alloc. Ripple does not fetch or read one, so it cannot know; marking every package that has one would leave almost no prelude name resolved. A package that has one whose library is named so builds, and ripple gives the standard library's verdicts for the names that library replaces (a constructor for Some(1) where the library's Some is a function: _assumed/fetched_lib_std, built with cargo, in bench/fixtures/rust-probes/crates; tests/test_rs_fetched_dependency_assumption.py pins the wrong verdicts as the price of the assumption). The assumption stops at a dependency keyed std or core, a package = "rustc-std-workspace-*", and a path dependency, whose Cargo.toml is read.

  • Build artifacts committed in the repo that a config points cargo at: build.target-dir and build.build-dir (and -C incremental=) name a directory, and one that holds a pre-built, forged copy of a macro crate may be taken by cargo as up to date. Ripple does not look in it.

Derives ripple trusts. Seven derives of three crates.io crates are the exception to the rule that a derive ripple does not know may emit items beside the type: serde's Serialize and Deserialize (reached through serde only), clap's Parser, Args, Subcommand and ValueEnum, and thiserror's Error. Every published version of the three macro crates was read (serde_derive 0.8 to 1.0.229, clap_derive 3.0.0-beta.1 to 4.6.7, thiserror-impl 1.0.0 to 2.0.21), and each adds impls of its own crate's traits for the deriving type and nothing else, with three exceptions that ripple narrows: serde_derive up to 1.0.162 may write a const named _IMPL_SERIALIZE_FOR_<Type> (or _IMPL_DESERIALIZE_FOR_<Type>) beside the type, so ripple reads that name as one a macro made, whatever version builds; #[serde(remote = "..")] adds an inherent serialize or deserialize, which the derive functions of a type already cover (a call of one is both the derive's and a repo trait's, unresolved); and #[serde(crate = "..")], also under cfg_attr, makes the impls those of another path, which may be a module of the repo, so a type that has one is not trusted. Where a derive is trusted its scope is not one where a macro may have made names, and its impls are not a reason the impls ripple read may be incomplete. Everything else, structopt included, is read as before.

Ripple trusts a derive only when everything the attribute macros need (the list above, with serde, clap or thiserror for the crate and serde_derive, clap_derive or thiserror-impl for its macro crate, and no package of the repo named like either, nor with a [lib] name like either, since rustc links the library of a package of the repo over a proc-macro crate of its name; a repo with a manifest or a library name ripple cannot read refuses too) holds, and also:

  • The bare name comes from exactly one use serde::Name;, use clap::Name; or use thiserror::Name; (a leading :: allowed) in the nearest scope that imports it, a block before the module and never a parent module: not under a #[cfg], not renamed, not beside another import of the name, with the crate there being the dependency. A path written in the derive (serde::Serialize, ::clap::Parser) must resolve the same way. A glob or a macro that may make names met before the import, a macro of the repo of that name, a #[macro_use] extern crate and edition 2015 refuse it. The edition is the crate's own: a target table's edition ([lib] edition = "2015", [[bin]], [[test]], [[example]], [[bench]]) decides before the package's, and one that is not a known edition reads as 2015. The same edition decides every other rule that reads it, so it also keeps a standard derive from being proved by a use core::fmt::Debug that a 2015 target reads as its own module.

  • For use serde::Name; and use clap::Name;, no glob import in the importing scope or in a block around it up to the module. Their derive feature is not asked for: with it off the import gives the trait alone and the name in the macro namespace goes on to a glob (built with a local proc-macro crate), and a manifest that turns it on says nothing of another target. thiserror::Name carries the derive always.

  • Nothing is trusted through a macro crate (serde_derive::Serialize, clap_derive::Parser, thiserror_impl::Error), whatever the manifests say. A library of the build graph called serde_derive (a path or git dependency, a registry package that sets [lib] name, a package ripple never reads: its lib.rs in another directory, a hidden directory, a directory above the one analysed) is linked where the proc-macro crate was meant, rustc preferring an rlib of the name, and neither a manifest nor a Cargo.lock records library names, so no repo can prove it away. serde::Serialize is safe because serde's re-export resolves inside serde's own build, against serde's own dependency. Built and run (offline, with the real crates and with local ones, bench/fixtures/rust-probes/crates/_derive_trust_lib): a second rlib called serde, clap or thiserror beside the real one is E0464; a proc-macro library of the name loses to the real rlib; either reached under another dependency key, as a dependency of a dependency or as a dev-dependency is no --extern of that name; and a library called serde_derive, clap_derive or thiserror_impl beside the real macro crate or without it leaves the facade's derive the real one. The refusal for a library of the repo called like the crate or its macro crate stays as a second guard.

  • serde: the serde dependency is plain, since the expansion says extern crate serde.

  • clap: clap is the dependency where the derive is written, not a module, an alias or an extern crate of that name, since the impls are written impl clap::Parser for .. and a local mod clap captures that path (built with a local proc-macro crate).

  • thiserror: std is the standard library where the derive is written, by the lookup and by a test that no dependency or library called std or core may make it another crate, since the impls are written impl std::fmt::Display for .. up to thiserror 1.0.69. That test is a second guard: the derive attribute of the item is refused first, by the test of the next entry (which is wider: it covers a prelude the crate sets too), so the standard derives' replacement and this check are not the same test, and the derive tests stay green with this one removed.

  • None of the three where the crate's std or core may be another crate's (the test above): the derive attribute is a macro of the standard prelude, which that crate may replace, so a derive written under it is no proof of anything.

  • No other derive that is not a standard one and no attribute macro is on the same type, and each bare attribute beside the derive is one of its helpers in every version the build can use. A Cargo.lock that lists the macro crate says which versions those are, so a name counts when each listed version declares it (clap 4's command, arg and group, group on Parser from clap 4.0.7, thiserror 1.0.2's from and backtrace); with no lock, only the names every version declares (serde, clap, error, source). A lock counts only while it agrees with the manifests: each requirement written for the crate the derive comes through (serde and serde_derive; clap; thiserror), in every package the lock covers (the lock's workspace and the transitive closure of its path dependencies, members or not: cargo resolves one lock over all of them, so a path dependency that asks serde = "=1.0.228" downgrades what a lock at 1.0.229 says) and every dependency table, with workspace = true taken from the root, must be met by a version the lock lists, by cargo's own rules (caret with the 0.x rules, =, ~, comparison lists, wildcards, pre-releases). One that is not met, or that ripple cannot read, makes the lock no lock for that crate, which cargo re-resolves on the next build. A path dependency ripple cannot read as a package (above the analysed directory, a directory with no manifest, a manifest that does not parse or that is no package, a path that is no string) is a requirement it cannot see: it counts as unreadable for every crate of the list, so the lock is no lock for the helpers and serde is refused with a lock and without. So is a workspace member ripple cannot read: one of the members of the [workspace] above the analysed directory, a members that is no list, or a ** glob (other globs are expanded, hidden directories included). A manifest inside the analysed directory that the source walk skipped (a package whose lib.rs is elsewhere, a hidden directory, a member or path dependency with no source file in its directory) is read for this and is part of the cache's fingerprint; nothing above the analysed directory is read. A declared helper beats an attribute macro of that name that is imported (built with a local proc-macro crate), so a use of the name elsewhere in the crate does not cancel it, which the old rule did. A bare name that is not certain is read as it always was, and the derive beside it is not trusted.

A site the repo does not prove is read as the same derive was read before: the same marks and the same reasons.

The serde version rule: when the Cargo.lock lists a serde_derive that runs a precompiled binary, which no source ripple has read describes (1.0.172-alpha.0 and 1.0.172 to 1.0.183, 13 versions), the serde derives are not trusted, and a lock that lists several versions of serde_derive is refused if any is one of them. The clap and thiserror derives are not affected. With no Cargo.lock that agrees with the manifests (none, or one a requirement no longer meets), cargo builds the newest published version that satisfies the requirements, which ripple computes from the index's list of versions (serde_derive alone: the newest that meets its requirements; with serde: the version its newest satisfying release pins, =<its own version> from serde 1.0.103 to 1.0.219, and both when serde_derive is also written, since the pin of the older ones belongs to the derive feature) and refuses when it is one of the 13, or when a requirement cannot be read or nothing published meets it: serde = "=1.0.180" and serde = "<1.0.184" are refused, serde = "1" is trusted. A version published after the list was made is newer than every one of the 13.

What ripple cannot prove, and so assumes, for the derives: what the published macros expand to. It was read for every version published when this was written, except the binaries of those 13 serde_derive versions (their source says const _ and nothing else; the binary was not read), and is assumed for later ones: the version of the crate is not checked, and a lock is read only for the 13 above and for which helper attributes the listed versions declare. That cargo picks the newest version that satisfies, and that nothing outside the manifests lowers it, is assumed too. What cannot be seen: the requirements of a registry or git dependency, which are not in the repo (a crate of crates.io that itself asks serde = "=1.0.180" is not read when there is no lock; with a lock that agrees with the manifests the lock lists what resolved, and one the dependency made stale is not noticed), and the manifests of path dependencies above the analysed directory, which count as an unreadable requirement instead. The same outside-the-repo limits as for the attribute macros apply.

Java

Experimental. Java is the newest front end and the least proven. Its answers agree with javac on every call site of the five source trees it was checked on (see "Checked against the compiler" below), but its resolver went through two rounds of fixes for wrong edges in legal Java those trees did not contain, and the JDK table it reads is new. Read its unresolved reasons, and report an edge that javac would not make.

check for Java runs Maven (ripple/java_check.py) and reads the verdict from surefire's XML reports (target/surefire-reports/TEST-*.xml: a testcase per test, with its failure, error or skipped child), cross-checked against Maven's exit status and against what was asked for, never from the exit code alone or the log text. mvnw in the repo is preferred to mvn on PATH (it is the Maven version the repo pins, and a Maven that is too old or too new fails a build for no fault of its tests; it may download a distribution on first use, which is the repo's own build, and a mvnw that is a link to a file outside the repo is refused, never run). It needs a pom.xml at the root, and a root with both a pom.xml and a Gradle file, or Gradle alone, is refused with the command to pass instead. With no arguments it runs mvn -B --fail-at-end test (every module of the reactor; --fail-at-end so an independent module still runs after a failure). The arguments:

  • the id impact lists for a JUnit test method, com.acme.shop.CartTest.addsItems() (...CartTest.Receipts.receiptHasTotal() for a nested class, parameter types as impact writes them), a test .java file (the test classes it declares), or a directory (a module, or a directory of modules, as a whole, or the test classes under a test source directory); file.java::Class[.Nested][.method[(types)]] is the same thing with the file named. An id that names two files (the same class in two modules) is refused, never guessed.

A class is -Dtest=com.acme.shop.CartTest (its @Nested classes run with it) and a method -Dtest=...CartTest#addsItems, in the module that holds it: -pl <module> -am in a build of several modules, always with -am. ripple does not read the poms to guess which modules a module needs (a dependency in a profile, a parent or a plugin would be missed, and -pl alone then runs against an installed copy of the sibling from the local repository, which can be an old one): Maven builds what the module needs from the tree. A module asked for whole therefore also runs the tests of what it needs, and the verdict says so; a class or method runs none of theirs unless a class of the same name is there (named in notes). Whole classes of a module share a run; a method never shares one with another class, because several # filters in one -Dtest are a cross product in some surefire versions. The -Dtest value is made of names read from the source file, never from the argument. Every argument that is an option, an @file, a path outside the repo, a control character, or not a test is refused before a process starts, and nothing a caller writes becomes a -D property or a build flag.

Merging requests merges the runs, never the requirements: check([".", "OffTest.java"]) is one Maven run, and OffTest, asked for by name, is still held to its own obligation (it ran, it was not skipped, it passed). The same goes for a file beside a method of it, a class beside its nested class, a module beside a class of it, and the same id twice or in two spellings.

Two check calls in one repository are serialized (an advisory lock file named by the repo's path in the temporary directory, never in the repo): two Maven runs writing one target/ cannot be told apart by the snapshot below, and measured, they did read each other's reports. A second call waits up to its time limit and then refuses; a build started by anything else (an IDE) is not covered, and a report it writes during a check can be read as the check's own.

Which reports are this run's: a snapshot of every report file is taken before the run, and a report counts only if it is new or changed since (mtime, size, inode) and was written no earlier than the run began. A report an earlier run left, saying PASSED, is never read; it is counted in a note. What is never reported as passed (each has a run captured from real Maven 3.9.9 and surefire 3.5.2 in tests/fixtures/java_check/, with the project and the command): a selector that matches nothing (Maven exits 0 with Tests run: 0 and no report), a compile failure in main or test code, a module that never reached its tests (the reactor says SKIPPED, and a module with test classes and no report is named even when it does not), a JVM that crashed or called System.exit, a surefire fork timeout (the report says the test passed and Maven exits 1) and ripple's own time limit, a requested test that was skipped or disabled, a build that skips its tests (skipTests, maven.test.skip), a test class surefire's name patterns do not pick up (CartChecks: the run is green without it), and a failure the build ignores (testFailureIgnore exits 0).

Which classes should have run (a whole-build or whole-module run) is predicted from the test sources (every class with a JUnit method of its own) and from the classes Maven compiled (target/test-classes: javac has already resolved a test inherited from an abstract base or an interface default method, a test method carrying a composed annotation such as @FastTest that is itself annotated @Test, a @RunWith, and whatever test source root the build has, from a parent pom or from build-helper). The class files are read by ripple (no JDK needed), and the rule has a middle ground that is stated, not left to a guess:

  • A class ripple knows holds tests, and that has no result, is a problem. It knows when, in the part of the class's supertype closure it can read (its superclasses and superinterfaces, transitively, cycles cut, as far as they are classes of the repo), it finds one of the known set: on a method JUnit 4 @Test and @Theory, JUnit Jupiter @Test, @RepeatedTest, @TestFactory, @TestTemplate and @ParameterizedTest, TestNG @Test, and any annotation meta-annotated with the JUnit Platform's @Testable (jqwik's @Property, a project's own) where that annotation's class file is in the repo (composed to any depth, so @FastTest meta-annotated @Test counts); on the class JUnit 4 @RunWith (a Suite, Enclosed, any runner) or TestNG's class-level @Test; JUnit 3 as a superclass junit.framework.TestCase. What is proven in the part ripple read decides, even when the closure leaves the repo further up. Its name does not matter: CartChecks, which surefire's patterns (Test*, *Test, *Tests, *TestCase) never pick up, and a class a build excludes, are problems.

  • A class ripple cannot decide is a note, never a problem: an annotation it does not know on a void method (JMH's @Setup, Spring's @PostConstruct, Guava's @Subscribe: helper code is full of them), or a supertype outside the repo (a library class, an interface of a library), or a name defined in several modules ripple cannot rank, with nothing known to hold tests in the part it read. The note names the class and why ("cannot tell whether X holds tests (X.setup carries org/openjdk/jmh/annotations/Setup), and no test of it ran"); five are named and the rest counted. A class surefire's default patterns name (when no pom sets includes or excludes) is not even that: surefire looked at it and found nothing. It is a problem when the request names it and no test of it ran.

  • The cost, stated: a test class of a framework ripple does not know (a library's own base class, an annotation whose class is in a jar, such as jqwik's @Property on its own) whose name misses surefire's patterns is not run by mvn test either, and ripple reports it in a note, not as a failure. A repo that never runs such a class passes. The alternative, a problem for every class that cannot be decided, made every whole-build check of commons-lang read not passed (two JMH benchmark classes in its test tree) and would have made any repo with helpers read the same.

A class is looked up the way its own module's build would resolve it, never by name across the whole repo: in the module's target/test-classes, then its target/classes, then the modules of this build it depends on (read from <dependencies>, in profiles and parents too; their target/classes, and their target/test-classes only through a test-jar dependency). A name found in two of those that ripple cannot rank is ambiguous, and the class is undecided. A compiled class counts only if the module's current source roots (src/main/java, src/test/java, or what the poms set, build-helper included) hold a source for it: the same package path and the outer class's name (Outer$Inner and Outer$1 follow Outer), or the file the class file names as its source. A class with none is left over from an earlier build (a module this run did not build, a deleted source) or generated, and is evidence of nothing; it is named in a note ("compiled class with no hand-written source"), whatever its package is called. Where the source roots cannot be read (a property), or a class was not compiled from a .java file (Kotlin, Groovy), every class counts. Class files, sources and reports are read as regular files inside the repo only (a link, a FIFO or a file over the size cap is refused, with a read that never blocks), and a class file that cannot be read is a note naming it.

A module with test sources (or a test root held in a property) and no current compiled test classes is "cannot predict"; results from a module whose prediction is empty are "predicted no test class but tests ran". Left out, and named in notes: failsafe's classes (IT*, *IT, *ITCase, run in verify). Not decided from bytecode: a class that gets its tests from an external library base, the interface of a library, a Cucumber-style runner (its results come under feature names: it has a result through its report file, when that holds tests), a class that exists only in a target directory other than Maven's default. Results are matched by the class a testcase names, or by the class the report file is of (a JUnit AllTests suite reports its tests under other names). MAVEN_OPTS, MAVEN_ARGS, .mvn/maven.config or .mvn/jvm.config that set -DskipTests, -Dtest, -Dgroups and the like make the run not passed, named; a pom that configures skipTests, groups, excludedGroups or testFailureIgnore is named in notes (an excludes the build sets shows as a test class with no result). Maven selects by method name, so an overloaded test method runs every overload: the verdict says so, names the overload that failed, and fails when only other overloads ran. A parameterized test, a @RepeatedTest and a @TestFactory report as name()[1], name()[2]: the method name is what is matched, and the verdict says how many invocations ran. The result has the usual keys plus problems, counts and notes; failures read FAILED file.java::Class.method: message. What it does not read: Gradle, TestNG, a build whose reports are written outside the repo (nothing is found, so it is not passed), failsafe integration tests (verify, not test: named in notes, never expected), and Kotlin tests. --test-command still means exactly that command. Java's profile is untouched (its fields are hashed into the cache key).

Java is read by tree-sitter too, as its own optional extra (tree-sitter and tree-sitter-java):

uv tool install "ripple-code[java] @ git+https://github.com/xtelos/ripple"   # or pip install 'ripple-code[java]'

--lang java or auto (which looks for .java files, skipping package-info.java, module-info.java and the output directories target/ beside a pom.xml, build/ beside a build.gradle and an IDE's out/ and bin/, which ripple index lists with the other skipped directories) reads a repo as Java. A Java-only repo without the extra is refused with the install command, and a repo with Python and Java answers for Python and says Java was skipped.

Symbols are dotted, like Python's, and a method carries the simple names of its parameter types as written, so overloads have their own ids: com.acme.shop.Cart (a member class is Cart.Line), com.acme.shop.Cart.add(Item), Cart.<init>(List) for a constructor, Log.info(String,Object...) for varargs, Ledger.runAll(List)$1 for the first anonymous class in a method, Op.ADD for an enum constant with a body. A file is its path with the extension (src/main/java/com/acme/shop/Cart.java, found by any tail of that path, shop/Cart.java too), so Cart is the class. Any of these finds it: the full id, Cart.add(Item), Cart.add when only one method has that name, or the bare name. A name that two overloads share is not answered for one of them: the overloads are listed as candidates. A class's callers include the callers of each of its constructors.

What is an edge. The Java resolver (ripple/java_resolver.py) does not use the shared one, because Java picks a method by its name and its parameter types from the whole class hierarchy. A call is proven from declared types, imports, the enclosing class that has the name (the "comb rule"), and the arguments' types: with several overloads of the right number of arguments it picks one only when every argument's type is known and equals that overload's parameter types, and otherwise says "N overloads of m take n arguments". Only the methods a type has as members and the caller may call are candidates (a private method is not inherited, a package-private one is not seen from another package, a protected one needs a subclass body), and a parameter written with type arguments takes only an argument written with the same ones. Two imports of one method name, a name that a local class or a pattern variable may or may not hide, and a type name that a supertype from outside the repo may have as a member type are not decided either. A call on an interface or a class with subtypes also gets an override edge to each method in a repo subtype that overrides it (anonymous classes and enum constant bodies included; a type variable counts as what the subtype's implements Visitor<Item> makes of it, and a method a subtype inherits from a superclass counts too), but not super.m(), Type.m() or new T().m(). Generics are erased, so a value typed by a type variable, an array element, the result of a call into the JDK or an untyped lambda parameter is unresolved.

ripple does not know the JDK's or a library's members, so it does not guess them. A method of a class that extends or implements a type from outside the repo (class Ledger extends Writer) cannot be proven to be the one a call means, because that type may declare another method of the name: the call is unresolved, with that reason. The exceptions are the three types the language itself puts under every class, enum and record (Object, Enum, Record), whose members are built in, and the types of the JDK table (ripple/data/java_jdk.txt): 1,812 types of java.base and java.compiler with their supertypes, methods and the numbers of arguments each takes, fields and member types. A name such a type lacks is not its own, and a marker interface like Serializable declares nothing. The table is generated from the class files of every released JDK from 8 through 27 (twenty of them, each named with its exact version in the file's header), because the repo may be built with any of them, and each fact is merged in the direction in which it is safe: a supertype, method, field or member type is in the table when any of those JDKs has it, so only a name the table lacks proves anything. A member that only some JDKs have (Thread.destroy(), ArrayList.getFirst(), Process.close()) blocks an edge and never proves one: in class Q extends Thread nested in a class that declares destroy(), an unqualified destroy() is unresolved. The table stops at JDK 27. A repo built with a later JDK may meet a member, supertype, field or member type that the table lacks, and ripple cannot tell that from the repo. Its Java answers rest on the assumption that no JDK after 27 adds one (JDK 26, for example, gave Process a close() and made it an AutoCloseable). The table is regenerated with bench/java_jdk/generate.py when a JDK is released. A table file that is cut short is refused whole: the header holds the number of rows, and when the file holds fewer, every type from outside the repo is unknown and ripple index notes that the table was not read. Any other type from outside the repo is unknown, and an unknown type may declare, inherit and be anything. A repo that declares a type in a package of the table (package java.util;) reaches members the table leaves out, so for that repo every type from outside it is unknown. A comment can stand between any two tokens and changes no answer. A call is counted as outside the repo only when it cannot run repo code: a call into the JDK or a library from a type it can name, or a call of a name no repo source declares with that many arguments (unless a Lombok annotation is in the repo). A value typed with an external class or interface, or Object, may be an instance of a repo class (List l = new MyList(); l.add(x) runs MyList.add), so a call of a name such a class declares is unresolved, unless no repo class can be an instance of the JDK class: it is final in every JDK (String), or it is a class with no public or protected constructor in any JDK and so is every non-final table type below it (java.util.Arrays, which is final from JDK 21 only).

Not followed, and never an edge: method references (this::show names a method, it does not call it), reflection, Lombok and annotation-processor output, qualified inner-class creation (outer.new Inner()), check for Gradle (a Gradle repo has no default test command yet: pass --test-command; no Java test is collected, see check for Java), and JDK 25 syntax the grammar does not know (those files are listed with the ones that could not be parsed, and read as far as the parser recovers). A file whose directory does not end in its package path is not indexed and is listed with the reason (a Java file a test compiles as data), and two files that define one fully qualified name (Android product flavours) are indexed as neither: their types have no symbol, calls of them are unresolved, and ripple index warns that the files share a module name.

What an on-demand import does not give. A name that an on-demand import of a JDK package might supply (import java.util.*;, then Timer) is NOT resolved to the JDK's type. It is ?.Name, a type of a package that is not known, and the shipped JDK table is not read for it. A type of the file's own package comes before every on-demand import (JLS 6.4.1), and a package is not closed: a jar on the classpath, or generated code, can put a Timer into the file's package or into a repo package the file imports, and ripple cannot see it. The table's absences ("java.util.Timer has no foo, so foo() is the enclosing class's", "final", "no such constructor") would then be about the wrong type. So such a name supplies nothing: a class that extends it may declare, inherit and be anything, a call on it is external only where no repo type may be an instance of it, and it never picks an overload by its type. A package that no outside source can add to would allow more, and that is a named module, module-info.java, which ripple does not read. What the repo's own sources supply is exact: a repo type an on-demand import brings is the name, and a type of the package, in any file ripple read, comes first.

What this closes. Each of these gave a wrong edge or a wrong "external" before, and is now unresolved with the reason: a single static import of the name (import static p.Shapes.Queue; may import a member type that comes before the on-demand import); a static on-demand import of a repo type that has a member type of the name; import module m; (JDK 23 and later), which the grammar cannot read and which may export repo types; a package that only a file in the wrong directory declares, which is an unknown package and not a repo package; and a .java file of the repo that ripple did not read whole.

Which files. Every .java file below the repo that the walk does not hand over: package-info.java (javac accepts a class there), module-info.java, build output under target/, build/, out/, bin/ (where the build tool that writes it is there), hidden directories and every other directory the walk skips, a file in a directory that is not its package's, a file the parser read in part (a parse error: the structure it recovered is no evidence, so every method the text of such a file declares counts as unseen, the ones the parser saw too), and a file that could not be read. Only .git, node_modules, __pycache__ and site-packages are not looked into, and a directory behind a symlink is not followed (the walk does not follow one either). Ripple reads their text, not their tree. The text is decoded as UTF-8, else ISO-8859-1 (which gives every byte a character, so no byte sequence hides a name), with UTF-16 and UTF-32 decoded by their byte-order mark or, with none, by the NUL bytes between the letters. A scan errs toward more names: a name is any run of characters that is no blank, separator, operator or quote (Java allows $, currency signs, connector punctuation, combining marks and every letter of Unicode, and characters javac ignores in an identifier are dropped); a method name is noted wherever a declaration may stand (a name after a result type, so record(...), yield() and every contextual keyword count, and a name after something the scan does not know counts with no arity); every component of a record is an accessor; every name after class, interface, enum and record is a type. The number of parameters narrows a refusal only when the list is read with certainty (closed, no receiver parameter; a varargs one takes any number from one less than its parameters).

Which verdicts. One question is asked wherever ripple would take a type for a library type, unread_type(qualified name): may an unread file declare a type of that package and name? If so the verdict is unresolved, never external. It is asked on every route that makes a type external: a single-type import, a full name (new q.Maker(), a field, a parameter, a local, a cast, a caught type), an on-demand import, a name of the file's own package, a single or on-demand static import (make()), a superclass (class Sub extends Maker, super.m(), super(...), a method a read subtype inherits from it), a member type, and a full name in a package of the JDK. A test (tests/test_java_unread_types.py) reads every place the resolver builds an external verdict off the module's own syntax tree and fails on one that is not classified, and runs a matrix of every route twice, with the type in an unread file and in a jar. The other conclusion, "no repo code runs here" from the absence of a method name, asks unseen_method(name, arguments) on every route: a call no repo method has the name of, a value of a type from outside the repo that a repo type may be, a method inherited from outside the repo that a subtype may override. An enum, a record and a final class have no subtype in a file ripple did not read, but only where their own file was read whole.

Which files are never opened. Only a regular file inside the repo is opened, and at most 4 MiB of it is read. A named pipe, a device, a socket and a directory called X.java are never opened and declare nothing; neither does a link that leads nowhere (dangling, or around a loop). A link to a file outside the repo is not read and may declare anything, a file that cannot be read and a directory that cannot be listed may declare anything, and a file larger than 4 MiB is not scanned: it may declare any method and any type of the package its first bytes say. Each of these is listed with the files that did not parse, with the reason.

What it costs. Recall only. A repo with a .java file that declares a method of a name ripple would otherwise have proven external has those calls unresolved, whatever type they go through (a name is asked, not a receiver). A copy of the sources that is not byte-identical (a target/checkout that the maven release plugin leaves, a checkout under .claude/worktrees) is a set of unread files that declares what the sources do: on commons-lang with such a copy, 2,950 of 43,235 external calls become unresolved. A byte-identical copy costs nothing. Measured on gson, commons-lang, junit5, okhttp, auto, petclinic and antennapod (a quarter of a million call sites), two sites move from external to unresolved, both in auto, and none in the other six.

What is assumed. The names java.lang supplies keep the reading they had before this: java.lang.Name where every JDK has the type or nothing else is imported on demand, ?.Name otherwise, and a full name java.lang.Name is not asked of the unread files. That reading has the same exposure (a type of the package that no source shows would come first), none of the guards above applies to it, and it is not widened. "Every JDK" means JDK 8 through 27: a build for an older JDK, whose library had a type that JDK 8 added to java.util (Base64), is outside it, as a JDK after 27 is. Code outside the repo is assumed to be what its name says: a type from a jar is a library type, and a file that a build compiles from outside the repo directory (a source path above it, a directory behind a symlink, generated output written elsewhere, an annotation processor's) is not seen. Other JVM languages are not read: a Kotlin, Scala or Groovy source in the repo may declare a type that a .java file imports, and ripple does not know it. A source in an encoding that is neither UTF-8, UTF-16 or UTF-32 nor ASCII-compatible (EBCDIC) is not read as the text it is, and names in a script outside ISO-8859-1 in UTF-16 or UTF-32 with no byte-order mark are not decoded.

Limits. The JDK table covers JDK 8 through 27 (a later JDK is past its horizon, see above) and java.base and java.compiler only: a type from any other JDK module (java.desktop, java.sql) or from a library is unknown, so a call that a supertype of that kind could answer stays unresolved. A name that an on-demand import supplies has no package in ripple's reading, so it is unknown, whatever the table holds. The table is read for a name only through a single-type import, a fully written name, or java.lang. check has no default test command for Gradle, and no Java test is collected: impact lists a test method among the callers.

Checked against the compiler. bench/fixtures/java/probes holds 195 small legal Java programs, each with javac.json: every invoke instruction javac wrote for it (bench/java_probes.py, run by hand with a JDK). Five of them depend on the JDK they are built with and also carry the answer of another javac (javac-8.json, javac-25.json, javac-26.json); ripple is held to every one. (A source file whose first line is // javac-min: 26 is compiled only by a javac of that release or later.) tests/test_java_probes.py needs no JDK and requires every edge ripple makes to be the method javac invoked, every override edge a method the receiver's subtypes really run, and every call it counts outside the repo one that cannot run repo code (ripple may be silent, but it may not be wrong). tests/test_java_comment_injection.py writes every probe and the golden fixture again with comments between the tokens and requires the same graph. bench/java_corpus.py is the same judgement on a real source tree (javac compiles it, javap reads every class, each call site is paired with its invoke instruction) and its bar is zero wrong calls, overrides and externals. It met that bar on gson (3,408 call sites), commons-lang (11,139), the JUnit platform modules (7,047), auto's common (1,319) and the golden fixture, each compiled with JDK 21. That check is weaker in one place: javac names java.lang.Object as the owner of an Object method the receiver's class does not declare (equals, hashCode), so the bytecode does not say which class the receiver is, and those sites (52 in those corpora) are listed apart rather than judged. tests/test_java_javac.py does it for the golden fixture and runs only when javac -version reports 21 or newer.

How it works

The core has no parser dependency: the Python front end reads files with the standard library ast module, and the base install needs only the mcp SDK. The TypeScript front end (ripple/ts_indexer.py) writes the same per-file facts from a tree-sitter parse, so one resolver builds both graphs. The languages are listed once, in precedence order, in ripple/registry.py: a language is a profile (ripple/profile.py) and one entry there naming its front end module, which is imported only when a file of that language is read. The Java front end (ripple/java_indexer.py) declares the types and members, and its own resolver (ripple/java_resolver.py) decides each call and writes the graph, so only the first step below is shared with it.

  1. Collect (ripple/indexer.py): each file is read on its own. For every module, class and function it records what names are bound (defs, imports, assignments and what they suggest about a value's class) and every call site.

  2. Resolve (ripple/resolver.py): with the whole repository in view, each call site either becomes an edge, because the source proves its target, or is kept as unresolved with a reason. ripple never guesses. "There is only one method named save, so it must be that one" is exactly the kind of answer that looks right and is wrong in the cases an agent cannot check.

What counts as proof: names defined or imported in scope; import x, from x import y, aliases, relative imports and package re-exports; self.method() through base classes; super(); calling a class (edge to its __init__); and method calls on values whose class is known from a constructor call, a type annotation, a return annotation or a self.attr assigned in the class, including a value that is itself a call result (Foo().run(), make().run() where make is annotated -> Foo, Foo().current().place()). When a method is called on self or a typed value, subclass overrides are linked too (class hierarchy analysis), except on a value that is exactly Foo().

A call written where a definition is made belongs to the scope that holds the definition: default arguments and decorator arguments, and calls inside annotations (qty: Annotated[int, Field(gt=0)] on a class attribute, a parameter or a return annotation), which are edges of kind annotation. With from __future__ import annotations such an expression runs later, when pydantic or typing.get_type_hints evaluates it, but it is still a call written in that scope.

Decorators. @timed def hello() binds the name hello to whatever timed returns. When timed is a repo function that defines a wrapper and returns exactly that wrapper (def timed(fn): def wrapper(*a): return fn(*a); return wrapper, with or without functools.wraps), a call to hello is a call of wrapper, and wrapper calls every function decorated with it (edges of kind wrapped). A decorator that returns its argument (def register(fn): ...; return fn) leaves the name alone, a factory such as @route("/x") is read as the def it returns, and a stack is read from the bottom up. What ripple does not read, it treats as before, the decorated function called directly: a decorator from outside the repo (lru_cache, property, a framework's route), one that returns different things on different paths (if not enabled: return fn), one that is itself decorated (flask's setupmethod), a generator or async decorator, one that rebinds its parameter, a wrapper that has a decorator other than functools.wraps, a call of the wrapped function made from a function nested in the wrapper, a decorator applied by hand (f = timed(f)), a class decorator, and a function defined more than once (a def in each branch of an if, decorated on one or on both): which def a call finds depends on the branch taken, so the call stays a direct call of the function and no wrapper is added.

A call of a decorated function is typed by its def's return annotation (compute(1).wait() with def compute(x) -> Result) only when every decorator is proven to hand the value back: one that returns its argument, a wrapper whose every return is return fn(...) (not result = fn(...); return result, and not an async or generator wrapper), or property, staticmethod, classmethod, functools.cache, lru_cache, cached_property, abstractmethod, overload. Any other decorator, a repo one ripple cannot read or a dependency's (retry, validate_call), leaves the result unknown and the call unresolved, with the reason. A decorator also called as timed(g) keeps its wrapped call unresolved as well, since the wrapper may be given g too. One wrapper body serves every function its decorator is applied to, but in each decoration it calls one of them, so the edges of a decoration carry the decorated function (via) and impact and path follow a chain through the wrapper only for the function the chain entered it for: the callers of run_unload are not callers of ship because both are @audited. callers of the wrapper itself still lists every caller of every function it wraps. callers of a decorated function lists the wrapper, which is what calls it, and also, under through_wrapper, the lines that write its name and reach it through the wrapper; impact labels such a caller via_wrapper. So a signature change finds every call site to edit.

Functions held in names. with_tax = functools.partial(apply_tax, 10) then with_tax(x) is a call of apply_tax, when partial is functools.partial (imported any way), every assignment to the name is such a call, and they all name the same function or method of the repo (a bound method such as self.k.step also reaches the overrides of that method). It stays unresolved, with the reason, for a partial of a class, of a parameter or of anything ripple cannot resolve, a name assigned partials of different functions or also assigned anything else, and a module-level name another module assigns to (m.T = ..., m["T"] = ...), a name some function declares global and then rebinds (by assignment, def, class, import or except ... as), or whose module has a star import that could define it. Stores written as calls are covered by one blunt rule (see "Tables and partials, and the store words" below).

Dispatch tables. A module-level dict, list or tuple literal of plain function names is a fixed table when no code in the repo can change it, and then TABLE["k"](x), TABLE.get("k")(x), TABLE[1](x), a local assigned TABLE["k"] and called, and for f in TABLE: f(x) (also .values() and .items()) are calls of the entries they reach: the one under that key, or every entry for a loop. ripple proves "no code can change it" by reading every module for any use of the name that is not a read: a subscript store, update, pop, append or any other method that is not get/items/values/keys/copy, del, an augmented assignment, passing the table to a call (len(T) included), aliasing it, returning it, storing it, global T, a second assignment, getattr(m, "T"). Names are matched as text in every module, so an import alias (from m import T as U, through any chain), m.T and a star import are all covered, and so is an unrelated variable that happens to share the name (the call then stays unresolved, never guessed). A module that has a star import that could define the name is not trusted either, nor is any table while a store word appears in the repo (see below). The unresolved call says which use spoiled the proof and where (T may be changed or handed on: 'T' is used other than to read it, at m.py:60). An entry that is not a plain name of a function or method, a missing key, a variable key, a loop over a dict's keys, and a loop variable that is assigned anywhere else in its function (two loops that reuse a variable name count), called after the loop, in the loop's else, in a nested function, lambda or generator expression, all stay unresolved.

Tables and partials, and the store words. Code can replace a module's table or partial without writing module.T = ...: setattr(m, name, v) in a loop over overrides, mock.patch, vars(m)[k] = v, exec. ripple does not try to recognise the shapes of those stores (every shape it learned had another spelling). It looks for the words instead: setattr, delattr, __setattr__, __delattr__, __dict__, vars, globals, locals, __globals__, f_globals, f_locals, exec, eval, __import__, importlib, patch, monkeypatch, builtins, __builtins__ and sys.modules. If any file of the repo has one of them, as a name, an attribute, or in a string or a comment, in any spelling (an alias, self.module, a line continuation, a look-alike Unicode letter, a file in another encoding), no table or partial of the repo is followed, and the unresolved call names the word and where it is. That disables tables and partials in any repo that uses those words anywhere, a test file that only calls monkeypatch or patch included (so most repos with a test suite that patches). A file the word is in is not excepted because it does not import the module: another module can hand it one. Not covered: a word spelled by computing a string at run time (getattr(object, "__set" + "attr__")), gc.get_referrers, ctypes.

The index is cached outside your repo (RIPPLE_CACHE_DIR if set, else $XDG_CACHE_HOME/ripple or ~/.cache/ripple) and keyed on every file's mtime and size, so each query re-checks the files and rebuilds only when something changed. A TypeScript or JavaScript graph is also stored with what the resolver found on disk beyond those files (a file in a skipped directory, a .vue component, a directory, a link), and is not served once any of it differs (on create-react-app that is 471 paths and 20 ms of the 400 ms a cached load takes). On my machine (a WSL2 laptop, timings vary by about 30% run to run) click, 91 files, takes 0.4 s cold and 0.08 s from the cache; pydantic's repository, 3,156 files with its core's tests and docs, 3.7 s and 0.4 s, peaking at 190 MB; Django, 2,941 files, 16 to 20 s and 1.1 s, peaking at 445 MB (the cyclic garbage collector is off while the graph is built, which is faster and costs memory).

Benchmark

python -m bench scores ripple against hand-written ground truth: 63 caller, callee and impact queries over four small fixture apps in bench/fixtures (an order and pricing service, a notes CLI, a web handler layer, and a warehouse toolkit that holds the calls on standard library objects, on call results, in annotations and defaults, through decorators that wrap, and through functools.partial and dispatch tables). CI fails if any number drops below bench/baseline.json.

Case

Queries

Exact

Precision

Recall

Imports, aliases, re-exports

11

11

1.000

1.000

Methods, super(), constructors

6

6

1.000

1.000

Typed receivers (annotations, call results, standard library values)

8

8

1.000

1.000

Callees

3

2

1.000

0.750

Decorators (including wrappers)

10

10

1.000

1.000

Dynamic (getattr, dispatch tables, partials, untyped values)

12

4

1.000

0.438

Calls made at definition time

2

2

1.000

1.000

Impact (transitive)

7

4

1.000

0.633

Overall

59

47

1.000

0.779

Missed callers (scored apart, not in overall)

4

4

1.000

1.000

The missed-callers row scores the other half of the contract: for a symbol, the callers ripple lists under possible_missed_callers because it could not rule them out. There, precision is the share of the listed callers that really call the symbol (a caller that never does is a false alarm), and recall is the share of the callers ripple missed that it still lists. It answers a different question from the rows above, so it is not averaged into the overall figure.

How to read this honestly:

  • The truth was written before the code. The first three fixtures and every expected answer were committed before any indexer code existed (see the first commit), and the dynamic cases were included on purpose to show where static analysis stops. The warehouse queries were added the same way: each group was committed, failing, before the rule that answers it.

  • The truth is checked against runtime. bench/trace.py runs each fixture's own test suite under a profiler, records the calls that actually happen with the stack each was made under, and tests/test_ground_truth.py fails if any expected answer disagrees with that trace. An impact answer is read from the stacks, not from a closure over caller and callee pairs, which would also credit a chain no run takes (two functions sharing one wrapper). A caller no test runs through is listed apart, as unexercised, with the reason. The tracer shares no code with ripple.

  • It is small. 63 queries over four fixtures I wrote, each query aimed at one resolution rule or one known limit. It shows which rules work, not what recall looks like on your codebase, where more of the code is likely to be untyped and dynamic.

  • Precision is 1.000 everywhere, recall is not. ripple reports a call only when the source proves it, so every miss is a call it left unresolved (see "What the benchmark still misses" below), never a wrong edge. The benchmark does not cover a decorator ripple cannot read: there the decorated function is treated as called directly (see "Decorators" above), which is a design choice, not a proof.

Agent eval

The benchmark checks that ripple's answers are right. The eval checks whether a coding agent does better with them: nineteen refactoring tasks (ten on small fixtures, nine on real repositories), each run by Claude Code in headless mode, once with a ripple MCP server and once without, three times each. Nine more, over TypeScript repositories, have had one full run of the same shape (see "TypeScript tasks" and Results below).

  • The tasks (eval/tasks/) are renames and signature changes where grep is noisy or incomplete: a method named total on four classes, a function reached only through a package re-export alias, an override in another package, a getattr lookup that neither grep nor ripple can see. Seven run over eval/fixtures/ledger, a small invoicing app written for the eval, and three reuse the benchmark fixtures. Each task's why field says what makes it hard.

  • Grading. An edit counts as a success when the fixture's own tests pass against the agent's source and still number at least the task's minimum (min_tests), and a hidden test the agent never sees passes too. The tests that run are the starting repo's own, not the agent's copy of them (see "Graded the same way" below). The hidden test checks that the change was made and that every caller still works. tests/test_eval.py shows each check fails on the untouched fixture and passes on a reference solution, and CI runs it.

  • Same conditions. Both modes get the same model, tools and permissions (edit files, run pytest) and the same prompt: a short note that the shell is only for running tests and edits go through the Edit or Write tool, then the task. The MCP server is the only other difference, plus one line in the with-ripple prompt saying the server is connected and naming its tools (it does not tell the agent to use them, so ripple calls is the agent's own choice). Each run starts from a fresh copy under /tmp, in a directory whose name says nothing about the task or mode, and leaves out the user's own settings, hooks and auto-memory.

  • Invalid runs. A run is marked invalid and left out of the success rate, but counted and printed (per mode, per task and with its reason) in three cases: a with-ripple run whose ripple server fails to connect, a run that changed no file while an edit tool (Edit, Write, MultiEdit, NotebookEdit) was refused by the permissions, since the harness then blocked the very tool the prompt named, and a run the CLI refused before the agent did anything (an error result with no tool call and at most one turn, for example "You've hit your 5-hour limit"): reason the agent did not run: <message>. A usage or rate limit message also stops the batch at once, records it as stopped_message in the meta and prints how many runs were not started, so the batch can be re-run after the reset; a run cut off by the limit part way is aborted instead. Other refusals are routine and do not invalidate a run: an agent that tries sed -i despite the prompt, or a read-only command that is refused, and changes nothing, is a real failure. The result JSON keeps each run's refused tools and their inputs (permission_denied). Results from before this wording (the 2026-09-26 batch) used the bare task prompt.

Tasks over real repositories

The first ten tasks sit at the ceiling (see Results), so nine more run over pinned, real open-source repositories, where the agent can no longer read everything: rich v15.0.0 (38k lines), werkzeug 3.1.9 (22k) and sqlglot v30.29.0 (86k, with a Dialect/Parser/Generator hierarchy overridden across dozens of modules). They are in eval/tasks/11-* to 19-*.

  • Pinned. eval/repos.json names each repo by git URL and a full commit SHA (a tag or branch is refused), with the Python version and exact-version test dependencies. Nothing from these repos is committed or vendored: python -m eval.fetch downloads them into $RIPPLE_EVAL_CACHE (default ~/.cache/ripple-eval), without .git and without the repos' own CLAUDE.md or AGENTS.md, and builds one virtualenv per repo with the test dependencies (the repo itself is never installed, so a run tests the agent's copy). Needs git and uv. python -m eval.fetch --verify also runs each repo's own suite and prints its summary line. A few test files are left out (they build C code, start a dev server that imports an installed copy, or take a minute): see ignore and deselect in repos.json. Only the top-level test dependencies are pinned to exact versions: their own dependencies (numpy, tzdata, pluggy and so on) resolve at fetch time and are not locked, so two fetches on different days can differ there. A venv counts as built only once its install finished (a .ripple-ready file in it), so re-run python -m eval.fetch after an interrupted fetch, or to upgrade an older cache.

  • Node repos. An entry with "runtime": "node" names a test runner (vitest or jest) and a package-lock.json kept under eval/lockfiles/<name>/, because not every upstream commits one. python -m eval.fetch copies that lockfile into the checkout and runs npm ci --ignore-scripts (no package script ever runs) into $RIPPLE_EVAL_CACHE/deps/<name>-<key>/, where the key hashes the lockfile, and then makes that directory read-only. A working copy gets node_modules as a symlink to it, never a copy, and vitest runs with --no-cache because before vitest 4 it writes a results cache into node_modules. Needs npm; --verify runs the suite from a scratch copy and prints the runner's Tests line.

  • Hard on grep. Each task is a rename or a parameter rename whose true callers are known and spread over 4 to 20 files, and each goes through something that defeats grep: a same-named method on another class (Style.parse next to Color.parse), a decoy that must not change (Dialect.format_time and a module function beside the generator method being renamed), an override in another module, a call through self or super(), an alias or a function-local import, a function passed as an argument, a subclass in a test or an example no test runs. Each task's why gives the caller count and the files.

  • Graded the same way. The agent's tests are not the ones that grade it. When the agent finishes, its copy is copied again and the starting repo's own tests directory is put over it, with the reference solution's edits to those tests (the prompts name every new name and signature, so they are a fair oracle), along with every conftest.py, pytest.ini, tox.ini, setup.cfg, pyproject.toml, sitecustomize.py and any module added at the root of a source path that shadows pytest or the standard library. The whole suite then runs against the agent's source: it must pass, every test that passes on the reference solution must pass (a test that skips itself on the agent's source is caught), and at least min_tests must run. Deleting, gutting, skipping or conftest-patching a test therefore changes nothing; an agent that deleted or hollowed out a test the reference edited is also marked down (the identifiers the reference added to that test function must still be in the agent's). A hidden test passes too, run with no conftest over the agent's own files. The hidden tests scan every .py file with ast for stale uses of the old name (including examples and Windows-only code the suite never runs, tests the agent left on the old name, and a file that no longer parses is a failure, not a skip) and then exercise the callers; task 18's also checks the parameter reads inside the method bodies. Grading costs one reference run per task per process (cached) plus the hidden check and one full suite run per graded run, measured here at about 7 seconds per run for rich and werkzeug and about 40 for sqlglot (plus roughly 30 once per process for the reference run). What this cannot cover: anything the agent writes outside its copy (the venv is shared by every run), and source it changes to patch pytest itself at import time; the diff of every run is saved for that. A reference solution for each task is kept as a solution.patch (a diff, never upstream files). tests/test_eval.py shows each check fails on the untouched repo, passes on the patch, and fails again when the patch leaves out any one file of its callers. Those tests are skipped when the repos have not been fetched, so CI (which does not fetch them) stays green; run them locally after python -m eval.fetch.

.venv/bin/python -m eval.fetch --verify        # once: fetch the pinned repos, run their own suites
.venv/bin/python -m eval.run                   # 19 tasks x 2 modes x 3 repeats = 114 runs, into eval/results/
.venv/bin/python -m eval.run --tasks 11-rich-rename-style-parse,12-rich-rename-cell-len,13-rich-rename-highlighter-highlight,14-werkzeug-rename-http-date,15-werkzeug-rename-mapadapter-match,16-werkzeug-rename-get-response,17-sqlglot-rename-generator-format-time,18-sqlglot-rename-parse-table-parts-schema,19-sqlglot-rename-schema-column-names   # only the real repos: 54 runs
.venv/bin/python -m eval.run --tasks 04-ledger-rename-invoice-total --repeats 1 --out /tmp/smoke.json

Each batch writes eval/results/<date>-<time>-<id>.json (unless --out says otherwise), a .md table (headed by an arm: <label> line, as is the printed summary; a results file from before the arm existed has none) and a -diffs/ directory beside it, and refuses to overwrite an earlier batch's files.

It calls the claude CLI on whatever account it is logged in to, so it never runs in CI.

TypeScript tasks

Nine more tasks (eval/tasks/20-* to 28-*) run over four pinned TypeScript repositories. They have had one full run (54 runs, three repeats per task and arm; see Results). The harness was first proven with a fake agent (see below). The grader (eval/check_node.py) is the same design as the Python one: the repo's own runner over the agent's source with the reference's tests put back, plus a hidden TypeScript test.

Task

Repo (runner)

What is renamed

What makes it ambiguous

20

neverthrow (vitest)

static ResultAsync.combine

Result.combine keeps its name; 49 of the 54 calls are in a file only tsc reads

21

neverthrow (vitest)

instance ResultAsync.orElse

three look-alike orElse methods; the receiver's type is the only clue

22

superstruct (vitest)

exported function assert

Struct.assert keeps its name; most uses are in typing tests and examples no test run reads

23

superstruct (vitest)

exported function create

a method and a boolean create flag in 19 fixtures share the name

24

tsyringe (jest)

interface member Transform.transform

TransformDescriptor.transform keeps its name, in the same expression; some implementers never write implements

25

tsyringe (jest)

decorator registry

applied as @registry(...), never called by name; module paths and a registry variable keep the word

26

react-pro-sidebar (vitest)

component SubMenu

237 identifiers plus code samples the website builds as strings; the module and test titles keep it

27

react-pro-sidebar (vitest)

hook useMediaQuery

a test names the export in a string (vi.spyOn(..., 'useMediaQuery')); module specifiers keep it

28

react-pro-sidebar (vitest)

the Menu prop transitionDuration

seven properties of that name; only the Menu's changes

What ripple answers on them, from the task why fields and the checks made when the tasks were written (not re-measured when the harness was wired; 24 and 25 were measured again on the pinned checkout after ripple began to flag decorations and the calls inside class expressions). Where it falls short is part of what the eval can show:

  • 20 and 21: complete on the symbols checked.

  • 22: 77 of the 83 calls, with no false one. The 6 it misses are in examples/*.js, which import the package by its own name. 23: 4 of 5.

  • 24: callers resolved 0 of 6. The member is declared on an interface, which ripple does not index, so no symbol has that name to ask about: transform is ambiguous between the methods of the classes that act as transformers. Three of the six calls are inside the class expression autoInjectable returns, which is not read. Those three used to be absent from every answer, and the same-name list found 3 of the 6. Now the 20 calls in that body are unresolved calls, and impact of a transformer's transform method lists all 6 under possible_missed_callers, the three from the class expression marked "inside a class ripple does not read" (callers lists those three). No call is resolved from that body, so callers still resolve 0 of 6.

  • 25: callers and impact of registry return 0 callers, which is right: it is never called by name. They now also list the 12 places it is written as @registry(...) (3 files: 10 in global-container.test.ts, 2 test fixtures), under decorations with the note that a decorator's effect is not modelled. The word still appears in module paths, a registry variable and the README, which ripple does not index.

  • 26: renders finds 84 of the 108 elements with precision 1.000 (the website demos import the package by name); renderer finds 0 of 108. 27: 6 of 6.

  • 28: a prop rename. ripple does not index props.

Fetch. python -m eval.fetch neverthrow tsyringe superstruct react-pro-sidebar (or no names, for every repo) needs git, node and npm and the network. It installs each repo's dependencies with npm ci --ignore-scripts from the lockfile vendored under eval/lockfiles/, into a read-only cache outside this repository.

Run. --runtime picks the tasks and defaults to python, so a plain python -m eval.run is the same 19 tasks, the same command line and the same cost it always was. --runtime node selects tasks 20 to 28, all selects both, and --tasks runs exactly the ids it names (a node task by id needs no --runtime; a mixed list is fine). For the with-ripple arm on a node task, --ripple-python PATH names an interpreter that has ripple with the typescript extra (pip install 'ripple-code[typescript]', which brings tree-sitter); it starts the server for the node tasks only. A Python task in the same batch always starts the ripple next to the interpreter running eval.run, as it always has, and a batch with no node task ignores the flag (one line says so, and the results file records it under ripple_python with ripple_python_ignored). The default is the interpreter running eval.run, and a node run that cannot index TypeScript with it is refused. --dry prints the plan and runs the readiness checks without starting an agent or calling a model:

.venv/bin/python -m eval.run --runtime node --ripple-python /path/to/venv/bin/python --dry
.venv/bin/python -m eval.run --runtime node --ripple-python /path/to/venv/bin/python --repeats 1 --out /tmp/ts-smoke.json
.venv/bin/python -m eval.run --tasks 20-neverthrow-rename-resultasync-combine,24-tsyringe-rename-transform --modes without --dry

What the agent has. The same shape as the Python runs, with node's commands. The shell allows exactly the repo's runner (vitest or jest) and tsc, and each is a small script in the run's own directory, not the binary:

  • The runner script runs what the grader runs (RepoSpec.node_argv, in the same environment: the repo's own binaries first on PATH, CI=true, no colour, vitest with --no-cache because before vitest 4 it writes a cache into the read-only node_modules). With no arguments it runs the repo's whole suite exactly as the grader does, so the agent sees the pass count the grader sees; with file paths or -t they go after the same flags. Snapshot updates, report files, coverage output, watch mode and init are refused.

  • tsc is for the type check only: --noEmit is forced and only -p/--project and a few read-only flags pass, so it cannot emit, build, init a config or write a build-info file. neverthrow's 49 ResultAsync.combine calls live in a file that only tsc reads, so tsc is the only way the agent can compile-check that task's stale calls.

  • npm test, npx, npm run, npm exec and node are not allowed: each can run any script or any code, which reopens the sed, xargs and node -e rewrite channels the Python run closes. The repos' own npm test scripts also differ and some write (superstruct's builds into dist/ first, tsyringe's runs yarn lint, neverthrow's runs tsc after vitest, and none passes --no-cache).

  • The prompt's first paragraph is the node version of the Python one (it names vitest run or jest and tsc --noEmit -p <tsconfig>, and says to edit with the Edit or Write tool), the same in both arms.

  • With ripple, the server is started with --lang typescript and a --test-command that is the runner script, so the check tool runs the same command; a TypeScript repo has no default test command and check would otherwise refuse. The ripple index skips node_modules, which is a link to the cache in the agent's copy.

  • changed_files and the saved diff for a node task cover .ts .tsx .js .jsx .mts .cts .mjs .cjs .json .md .mdx files, never node_modules.

  • A with-ripple node run whose server did not connect is invalid, as for Python.

What a run records of ripple. Besides the counts (tool_calls, ripple_calls), every run record carries ripple_exchanges: for each mcp__ripple__* call its tool, its input (clipped like a denied tool's) and, from the matching result, is_error, result_chars (the whole text) and result_head (the first 2000 characters). A call the run ended before answering has null for those three. toolsearch_queries lists the inputs of every ToolSearch call. The two share a 40 KB cap, the first ones kept, and ripple_exchanges_truncated says when it cut. The batch table gains a "runs with a ripple error" column when the runs recorded exchanges. These keys are what shows whether an agent that called ripple got an answer it could use (the earlier TypeScript batches recorded counts only).

Test arms. Three flags, all off by default; with none set a batch is exactly what it was (tests/test_eval_arms_pins.py pins the command, prompts, tool lists, mcp config, shims and record to literals from before they existed). They combine, and the arm is a label (base, forced, hard, restricted, joined with + in that order) in the results meta and in every run record, so a results file says which arm it is. --dry prints the arm, the text the agent is told before the task for each runtime and mode, and the allowed and disallowed tools. Code in eval/arms.py.

  • --forced-use: the with-ripple prompt gains one paragraph after the line that says the server is connected: "Before editing, call the ripple callers tool on the symbol you are changing and use the call sites it returns." The without arm is unchanged. Python and node tasks (not every Python task is a rename, so the sentence says "changing").

  • --hard-prompts: each task's hard_prompt (an optional task.json field; tasks 20 to 28 have one) replaces its prompt, in both arms. It is the same task with no file paths, no lists or counts of sites and no hint of where uses live, but every rule about what keeps its name, "update every use", the no-alias rule and the suite rule are kept, and the four tasks whose hidden check reads documentation (24, 25, 26, 28) still say, in general words, that the documentation is part of the rename. A Python task selected with it is refused before anything starts. tests/test_eval_hard_prompts.py lists, per task, the phrases a hard prompt must keep and bans paths and counts.

  • --restrict-search: both arms lose the Grep and Glob tools, LS, the web tools and the shell commands that search (grep, rg, find, git grep, ...: Claude Code lets read-only shell commands through without a rule, so denying the tools alone leaves the shell as a search channel; a deny rule beats the allow rules). A node task also loses its tsc script and Bash(tsc:*) rule, so the shell holds the runner only. The preamble names only the runner (pytest for Python) and says search is not available. A restricted run lists its shell commands under bash_commands (the first 60, 160 characters each), so a search that got through shows in the record. Known open channel: the arm does not remove search. The runner stays allowed and the agent can Write, so it can write a test file that walks the tree and prints the lines it wants, then run that file with pytest, vitest or jest. Nothing here stops it. It shows only after the fact: bash_commands lists a runner call on a file the agent just made, and the changed-files list holds that new test file. Read both before treating a restricted run as one that did not search.

Checked before any agent starts (in --dry too): node and the runner's and tsc's binaries are in the install; and, when the with-ripple arm is selected, the ripple interpreter imports ripple, tree-sitter and its TypeScript grammar, and for each node repo the server (started with the config the runs use, on a scratch copy) lists its five tools and answers a query without a warnings list. Any failure stops the batch with a message and nothing started.

What this does not prove: the shell rules were tested through the scripts and a model of Claude Code's Bash(prefix:*) matching, not against a live agent, so how the CLI treats shell redirections under those rules is assumed to match the Python runs. The fake-agent tests apply each task's reference solution through the same scripts, PATH, linked node_modules and diff recording a real agent gets, and the grader marks them successes; that shows the environment works, not that an agent can use it.

Results

First full run, 2026-09-26, Claude Sonnet 5, 60 runs (eval/results/2026-09-26.json):

Mode

Success

Median input tokens

Median output tokens

Median turns

Median wall time

with ripple

30/30

145,461

3,372

19.5

25.2 s

without

30/30

129,108

3,211

15.0

22.9 s

ripple did not help on these tasks. Both modes solved every task every time, so there is no difference in success to measure, and with ripple the agent spent about 13% more input tokens and four or five more turns, mostly on loading and calling the tools (78 ripple calls across the 30 runs).

The likely reason is the tasks, not the tool: the fixtures are a few hundred lines, small enough that the agent can grep and read everything it needs, which puts both modes at the ceiling. The cases where a call graph should matter (a large unfamiliar codebase, callers the agent never opens) are exactly the ones this first task set does not have. The next version of the eval needs tasks over bigger, real repositories, where the without-ripple agent has a real chance to miss a caller.

In this run each arm's working directory name included its condition label (such as --with-ripple--), which the agent can see; that is fixed now, and the result is unlikely to depend on it since both arms scored 30/30.

TypeScript tasks, 2026-11-09, Claude Sonnet (--model sonnet), nine tasks, three repeats per task and arm, 54 runs, ripple at 5147bf7 (eval/results/2026-11-09-typescript.json):

Mode

Success

Median input tokens

Median output tokens

Median turns

Median wall time

Median cost-equivalent

with ripple

27/27

247,566

5,105

26

43.8 s

$0.155

without

27/27

218,666

5,250

29

38.9 s

$0.146

Both arms solved every task every time, so again there is no difference in success to measure. With ripple the agent used about 13% more median input tokens and took slightly longer, but not more turns (median 26 against 29). The whole batch cost $13.46 in cost-equivalent terms and took 74 minutes.

The agent barely used ripple. It called a ripple tool in 11 of the 27 with-ripple runs, 12 calls in all, and in none of the 15 runs on tasks 24, 26, 27 and 28 (one run of task 25 called it twice). So this compares an agent that has the tool with one that does not, and says nothing about whether ripple's answers help when they are used. Both arms can run tsc --noEmit and the repo's test runner; I did not measure how often they used tsc, which finds stale uses in code the suite never runs.

An earlier one-repeat look at the same tasks (9 of 9 against 8 of 9) is not part of these numbers: the one failure was a task 26 prompt that let the agent rename a runtime warning text the suite asserts, fixed before this run.

Tool-use test arms

Because agents called ripple in only 11 of the 27 with-ripple TypeScript runs, four more batches were run on 2026-11-09 to find out why (records in eval/results/2026-11-09-tool-use-arms/, same model, three repeats per task and arm, about $47 in all):

Arm

What it changes

With ripple

Without

Ripple use (with-ripple runs)

P0: Python tasks 01 to 10

nothing (current model, neutral working directory)

30/30

not run

29 of 30 runs, 62 calls

F: --forced-use, TypeScript

the prompt tells the agent to call callers before editing

27/27

not run

27 of 27 runs, 33 calls

H: --hard-prompts, TypeScript

prompts with no file paths or lists of sites

25/27

27/27

7 of 27 runs, 11 calls

R: --restrict-search, TypeScript

no Grep, Glob, LS or web; shell search commands denied; no tsc

23/27

27/27

27 of 27 runs, 53 calls

  • P0. Python agents still called ripple in nearly every run (30 impact, 32 check), as in the first run, so the TypeScript gap is not the model or the old working-directory label. Python impact returns pytest ids that feed check; TypeScript has no such ids. As graded, P0 task 05 failed 3 of 3 because the agent renamed a test function and the grader keyed tests by name; that grader bug is fixed, and the three real diffs replayed through the fixed grader pass, so 30/30 is after a regrade by replay, not a re-run.

  • F. When told to, every agent called ripple and the tool path worked (no tool errors). But 11 of the 33 answers were "no symbol named ..." errors, on tasks 24, 26 and 28, where the agent wrote an id such as src/components/SubMenu:SubMenu for a symbol that is SubMenuFR. Four runs tried again, and none of the nine runs on those three tasks got a usable answer for the symbol being renamed.

  • H. Short prompts did not raise usage, and the two with-ripple failures were not the same cause: one agent used impact, which gives one entry per module and no call-site lines, and left 4 stale calls in a file only tsc reads; the other made no ripple call and missed 11 uses in a test file after its tsc and jest commands were blocked. 25/27 against 27/27 is not a significant difference.

  • R. With search taken away, agents with ripple cost about 35% less (median $0.261 against $0.403 per run, 379k against 643k input tokens) and passed less often (23 of 27 against 27 of 27). Each of the four with-ripple failures is a site ripple cannot see: examples/*.js that import the package by its own name (tasks 22 and 23), the website demos (task 26), and a prop (task 28). The pattern fits an agent that stops when the list ends, but four failures against none is not significant (Fisher exact p about 0.11).

Read these with their limits. Cells are three runs each. Eleven R runs were lost to the account's usage limit (ten ended after one turn, one at turn 39), the harness did not flag them, and they were excluded and re-run, with the ten re-runs recorded as repeat 1. The R restriction leaked: in 11 of the 54 valid runs (7 with ripple, 4 without) a shell command naming grep, awk or find ran, because a deny rule does not see a search word inside a compound command that starts with an allowed one; on the 43 runs with no leak the result has the same shape (with ripple 17 of 20, without 23 of 23). R is "mostly restricted", not ripple-only, and an agent can still search by writing a test file.

Known limits

Static analysis of a dynamic language misses things. ripple does not follow:

  • method calls on values of unknown type: unannotated parameters, loop variables, results of functions without a return annotation (reported as unresolved, with the reason)

  • getattr, registries that are added to, a dict or list looked up by a variable key or whose contents are not plain function names, callbacks passed as arguments, a functools.partial that is not bound to one name (passed on, stored in an attribute, or built by a call)

  • decorators ripple cannot read: for those the decorated function is treated as called directly, so a call of it is not shown as a call of the wrapper. That covers a decorator from outside the repo (lru_cache, a framework's route), a decorator that is itself decorated, a generator or async decorator, and a function wrapped by hand (f = timed(f)). A class decorator is never read: the class keeps its name, and a decorator that may return something else than the class (a subclass, a wrapper) is not followed. What ripple does is stop calling a value built from such a class exactly that class, so its subclass overrides stay linked (see the exact-class rule below). It does not add an edge to the class the decorator builds, which it cannot see. See "Decorators" above for the full list

  • calls ripple leaves unresolved on purpose, where it could have guessed:

    • a method on a value annotated with a class from outside the repo (logging.Handler) when a repo class that may inherit from it overrides the method. A repo class's base is compared with the annotation by what the interpreter says for standard library classes, and a dependency's class or a base ripple cannot read is never ruled out, so the call stays unresolved and impact lists it under possible_missed_callers

    • a call result through a decorator ripple cannot prove returns what the def returned, and through a function with a def that has no annotation among several (see "Decorators")

    • every table and partial while any file of the repo has a store word (setattr, patch, monkeypatch, vars, exec, importlib, sys.modules and the rest of the list in "Tables and partials, and the store words"), or while the repo has a file ripple cannot parse

  • __call__, metaclasses, monkeypatching, importlib, exec, and a call on the result of a function with no return annotation naming a class (make().run() is followed when make has a return annotation or is a class; ripple does not read return Foo() to infer one, and an @overloaded function or two defs of one name that annotate differently, or only one of which is annotated, in either order (a def in each branch of an if sys.platform), give no type)

  • calls written inside a string annotation (x: "Annotated[int, Field(gt=0)]"): the string is not parsed. Calls in an ordinary annotation are recorded (see above); the annotation of a local variable in a function (x: Annotated[int, Field()] = 1 inside a def) is never evaluated by Python, so it is left out

  • syntax the Python running ripple cannot parse (except* before 3.11, type X = ... and def f[T]() before 3.12): that file is listed as unparsable and left out. So are files with invalid bytes or a null byte, and files nested so deeply that the parser itself gives up (hundreds of thousands of terms). Such a file may rebind a table or a partial where ripple cannot see it, so while the repo has any, no table or partial is followed, and the unresolved call names the file Generated code nested far deeper than ordinary code (an elif chain of 1,500 branches) is indexed on Python 3.12 and later, where ripple raises the recursion limit while it indexes. Before 3.12 it leaves the limit alone, because another thread recursing without bound would then crash the process, so a file nested deeper than the default limit allows is listed as unparsable

  • code imported under a name that differs from its path in the repo (modules are named by their path from the repo root, with a leading src/ dropped; pydantic's pydantic_core lives under pydantic-core/python/, so about 8,000 calls into it count as outside the repo). Two files that get the same name (tests/test_x.py and src/tests/test_x.py) share one set of symbol ids, so a name defined in both is one symbol; ripple index warns when that happens and names the files.

  • directories that hold dependencies or build output: hidden directories, __pycache__, node_modules, site-packages, venv and any directory with a pyvenv.cfg anywhere, any directory a build, dist and env at the repo root only (a directory a tsconfig.json names as outDir is skipped for TypeScript and JavaScript, never for Python). ripple index lists the skipped directories, except hidden ones and __pycache__.

  • custom pytest collection settings (python_files, python_functions, python_classes): test node ids follow pytest's defaults. ripple sees only the repo's own classes, so a class counts as a unittest.TestCase subclass when it has a base from outside the repo whose name ends in TestCase (unittest.TestCase, django.test.TestCase), and an __init__ inherited from outside the repo is not seen.

Override edges can over-approximate: a subclass override is linked even if that subclass never reaches the call site. The exception is a variable whose every assignment is a call of one class named directly (field = Field(), not self.Field(), which a subclass may redefine). It is exactly that class, so no override is linked, but only when ripple can prove the call builds it: no class in its repo hierarchy defines __new__ or declares a metaclass (either can return a subclass, as anyio's Event.__new__ does), every base resolves, and every decorator on the class and on its bases hands the same class back. A class decorator binds the name to whatever it returns, so one that is a repo function or class, or that ripple cannot resolve, may return a subclass: the class is not exact. Outside the repo only a short list is trusted: dataclasses.dataclass (bare or called), attr.s, attr.attrs, attr.attributes, attr.define, attr.mutable, attr.frozen, attr.dataclass and attrs.define, attrs.mutable, attrs.frozen (bare or called, imported from attr or attrs), and, written without a call, functools.total_ordering, typing.final and typing.runtime_checkable. Any other decorator from outside the repo (six.add_metaclass, pytest.mark.x) leaves the class not exact. A repo decorator that only returns its argument is not told apart from one that returns a subclass, so it costs the class its exactness too. Otherwise override edges stay. Method lookup walks bases depth-first, which matches Python's C3 order except in diamond-shaped hierarchies.

To keep the blind spots visible, callees lists every unresolved call with its reason, and impact lists unresolved call sites that use the same name as the target under possible_missed_callers. A call counts as "code outside the repo" only when it must be: a method missing from a class's repo bases is inherited from an external base such as Exception, unless a base could not be resolved (class Cached(make_base())) or a subclass defines the method, and then it is unresolved too. Subscripted bases such as Repo[int] or Generic[T] resolve to the class they subscript.

A method called on a value of a class from outside the repo is outside the repo too, and impact no longer lists it as a possible missed caller, but only when ripple can prove the receiver's class: a builtin value; a plain class of the standard library (deque(), Path(...), x: threading.Event, self.ready = threading.Event(), checked by asking the interpreter about a short list of modules that are safe to import); or a class some class in the repo inherits from, since only a class can be a base. It stays unresolved when a repo subclass overrides that method and the value is not built in place (an annotation buf: deque may hold the LoudDeque that overrides extend), when the name is not proven a class (session = requests.Session() where nothing in the repo inherits from Session, or an annotation such as Any, a protocol or an ABC), and one attribute further (local.chal.get(): what is stored on an object from outside the repo may be a repo object). An unresolved receiver says why in its reason (an unannotated parameter, a loop variable, the result of a call to a function without a return annotation, ...), and ripple index --reasons counts unresolved calls and calls outside the repo by cause.

What the benchmark still misses, and why

python -m bench lists every query it does not answer exactly. Each remaining miss needs something ripple does not do, and none of them is a bug that more rules would fix without guessing:

  • Receivers whose class only a type inferrer or the running program knows. The loop variable over a list with no element type (for item in self.items: item.subtotal()), the parameter without an annotation (store.search(...)), the value returned by a function without a return annotation (best_discount(), pick_three()), and a lambda over an untyped list. Closing these needs return-type inference and element-type inference, and ripple reads annotations and constructor calls only. The impact queries that hang on one of these hops inherit the miss, since every caller further up the chain is missed too.

  • Names built at run time. getattr(module, "cmd_" + name), getattr(self, "on_" + verb) and a table looked up by a variable key. The target is a string value that exists only when the program runs.

  • A table something changes. A registry that is added to after it is built (REGISTRY["b"] = ...) does not fix what a key finds, so REGISTRY["a"](x) stays unresolved. Only a table no code in the repo can change is read (see "Dispatch tables"). Proving a mutation does not matter would need knowing the order the code runs in.

In every case ripple reports the call as unresolved with its reason and, for impact, lists it under possible_missed_callers, rather than choosing a target.

Next

  • TypeScript, further: jest and vitest collection, so that impact lists the tests that reach a symbol and check can run them.

Development

uv venv && uv pip install -e ".[dev,typescript]"
.venv/bin/python -m pytest -q      # unit tests, plus the ground truth against its runtime trace;
                                   # the TypeScript tests are skipped, with the reason, without the extra
.venv/bin/python -m bench          # the benchmark; --write-baseline after a deliberate change

MIT licensed. Copyright (c) 2026 Dylan Fodor.

Available Tools

5 tools
calleesA
Read-onlyIdempotent

List what a function or method calls: resolved callees with call sites, plus the calls ripple could not resolve statically and why.

Inputs: symbol (required).

callersA
Read-onlyIdempotent

List the functions and methods that directly call a symbol, with the file:line of each call site. symbol: dotted path, Class.method suffix, or bare name.

Inputs: symbol (required).

checkA
Destructive

Run the repository's test command (default: python -m pytest -q) and return pass or fail, the summary line and the first failing tests, never the full log. tests: optional pytest node ids or test paths inside the repo to run instead of the whole suite, e.g. the node_id of each test impact listed. Options (anything starting with '-') are refused.

Inputs: tests.

impactA
Read-onlyIdempotent

Answer 'what breaks if I change this?': every transitive caller of a symbol up to depth hops, grouped by file, with the tests that reach it listed separately (each with the pytest node_id to pass to check). At most limit callers and limit tests are listed; truncated and omitted_callers / omitted_tests say how many more were found. Also lists unresolved call sites with the same name, which static analysis cannot rule out.

Inputs: symbol (required), depth, limit.

pathA
Read-onlyIdempotent

Find the shortest call chain from one symbol to another, e.g. from a test or entry point to the function you are changing. Returns each hop with the file:line it is called from.

Inputs: source (required), target (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool answers a distinct query: direct callers, direct callees, transitive impact, shortest call chain, and test execution. The only near-overlap is callers vs. impact, but the descriptions explicitly distinguish direct vs. depth-limited transitive results, and direction (callers vs. callees) is spelled out.

    Naming Consistency4/5

    All five names are short, single-token lowercase words with no mixed casing or prefix noise, which reads as a deliberate convention. Minor deviation: callers/callees/path/impact are nouns while check is a verb, but the set is still highly predictable.

    Tool Count5/5

    Five tools is tightly scoped for a call-graph analysis server, and each maps to a real workflow step (navigate down, navigate up, assess blast radius, trace a route, verify with tests). Nothing feels redundant or padded.

    Completeness4/5

    The forward/reverse/path/verify lifecycle is covered, including unresolved call sites and test node_ids, which is unusually thorough. The main gap is symbol discovery: there is no search, list_symbols, or definition tool, so an agent must already know the exact symbol path or rely on external grep.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a dependency graph of any local repository with tools for change impact, transitive dependents, health audits, and more, enabling AI coding agents to see structure and refactor safely.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides a graph-based code analysis to coding agents, enabling tools to trace call dependencies, assess change impact, and identify hotspots using tree-sitter and Neo4j.
      10
      6 npm
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to query a local-first code intelligence graph of Python repositories—covering functions, classes, modules, and their relationships—via MCP, supporting subgraph retrieval, caller lookup, and impact analysis without re-reading the codebase.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to analyze Python repositories structurally via AST and call graphs, providing code search, symbol lookup, change-impact analysis, workflow tracing, and explanation without embeddings.
      1
      -