@suss/adapter-python 0.22.4 → 0.24.0

package/README.md

@@ -1,439 +1,47 @@
 # @suss/adapter-python
 
-The Python language adapter for suss. It parses source with tree-sitter (WASM), resolves names with its own lexical binder, and emits behavioral structure through the same shared assembly layer the TypeScript adapter uses.
+Read a Python codebase with [suss](https://github.com/nimbuscloud-ai/suss).
 
-## What this package is
+suss reads both sides of every call in a repository and says where the two disagree: a client asking for a field the route stopped returning, a status nobody handles, a queue with no consumer. It reads the code itself, with no model and no network. This package is the part that reads Python: it parses with tree-sitter, binds names the way Python does, and writes down what each route declares and what each handler reaches.
 
-`@suss/adapter-python` is the Python language adapter. It meets the Layer 1 contract in [`docs/internal/facts-and-rules.md`](../../../docs/internal/facts-and-rules.md): discover units, emit summaries in the shared IR, emit facts. It parses a file with `web-tree-sitter` and a vendored Python grammar (`grammar/tree-sitter-python.wasm`, so there is no native build step), builds module, class and function scopes over the tree (imports, assignments, `global`/`nonlocal`), works out which file in the repo an import points at, and finds routes on decorated functions and class methods whose decorator resolves to a module the pack was configured with. When a pack says the library mounts routers (FastAPI's `APIRouter` plus `include_router`), the adapter builds a route's path out of the two literal prefixes, one mount hop deep. When it cannot build the path, the route keeps its name, gets no path, and gets a gap explaining why. Each unit it finds becomes a `RawCodeStructure` object, which it hands to `assembleSummary` in `@suss/extractor`, the same assembly code the TypeScript adapter uses.
+## Install
 
-v0 (this slice) does nothing with the path engine. A route either has no transitions at all, or one transition that describes the response the code declares (a FastAPI `response_model` / `status_code`, or a return annotation). It never breaks a route into branches. See [`design/proposals/language-adapters.md`](../../../design/proposals/language-adapters.md) for what a later slice adds.
-
-## Where it fits in suss
-
-This package depends on `@suss/extractor` (for `RawCodeStructure` and `assembleSummary`), `@suss/behavioral-ir`, `@suss/datalog` (for the fact database), and `web-tree-sitter`. Framework packs under `packages/framework/*` (`@suss/framework-flask-restx`, `@suss/framework-fastapi`) use its `PythonPack` contract. Nothing in this package knows what any particular library calls its decorators.
-
-## Path templates
-
-A pack declares which syntax its library uses for path parameters, under `pathParamSyntax`. The adapter understands two. `"braces"` covers `{name}` and `{name:converter}`, which is what FastAPI uses via Starlette. `"flaskConverters"` covers `<name>`, `<converter:name>`, and `<converter(arguments):name>`, which is what flask-restx uses via Werkzeug. In both cases the adapter rewrites the path into the IR's plain-brace form and treats the parameters in the template as path parameters.
-
-If a pack declares nothing, it gets paths exactly as written and no parameter is treated as a path parameter. If a pack declares a syntax the adapter has no reader for, its routes are still discovered, but they come out with no path and a recorded gap. Packs written against 0.3 assumed brace parsing applied to every path, so those packs now have to declare `"braces"` explicitly.
-
-## Which expression is the app
-
-A route is a decorator on something, and whether it counts depends on what that something is. `@app.get("/x")` is a route when `app` was built by calling what FastAPI exports, and nothing at all when `app` is some other object with a `get` method. So discovery has to answer one question per decorator: what built the object this hangs on?
-
-The lexical binder goes first, and it settles most cases: it follows the name one hop back to the call that built it and reads where that call's constructor was imported from. It is fast, it needs no facts, and it covers the module-level app and the app factory.
-
-The binder only records a name written directly in a body's own statement list, and it has no idea what an attribute refers to. So these two get nothing out of it:
-
-```python
-class Holder:
-    def __init__(self):
-        self.app = FastAPI()
-
-    def wire(self):
-        @self.app.get("/health")     # the binder has no binding for self.app
-        def health(): ...
-
-try:
-    app = FastAPI()
-
-    @app.get("/health")              # the binder skips a name written inside a try
-    def health(): ...
-except RuntimeError:
-    pass
-```
-
-Whatever the binder declines goes to the rules in `@suss/resolution`, as `wantedSubject`. They follow the value however it was moved, through a binding, a property read, an import, or an argument, and come back with the call it was written as and where that call's callee came from. The TypeScript adapter asks the same question of the same rules, so a spelling either language learns to follow, both get.
-
-The rules settle on one construction or on nothing. A name that could be two different constructions comes back with neither, because keying a route on the wrong app is worse than keying it on none, and then the decorator stays unclassified and the route is not discovered.
-
-Three Python facts feed the question. A method's receiver binds to the class it is declared in, which is what makes `self.app` the value the class puts under `app`. An assignment written inside a method body binds its name, which the class walk used to skip. And an import of a package the repo cannot read still records which module a name came from, which is how `FastAPI()` is told apart from a same-named constructor the project wrote itself.
-
-## How a prefix is read
-
-A mounted route's path comes from prefixes written at up to four places: the object the mount is called on, whatever that object was built from, the router's constructor, and the call that mounts it. All four go through one reader, and a given spelling means the same thing at every one of them. We got this wrong three times by fixing one place or one spelling at a time, so the whole grid is written out here.
-
-Every cell describes what the library itself does. We read that off the library's source and then confirmed it against a running app, using `url_map` for flask-restx and the route table for FastAPI.
-
-**At the constructor** (`Namespace(path=...)`, `APIRouter(prefix=...)`):
-
-| Written              | flask-restx serves         | FastAPI serves             | What suss records                                                            |
-| -------------------- | -------------------------- | -------------------------- | ---------------------------------------------------------------------------- |
-| nothing              | `/` + the namespace's name | the route path, no prefix  | unstated                                                                     |
-| `"/orders"`          | `/orders` + the route path | `/orders` + the route path | stated                                                                       |
-| `"/orders/"`         | `/orders` + the route path | the app does not start     | stated, trailing slashes trimmed where the pack says so                      |
-| `"/"`                | the route path, no prefix  | the app does not start     | stated, and trimming leaves nothing                                          |
-| `""`                 | `/` + the namespace's name | the route path, no prefix  | unstated where the pack says a no-value prefix is unstated, otherwise stated |
-| `None`, `False`, `0` | `/` + the namespace's name | the app does not start     | unstated where the pack says so, otherwise unreadable                        |
-| a name, a call, or an f-string the evaluator settles | whatever it evaluates to | whatever it evaluates to | stated, with the string it settles on                     |
-| anything the evaluator cannot settle | whatever it evaluates to | whatever it evaluates to | unreadable                                                   |
-
-**At the mount** (`add_namespace(ns, path=...)`, `include_router(router, prefix=...)`):
-
-| Written              | flask-restx serves                                   | FastAPI serves                                     | What suss records                                     |
-| -------------------- | ---------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------- |
-| nothing              | where the constructor put it                         | the constructor's prefix + the route path          | unstated                                              |
-| `"/api"`             | `/api` + the route path, replacing the constructor's | `/api` + the constructor's prefix + the route path | stated                                                |
-| `"/api/"`            | `/api/` + the route path, kept as written            | the app does not start                             | stated                                                |
-| `""`                 | where the constructor put it                         | the constructor's prefix + the route path          | unstated where the pack says so, otherwise stated     |
-| `None`, `False`, `0` | where the constructor put it                         | the app does not start                             | unstated where the pack says so, otherwise unreadable |
-| a name, a call, or an f-string the evaluator settles | whatever it evaluates to              | whatever it evaluates to                           | stated, with the string it settles on                 |
-| anything the evaluator cannot settle | whatever it evaluates to             | whatever it evaluates to                           | unreadable                                            |
-
-The two libraries differ on one property, and the pack says which way each one goes. flask-restx checks whether the path is truthy, so all four no-value spellings mean the same thing as writing nothing, at both places. FastAPI wants a string, so an empty string is an ordinary prefix that happens to add nothing, and the other three stop the app from starting.
-
-Here is what the reader does with each answer. A stated prefix goes into the path. An unstated one adds nothing, unless the pack says the library makes up a path of its own when the prefix is unstated. In that case the route abstains, because the path it is actually served at is somewhere suss never looked. An unreadable prefix abstains too. A route that abstains keeps its name and gives no path, and the summary says why.
-
-The trailing-slash rows are not symmetric. flask-restx trims at the constructor and not at the mount, because only the constructor's path goes through the property that strips it. The pack declares trimming per library, and the mount side does not need it, since a mount that states a prefix on that library abstains anyway.
-
-### The object the mount is called on
-
-flask-restx serves a route under the prefix of the object `add_namespace` was called on, ahead of everything the namespace and the route say. That object has two prefixes of its own: one written on it, `Api(prefix=...)`, and one written on the Flask blueprint it was built from, `Blueprint(name, __name__, url_prefix=...)`. The library joins the blueprint's prefix, the `Api`'s, the namespace's path and the route's path by concatenating them and dropping the falsy ones, so nothing is stripped at either of these two sites.
-
-FastAPI has no column here: its app has no prefix of its own, and the pack declares none, so the object contributes nothing.
-
-**At the blueprint** (`Blueprint("api", __name__, url_prefix=...)`):
-
-| Written | flask-restx serves | The reader says |
-| --- | --- | --- |
-| nothing | the rest of the path, no prefix | unstated |
-| `"/api/v1"` | `/api/v1` + the rest | stated |
-| `"/api/v1/"` | `/api/v1/` + the rest, and Werkzeug answers the merged `/api/v1/...` | stated, and the composed path is merged |
-| `"/"` | the rest of the path, once the merge collapses the doubled slash | stated, and merging leaves nothing |
-| `""`, `None` | the rest of the path, no prefix | unstated |
-| `False`, `0` | the app does not start: Flask hands the value straight to `rstrip` | unstated |
-| a name, a call, or an f-string the evaluator settles | whatever it evaluates to | stated, with the string it settles on |
-| anything the evaluator cannot settle | whatever it evaluates to | unreadable |
-
-**At the `Api`** (`Api(bp, prefix=...)`):
-
-| Written | flask-restx serves | The reader says |
-| --- | --- | --- |
-| nothing | the blueprint's prefix + the rest | unstated |
-| `"/extra"` | the blueprint's prefix + `/extra` + the rest | stated |
-| `"/extra/"` | the same, concatenated as written, and Werkzeug answers the merged path | stated, and the composed path is merged |
-| `""`, `None`, `False`, `0` | the blueprint's prefix + the rest | unstated |
-| a name, a call, or an f-string the evaluator settles | whatever it evaluates to | stated, with the string it settles on |
-| anything the evaluator cannot settle | whatever it evaluates to | unreadable |
-
-### A call that spreads a dictionary
-
-`Api(**build_authorizations())` and `include_router(router, **options)`
-spread a value the call does not write out. The reader skips the spread
-and reads the keywords that are written, so the routes underneath keep
-their paths.
-
-That leaves one thing it cannot see. If the dictionary sets the prefix
-keyword itself, the composed path is wrong, and nothing in the output
-says so. Reading the prefix as unknown instead would be correct and would
-cost every route under every call that spreads a config dictionary, which
-is most of them. Propagating the uncertainty rather than choosing between
-the two is the work that would settle this.
-
-**At the registration** (`app.register_blueprint(bp, ...)`), which the reader consults only to abstain:
-
-| Written | flask-restx serves | The reader says |
-| --- | --- | --- |
-| nothing | where the blueprint's own `url_prefix` put it | the reading stands |
-| `url_prefix="/over"` | `/over` + the rest, replacing the blueprint's | abstain |
-| `url_prefix=""` | the rest, replacing the blueprint's with nothing | abstain |
-| `url_prefix=None` | where the blueprint's own `url_prefix` put it | abstain |
-| registered on another blueprint | the outer blueprint's prefix in front of everything | abstain |
-| registered twice | flask-restx refuses to start | abstain |
-| never registered | nothing at all | the reading stands |
-
-Any spelling of `url_prefix` at the registration abstains, `None` included. The three that are written say different things (`"/over"` replaces, `""` replaces with nothing, `None` falls back to the blueprint's own), so a written keyword there says nothing on its own about where the routes land.
-
-A registration nobody wrote leaves the reading standing rather than abstaining. A blueprint the run never sees registered is one whose registration might sit in a file outside the run, and reading the prefix it was built with is the same claim the constructor already makes.
-
-### Repeated slashes
-
-A prefix written with a trailing slash leaves the composed path with two. Werkzeug answers such a rule at the merged path and redirects the written one, so `/api/v1//orders` is reached at `/api/v1/orders`; the pack says so, and the reader merges repeated slashes in every path it composes. Starlette does not do this, so FastAPI's pack says nothing and its paths stand as composed.
-
-## What a body lowers to
-
-A route ends where it returns and where it raises, and each of those places is
-what makes it produce more than one transition, so the adapter lowers a function
-body into the statement form the shared path engine in `@suss/extractor` walks.
-That engine is generic over the language's own condition handle and never looks
-inside one, so the enumeration, the negation of an earlier arm, and the budget
-are all shared with TypeScript.
-
-| Python | Lowers to |
-| --- | --- |
-| `if` / `elif` / `else` | one `if` per test, with the elif chain nested into the else arm the way Python reads it |
-| `while`, `for` | `loop` |
-| `try` / `except` / `finally` | `try`, with every except arm as the catch body |
-| `match` / `case` | `switch`, one group per case, `case _` as the default group |
-| `return`, `raise` | `exit`, which is what gives each of them its own transition |
-| `break`, `continue` | `exit`, which the engine uses for reachability rather than as an outcome |
-| anything else | `opaque` |
-
-A statement's exit kind comes from scanning its own subtree for a return or a
-raise, stopping at a nested `def` or `lambda`, because those belong to the
-function they declare. A raise anywhere beats a return anywhere.
-
-So a handler written this way:
-
-```python
-def get(self, order_id) -> dict:
-    if not found:
-        return {"error": "nope"}, 404
-    return {"a": 1}, 200
+```bash
+npm install --save-dev @suss/cli
 ```
 
-comes out as two transitions, the 404 gated on the opaque condition
-`not found` and the 200 gated on its negation, rather than as one claim with a
-guessed status.
-
-### A branch that ends by raising
-
-Most frameworks let a route end the request by raising rather than by
-returning, and the status the client receives is then whatever the raised
-call was given. A pack says which of its library's callables do that, under
-`responseStatusCalls`, and where each of them takes its status:
+The adapter ships inside the CLI, so there is nothing else to install.
 
-```ts
-responseStatusCalls: [
-  {
-    callee: "fastapi.HTTPException",
-    statusKeyword: "status_code",
-    statusArgument: 0,
-  },
-],
-```
-
-`callee` is the name as the file imports it, module and name together, which
-is what tells FastAPI's `HTTPException` apart from a project class of the same
-name. A `raise` of one of these becomes a transition responding with that
-status, and so does a bare call to one written as a statement of its own,
-which is how Flask's `abort(404)` ends a request. So this handler:
+## Read a FastAPI service
 
-```python
-@app.get("/items/{item_id}")
-def show(item_id: int):
-    if item_id > 10:
-        raise HTTPException(status_code=404, detail="missing")
-    return {"id": item_id}
+```bash
+npx suss extract --lang python -f fastapi -f sqlalchemy -f requests -o summaries/python.json
+npx suss check --dir summaries/
 ```
 
-comes out as a 404 under `item_id > 10` and a 200 under its negation.
+`suss init` reads your requirements file or pyproject and writes those two commands out for your own project.
 
-A status the reading cannot resolve to a number is reported as the text it was
-written as, so the transition says a status was set without claiming which. A
-`raise` of anything the pack does not list is still a transition, with the
-exception type on it and no status, since the framework is the only thing that
-knows what it turns that exception into.
+## What it reads
 
-### Keying anything on a node
+- FastAPI and flask-restx routes, including a decorator a project re-exports through a wrapper module, with `response_model` and `status_code` taken as the declared contract.
+- The path a route is served under, composed through `include_router` prefixes, however many mounts deep, including a mount written inside a function or spread out of a dictionary.
+- SQLAlchemy calls, `requests` / `httpx` / `aiohttp` call sites, what a file reads from the environment, and what a handler calls out to, as facts the checker's rules run over.
 
-tree-sitter hands back a fresh wrapper object every time a child is read, so
-two reads of one node are never `===` and a plain `Set` or `Map` keyed on a
-node matches nothing. Use `NodeSet` and `NodeMap`, which key on the node id.
-`npm run check:style` fails a build that keys either on a node.
+How each of those is decided, and where it stops: [how the Python adapter reads a project](./DESIGN.md).
 
-## What a body does with the database
+## Where it fits
 
-A pack says which query types its library defines, and a call chain matches
-when the method behind it says it returns one:
+It depends on `@suss/extractor`, `@suss/behavioral-ir`, `@suss/datalog` and `web-tree-sitter`. The `fastapi`, `flask-restx` and `sqlalchemy` packs consume its `PythonPack` contract, and nothing here knows what any particular library's decorators are called.
 
-```ts
-storage: [
-  {
-    module: "sqlalchemy.orm",
-    queryTypes: ["Query"],
-    writes: ["update", "delete", "add"],
-    storageSystem: "postgresql",
-  },
-]
-```
+`grammar/tree-sitter-python.wasm` is a checked-in binary, not a build output. [Where it comes from](./grammar/README.md).
 
-Matching on the return rather than on the import is what reads a project's own
-wrapper. A measured Flask service imports `sqlalchemy` in 50 files, and every
-one of its 157 queries still goes through a base class the call sites never
-import:
+## More
 
-```python
-# in the project, not in the library
-class Base:
-    @classmethod
-    def query(cls) -> Query: ...
-
-class Orders(Base): ...
-
-# in a handler, importing neither the base nor SQLAlchemy
-found = Orders.query().filter_by(id=1).first()
-```
-
-A recognizer keyed on the import finds none of that. Following the call to
-`Base.query` and reading what it says it returns finds all of it, and the
-inheritance hop comes from `contains`, which reads `holdsProperty` and adds
-what a base class declares.
-
-A chain is one thing the code does, so the three calls above are one read. The
-call that starts the chain is the one resolved, and the method the chain ends
-with tells a read from a write. A method a base and a subclass both declare
-gives two, and nothing is claimed.
-
-A chain also matches when the name it starts on is declared, where the chain
-is written, as one of the query types: a parameter annotated `db: Session`,
-a local bound by `session = Session()` or `with Session() as session:`, or a
-project function whose return annotation says `Session`. The type has to be
-imported from the pattern's module, so a project class that happens to share
-the name does not match. `recordsNothing` lists the methods on such a type
-that touch no rows of their own: `execute` runs a statement whose own chain is
-the read or write, and `close` manages the session.
-
-A query built from a function the library exports has no project method in
-between for its return to be read off, so a pack lists those by name and a call
-site importing one matches on that:
-
-```ts
-queryFunctions: ["select", "insert", "update", "delete"]
-```
-
-For one of these the function itself is the operation, so
-`update(User).where(...).values(...)` is an update however it ends.
-
-`fields` comes from the columns a query spells out, `User.id` in
-`select(User.id, User.email)`, and from the keywords of a call the pack lists
-under `valueMethods`, `name` in `.values(name="x")`. `selector` comes from
-the keywords every other call in the chain picks rows by, `id` in
-`filter_by(id=user_id)`. Raw SQL handed to `text` is read as its own effect,
-with the kind and table taken from the statement.
-
-## Where a mount is written
-
-Almost no service mounts anything at the top level of a module. It builds its routers or namespaces there, each with a literal prefix, and registers them inside the function that builds the app, often by looping over a list that another function put together:
-
-```python
-def create_app():
-    app = Flask(__name__)
-    api = Api(app)
-    for namespace in loader.load_namespaces():
-        api.add_namespace(namespace)
-    return app
-```
-
-So suss looks for mounts inside function bodies as well as at the top level. It still reads constructor calls at the top level only, which is where people write them. It does not see a mount inside an `if`, a `try`, a `with`, a `while`, or a class method, because the binder records no name written inside one of those, and a mount there would resolve to nothing anyway.
-
-A mount inside a `for` goes one of two ways, depending on whether the source says which routers the loop covers.
-
-| The loop reads | What suss does | Why |
-| --- | --- | --- |
-| a list or tuple of bare names, `for ns in [orders, users]` | mounts each of those names, exactly as a mount call that named it would | every element is a name the existing one-hop rule already follows |
-| anything else, `for ns in loader.load_namespaces()` | mounts nothing, and every router it never saw mounted by name explains that the loop is the reason | no file says which routers the call returns |
-
-Claiming a path off the second row would mean guessing twice at once: that this router is in the collection at all, and that the mount states no prefix that would replace or extend the router's own. A wrong path is worse than no path here, because a claimed path pairs the route with a contract on the other side, and every check downstream treats it as fact. Nothing tells those checks apart from a path suss followed all the way.
-
-What the second row does give you is a better explanation. A router nobody mounts by name used to say "is never mounted through a single variable binding in the files read", which sends a reader hunting for a registration that is sitting right there in the app factory. When suss saw a loop it could not enumerate, the reason says that instead, and the fix it points at (list the routers out in the source, or give suss the list) is the one that works.
-
-Both rows were checked against a running app. A loop over a literal list serves each namespace under its constructor path, the same paths the direct mounts serve. A `path=` written on the mount inside the loop replaces every namespace's own path, which is one more reason not to treat a loop's mount as an ordinary registration.
-
-### A mount inside a function runs only if the app calls that function
-
-A mount at a module's top level runs on import, so it is the mount. A mount inside a function is only a candidate, and suss has no idea which functions the app actually calls. A repo with a test factory next to the app factory is where that goes wrong:
-
-```python
-def create_test_app():
-    app = FastAPI()
-    app.include_router(router, prefix="/test")   # only tests call this
-    return app
-
-
-def create_app():
-    app = FastAPI()
-    for r in loader.load_routers():              # what production runs
-        app.include_router(r)
-    return app
-```
-
-Taking the only mount it could follow would put the route at `/test`, where no request ever arrives. So suss drops a mount written inside a function when it also saw a loop it could not enumerate somewhere other than that same function. The route abstains, and says both the function and the loop.
-
-Both of those qualifiers matter. Only counting loops keeps the ordinary case working: two factories that each register their own routers by name are not competing, because neither one could have registered the other's. Only counting a loop in a *different* place keeps a factory working when it mixes an explicit registration with a loop, since both of those run together whenever that function runs.
-
-A module-level mount is never dropped this way. It runs whichever factory the app calls.
-
-## What a file reads from the environment
-
-`os.environ` is part of the language's standard library, so the adapter recognizes reads of it itself, without a pack. Each read becomes the same `config-read` interaction the TypeScript adapter emits for `process.env.X`, on the binding `runtime-config`, spelled `os.environ["X"]` whichever way the source wrote it. The runtime-config checker pairs those against what a template declares for the function the file runs in.
-
-| Python | Recognized as | Defaulted |
-| --- | --- | --- |
-| `os.environ["X"]` | a read of `X` | no |
-| `os.environ.get("X")` | a read of `X` | no |
-| `os.environ.get("X", "d")`, `os.environ.get("X", default="d")` | a read of `X` | yes |
-| `os.getenv("X")`, `os.getenv("X", "d")` | a read of `X` | as above |
-| any of these followed by `or` (`os.environ.get("X") or "d"`) | a read of `X` | yes |
-| `import os as _os`, `from os import environ, getenv` | the same reads, through the alias | |
-| `os.environ[name]`, `os.environ.get(f"{prefix}_X")` | nothing: the name is not a literal | |
-| `os.environ["X"] = "1"`, `del os.environ["X"]`, `"X" in os.environ` | nothing: a write or a membership test | |
-| `os.environ.get("X") or os.environ.get("Y")` | `X` defaulted, `Y` not, since `Y` is the chain's last resort | |
-
-A read inside a route body goes on that route's summary. A read at module level, or in a class body, runs when the module is imported, so it goes on a `module-init` summary named after the file, one per file that has such a read. A read inside a function a route reaches through its calls goes on that function's own summary (see below). A read inside a function nothing discovered and nothing reaches is reported nowhere, because nothing says when that function runs.
-
-## What a route reaches
-
-A route's body calls project functions, and those call others. Each function a route reaches this way gets a summary of its own, of kind `library`, bound as `function-call` with `transport: "in-process"` and `recognition: "reachable"`, with the calls, environment reads and database work its own body does. Each invocation effect on a route or a reached function says which summary the call lands on, in `summary`, so a reader answering "what does this route reach" follows `summary` from one unit to the next and never has to match a name. This is the same walk the TypeScript adapter runs, and it produces the same shape.
-
-The walk starts at every discovered route, and adds a `calls` fact for each call in a body it could follow, until the set stops growing. A function two routes both reach gets one summary. A call the walk could not follow is recorded once per callee on the summary of the body it is in, as an `unfollowedCall` gap saying why, unless the reason is one nothing could have done better with (a call to a parameter that some caller passes a function by name into, or a call into a package that is not in the run).
-
-A callee is followed only through a binding that says where it came from. The binder's scopes settle a name written in the file; the import resolver settles a name brought in from another file in the run.
-
-| Written as | Followed to |
-| --- | --- |
-| `helper()` with `def helper` in the file | that definition |
-| `helper()` with `from pkg.mod import helper` | `helper` in `pkg/mod.py` |
-| `mod.helper()` with `import pkg.mod` or `from pkg import mod` | `helper` in `pkg/mod.py`, whether or not `pkg` has an `__init__.py` |
-| `run = helper` then `run()`, written straight in a body | `helper`, one alias hop |
-| `Handlers.on_get()` with `on_get = helper` in the class body | `helper` |
-| `self.method()` or `cls.method()` inside a method | the method on the enclosing class |
-| `Service().run()`, or `svc = Service()` then `svc.run()` | `run` on `Service` |
-| `Service()` | `Service.__init__` |
-| `helper()` with `from pkg.mod import *` and one module defining it | that definition |
-| a call written as an argument, or as the receiver of a chain | followed like any other, in the order it finishes |
-| a call inside a lambda | the enclosing function's call |
-| `inner()` with `def inner` nested in the body | `inner`, which gets a summary of its own with the calls its body makes |
-| `register(build_index)`, where `register(handler)` calls `handler()` | `build_index`, followed from wherever a caller in the run named it, through the parameter `register`'s own body calls |
-
-A function passed by name into a call is followed one hop further than the call itself. `register(build_index)` records where `build_index` is declared, keyed to its position among `register`'s arguments; `register`'s own body calling `handler()` records which of its parameters that call goes through. A reader asking what calls `build_index` finds `register`, and what `register` reaches includes `build_index`, even though the join crosses two separate calls. Only a bare name counts, so a lambda written inline and a variable bound to a function are both out of scope, the same as a callee written that way.
-
-Where it stops, and what the gap says:
-
-| Written as | Reason |
-| --- | --- |
-| a call on a parameter, `callback()`, that some caller in the run passes a function by name into | followed through the join above (no gap) |
-| a call on a parameter, `callback()`, that no caller in the run passes a function by name into | the caller supplies it, and nothing named what it passed |
-| a name a `for`, `with`, `except ... as`, walrus, or lambda parameter rebinds | the value could not be settled |
-| a name assigned inside an `if`, `try`, or `with` block, or by unpacking | the value could not be settled |
-| `from a import *` and `from b import *` when both define the name | more than one possible source |
-| an import that resolves under two roots | more than one possible source |
-| a call into a package whose source is not in the run | outside the run (no gap) |
-| a value's attribute, `order.save()`, or a call on a call's result | no declaration to follow (no gap) |
-
-One callee spelling that lands on two definitions in one body, `load()` under a class body that imports its own `load` say, is placed on neither.
-
-Not followed yet: a method inherited from a base class, a callable stored in a dict or a list, a decorator's own body, a call written in a parameter default such as `Depends(get_db)`, and an attribute set on `self` in `__init__` and called elsewhere.
-
-A summary's `identity.id` is the file relative to the project root plus the export path (`app/store.py::read_orders`, `app/models.py::Orders.total`), and `summary` on an effect is that id. Two summaries that would share an id are told apart by their boundary, then by their line.
-
-## What a file imports from the project
-
-Every summary has `metadata.moduleImports`, the project files its own file's imports resolved to, relative to the workspace root and sorted. A file whose imports all resolve outside the project gets an empty list rather than no field, so a Lambda handler that imports only the standard library still tells the checker that its closure is the handler module alone. A checker rebuilds the import graph from that field to work out which modules a template's handler entry loads; the entry `app.handler` under `CodeUri: src/` matches `src/app.py`, and a dotted module such as `shop.app.handler` matches `src/shop/app.py`.
-
-## Extraction cache
-
-This adapter uses the extraction cache shared across every language adapter, from `@suss/extractor`. It keeps the cache beside the project root, at `.suss/cache/`, and supplies the walked `.py` file list as the key's file set; it has no config file of its own to guard the entry the way the TypeScript adapter's tsconfig does. Reuse today is whole-run only: any file changing re-extracts the whole project instead of that one file. See the extractor package's README for the design.
-
-## Grammar asset
-
-`grammar/tree-sitter-python.wasm` is a checked-in binary asset, not a build output. See [`grammar/README.md`](./grammar/README.md) for its provenance and how to bump it.
-
-## Coverage
+- [Documentation](https://nimbuscloud-ai.github.io/suss/)
+- [Python and Ruby](https://nimbuscloud-ai.github.io/suss/guides/python-and-ruby)
+- [Every pack suss ships](https://nimbuscloud-ai.github.io/suss/reference/packages)
+- [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ![coverage](../../../.github/badges/coverage-python.svg)
 
-## License
-
-Licensed under Apache 2.0. See [LICENSE](../../../LICENSE).
+Apache 2.0. See [LICENSE](../../../LICENSE).