Effect catalog, pyright cross-check, and resolution fixes

[Raman369AI]

Summary

Three pieces, one commit each. They follow the resolver feasibility study, which recommended against delegating resolution to Jedi or pyright.

1. Resolution fixes (b775f43)

• Unannotated factories: a factory with no return annotation types its result when every non-None return constructs a class (return Repo(), or return build() that does). Async and generator factories don't.
• Aliases: a name assigned once from a function or attribute (alias = clean) resolves through that value as probably. Parameters, loop targets and reassigned names stay unknown.
• Parse errors name the Python that parsed the file. Below 3.14 they add: "if this file uses newer syntax, run Threadline with Python 3.14".

2. Pyright cross-check in CI (fdbb5f1)

• tests/pyright_crosscheck.py asks pyright's language server where a deterministic sample of calls goes.
• It fails if pyright names a different project function for any call Threadline marks supported. Pyright having no answer is not a failure.
• It reports, without failing, probably mismatches and calls pyright resolves where Threadline can't, as review leads.
• CI runs it on this repo (Linux, 3.12) and on flask and requests in the public-repository job.
• Pyright is pinned as a dev dependency beside axe-core; there's no runtime dependency.

3. Effect catalog (00a77aa)

• threadline/effects.py maps known library calls to effect classes, with reads and writes separate:

  Effect	Recognised
  DB read/write	SQLAlchemy/SQLModel sessions and DB-API cursors; execute is classified by its statement (select / insert, update, delete)
  Network read/write	requests, httpx, aiohttp, urllib, by HTTP verb
  File read/write	open (by mode), pathlib, os, shutil, json/pickle
  Process	subprocess, os.system, …
  Logging	logging, loguru, structlog
  Raises	raise statements

• Certainty: identified library targets are definite. Untyped session/db/logger receivers match by name and are possible.

• Propagation: effects travel through resolved project calls with their path. Probable or deferred calls (an unawaited coroutine, a generator) make them possible.

• Summary: the method summary gains an Effects row, e.g. "DB write via update_user". Raises also lists exceptions from called project functions.

  • Clicking a direct effect highlights its lines; clicking an inherited one opens the function it comes through.

• CLI: threadline method returns the records as effects.

• Supporting analyzer changes: external calls record their library target. with X() as y: and dotted library factories (logging.getLogger(__name__)) now type their receivers.

Example (agent-kanban-pm, POST /tasks): Effects DB write, DB read; Raises HTTPException, PermissionError via create_task_record, TaskReferenceError via create_task_record.

Gate

Each change landed its semantic-corpus cases first, with contrasting checks, and each case failed before its fix. A new effects check kind covers every library family plus propagation, including a function built from pure helpers and a recursive pair that must have no effects.

The corpus now has 73 checks, 0 incorrect supported.

Testing

• python -m pytest: 163 pass. python test_semantic_accuracy.py: 73 pass.
• tests/browser_smoke.py in all four modes: all pass, including new Effects-row checks.
• tests/browser_accessibility.py --browser chrome: all pass.
• tests/pyright_crosscheck.py --project . --repo flask --repo requests: 0 disagreements on 563 supported and 561 probably calls.
• tests/online_repo_smoke.py: all 7 pinned repositories pass.
• mypy (CI scope): passes.
• Effect pass on agent-kanban-pm: 0.04 s for 1,174 functions.

Limits (documented in docs/CAPABILITIES.md)

• Only catalogued libraries are recognised; Django's ORM isn't catalogued yet.
• A statement passed through a variable is DB access, with no direction.
• Effects describe source, not executed behaviour.

🤖 Generated with Claude Code