coretrace-python-analyzer 0.17.0__tar.gz → 0.19.0__tar.gz

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.19.0 (2026-09-29)
+
+### Analysis
+
+- Two files with the same Python module name, `a/app.py` and `z/app.py` outside any package, no longer overwrite each other: both are discovered, analysed and covered whatever the order they are found in. The engine tells them apart by their path from the root as a module name, `a.app` and `z.app`, in the module graph, the summary index, the cache keys and what project plugins see; a unique name stays what it was. An import of such a name resolves to the file in the importer's own root only, and one no root resolves is not followed. Each colliding file carries an `ambiguous-module` note and is covered as `ambiguous`, since a model or a route naming `python.app.main` applies to every definition of that symbol, and so does an importer whose import stayed unresolved; a VEX statement over such a project stays `under_investigation` (#182).
+
+### Precision
+
+- A `TEMPLATES` assigned inside a function or a class no longer counts as Django settings: only a module-level assignment can activate the `request` context processor, and only a mention of the module's `TEMPLATES` elsewhere leaves that activation uncertain. A function-local `TEMPLATES`, called or not, used to enable the implicit request source, upgrading a template filter finding to exploitable (#184).
+- A template block that renders `{{ block.super }}` keeps the parent block's content, so the filters the parent applies stay fed by the render context, with the parent template as the place of the call; a block without it still replaces the parent's whole block, and a chain of templates keeps exactly the parents each level renders. The parent's filters used to drop out of the exploitable flow as soon as a child defined the block (#185).
+- A project tag library registering a filter of a built-in's name replaces the built-in in every Django template loading it before applying the filter, as Django's parser does: `{% load custom %}{{ bio|striptags }}` calls the project's `striptags` when `app/templatetags/custom.py` registers one, so it is no longer a reachable or exploitable call to `django.template.defaultfilters.striptags`; the project's function is ordinary code, analysed as any other. A load affects only the filters after it, a later load overrides an earlier one, `{% load striptags from custom %}` replaces only what it names, and Django's own libraries change nothing. The analyzer reads the registrations on `register`, a `django.template.Library` however it is imported, in decorator and call form, at module level or under `if`, `try` or a function. Where it cannot tell what a library registers — no such library file, one it cannot read or parse, a name not written as a constant, `register` passed elsewhere or filled through `filters=` or `register.filters`, or two apps giving the name and registering different filters — a filter of that name applied under the load is neither the built-in nor certainly replaced: no call is claimed, and the load counts among the templates the analyzer could not read (`app/templates/app/profile.html:1 loads 'custom', not read`), so an advisory naming the filter stays `under_investigation` in the VEX document. The settings' `OPTIONS["libraries"]` and `OPTIONS["builtins"]` are not read (#183).
+
+### Plugins
+
+- `ModuleFunction.aliases` gives a project plugin the module-level names bound to a function by assigning one name to another, transitively and in source order, so an integration declaring a handler by the name a module binds (`handlers.main`) can report a name the engine resolves to no function; a method or a nested function has none. The cache format changes.
+- An `EntryPoint` naming a project function or class applies through a module-level alias of it: `main = actual` makes `python.app.handlers.main` name `actual`, so a deployment declaring `handlers.main` reaches the function doing the work. An alias is an assignment of one name to another at module level, followed transitively and in source order, in a conditional or a `try` as well; a name bound inside a function or class, or to a call, an import or anything but a name, is no alias, and the engine still infers nothing from a name. A model naming a method wins over one naming its class, whichever name it uses.
+
+## 0.18.0 (2026-09-28)
+
+### Precision
+
+- A Django template file the analyzer cannot read, because of its permissions, no longer counts as escaping everything it renders: it read the file as empty text, and an empty template escapes. The flow through `render_to_string` stays `xss`, and a template extending or including the unreadable one is not established to escape either, as for a template the analyzer cannot find. An unreadable file was already listed among the templates the project names but the run could not read.
+
+### Plugins
+
+- An `EntryPoint` may name a project function or class by its own symbol, `python.app.handlers.main`, so an integration reading a deployment declaration, a SAM template or a `serverless.yml`, can make a bare Lambda handler an entry point; the engine itself infers nothing from a function's name. `EntryPoint.inputs` limits the parameters that are input to the given positions, after `self` for a method: the handler's event, not its context (#180).
+
 ## 0.17.0 (2026-09-28)
 
 ### Plugins

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.17.0
+Version: 0.19.0
 Summary: Static security analysis infrastructure for Python code
 Project-URL: Homepage, https://github.com/CoreTrace/coretrace-python-analyzer
 Project-URL: Repository, https://github.com/CoreTrace/coretrace-python-analyzer

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/docs/plugins.md

@@ -53,7 +53,11 @@ resolved through imports and aliases, so `python.os.system` covers `os.system`,
 symbol, so a chain such as `sqlite3.connect(p).cursor().execute` is
 `python.sqlite3.connect.cursor.execute`, and `app = Flask(__name__)` gives `app.route` the
 symbol `python.flask.Flask.route`. Builtins are `python.builtins.<name>`. Symbols are
-`SymbolId` values from `coretrace_python.semantic.symbols`.
+`SymbolId` values from `coretrace_python.semantic.symbols`. A function of the project is
+`python.` followed by its module's import name and its qualified name,
+`python.app.handlers.main`; two files with the same import name, `a/app.py` and
+`z/app.py` outside any package, define the same symbols, so a model naming
+`python.app.main` names the function of each.
 
 ## Kinds of plugin
 
@@ -151,7 +155,7 @@ class BottleModels(ModelPlugin):
 | `Source(symbol, label, kinds=ALL)` | A call or attribute whose value is attacker-controlled; `label` names it in messages (`http`, `stdin`, `argv`, `http-response`). `kinds` restricts what it can inject. Text input, such as a form field, a header or a URL parameter, carries `TEXT_KINDS`, every kind but `NOSQL`: a string cannot hold a query operator. |
 | `Sink(symbol, kinds, positions=(), keywords=())` | A call dangerous for `kinds`. `positions` limits a kind to the given argument indexes, and `keywords` to the given keyword names; a restricted kind reaches only the arguments listed there. SQL sinks read the statement only, and the SSRF sinks of HTTP clients read the URL, by position or as `url=`. A starred argument or `**kwargs` reaches no restricted kind. |
 | `Sanitizer(symbol, kinds)` | A call whose result is safe for `kinds`, including when the call is inside a project function the data goes through. |
-| `EntryPoint(symbol, label, kinds=ALL)` | A decorator or a class base whose functions receive their parameters as `label` input, such as `flask.Flask.route`. |
+| `EntryPoint(symbol, label, kinds=ALL, inputs=None)` | A decorator or a class base whose functions receive their parameters as `label` input, such as `flask.Flask.route`; or a project function or class named by its own symbol (`python.app.handlers.main`), as an integration reading a deployment declaration names a Lambda handler. `inputs` limits the parameters that are input to those positions, after `self` for a method: a handler's event, not its context. |
 | `TypedParameter(symbol, label, kinds=ALL)` | A class whose annotated parameters carry `label` input, such as Django's `HttpRequest`. |
 | `NamedParameter(pattern, label, kinds)` | A regular expression on parameter names; matching parameters carry `kinds`, as `password` carries `CREDENTIAL`. |
 | `BasePattern(pattern, label, parameters=(None,), kinds=ALL)` | A regular expression on the canonical symbol of a class's base, for bases generated per project such as a gRPC servicer's (`(?:^|\.)\w+_pb2_grpc\.\w+Servicer$`), whatever the module's prefix and however the base is imported. The methods taking the parameters listed, by position after `self`, are entry points: a position left `None` is `label` input carrying `kinds`; one holding a class symbol denotes an object of that class, which the sources on the class taint, as `invocation_metadata()` on a `ServicerContext`, without the object itself being input. When the project holds the base, only the methods the base defines count; otherwise every method with that number of parameters. Inheritance identifies a potential service, not its registration on a server. |
@@ -255,14 +259,19 @@ module graph, the dependency graph, every advisory the plugins and advisory file
 contributed, the policy, the project root, and each module's imports, call graph and
 functions. `ctx.functions(module)` gives every function as the call graph names it
 (`Admin.get`, `outer.inner`, `<module>`), with its span, so a finding can be placed in
-one, and the label of the entry point it is (`http` for a route, `argv` for a command)
-when the models make it one. `ctx.call_graph(module)` gives each function's call sites
+one, the label of the entry point it is (`http` for a route, `argv` for a command)
+when the models make it one, and its `aliases`, the module-level names bound to it by
+assigning one name to another (`main = actual`), transitively and in source order, so
+an integration declaring a handler by the name a module binds can tell a name the
+engine resolves to no function; a method or a nested function has none. `ctx.call_graph(module)` gives each function's call sites
 (`sites(function)`) and the symbols it reads, called or not (`reads(function)`: reading
 `request.form['name']` reads `python.flask.request.form`), each where it first reads it.
 `ctx.templates` gives the templates found under the project's `templates` directories:
-their `names`, the filters they apply as `calls` (each a `FilterCall(symbol, span)`, the
-function behind the filter and where the template applies it), and where they name a
-template the analyzer cannot read (`unread`).
+their `names`, the filters of Django's own libraries they apply as `calls` (each a
+`FilterCall(symbol, span)`, the function behind the filter and where the template
+applies it; a filter a project tag library the template loads replaces is no call),
+and where they name a template the analyzer cannot read, or load a library it cannot
+read while applying a filter of that library's name (`unread`).
 The shipped `vulnerable-dependency`, `reachable-vulnerability` and `dependency-policy`
 plugins are of this kind.
 

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/docs/usage.md

@@ -65,7 +65,13 @@ coretrace-python-analyzer [--check | --emit-ir [--ssa]] [options] [path]
 ## What is analysed
 
 Given a directory, every `.py` file below it is a module of one project, named after
-its package (`app/views.py` is `app.views`). Hidden directories, `node_modules`,
+its package (`app/views.py` is `app.views`). Two files that would share a name, `a/app.py`
+and `z/app.py` outside any package, are told apart by their path from the root, `a.app`
+and `z.app`, and reported: each carries an `ambiguous-module` note, since a symbol
+`python.app.main` may name a function of either and an import of `app` resolves only
+from the importer's own directory, and each is covered as `ambiguous` rather than
+analysed. An import of such a name that no file of the importer's own directory answers
+is noted where it is written and not followed. Hidden directories, `node_modules`,
 `__pycache__`, `build`, `dist` and any virtual environment, recognised by its
 `pyvenv.cfg` whatever its name, are skipped. Dependency files at the root
 (`requirements*.txt`, `pyproject.toml`, `poetry.lock`, `uv.lock`) are read into a
@@ -156,9 +162,9 @@ It establishes escaping only when all of the following hold:
 - No Python file of the project sets `autoescape` to `False`.
 
 The analyzer never assumes escaping where it cannot read the template. That covers a
-template named by an expression, a template found through a `DIRS` entry not named
-`templates`, one shipped by an installed package, one rendered through `get_template`,
-and Flask's Jinja2 templates. The flow is then reported as before. A single-file check
+template file it cannot read, a template named by an expression, a template found
+through a `DIRS` entry not named `templates`, one shipped by an installed package, one
+rendered through `get_template`, and Flask's Jinja2 templates. The flow is then reported as before. A single-file check
 reads no template.
 
 ### Dangerous API usage
@@ -241,7 +247,7 @@ the directory of the checked file; a path outside it is printed as it is.
 ```json
 {
   "schema_version": 1,
-  "tool": {"name": "coretrace-python-analyzer", "version": "0.17.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.19.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -261,7 +267,9 @@ the directory of the checked file; a path outside it is printed as it is.
 }
 ```
 
-`root` is the directory the paths are relative to.
+`root` is the directory the paths are relative to. A file's `status` is `analysed`,
+`ambiguous` (analysed, but another file has its module name, see above), `syntax-error`
+or `unreadable`; only `analysed` files count in `files_analysed`.
 
 A directory check also lists, in `tool.components`, what the result was produced with
 besides the engine and the sources: each plugin it loaded, by manifest name and version,
@@ -273,7 +281,7 @@ bytes. A single-file check lists no components.
 
 ```json
 "tool": {
-  "name": "coretrace-python-analyzer", "version": "0.17.0",
+  "name": "coretrace-python-analyzer", "version": "0.19.0",
   "components": [
     {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
     {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
@@ -372,6 +380,28 @@ Django. Most filters are functions of the same name in `django.template.defaultf
 are `<name>_filter` there, and the filters of `i18n`, `l10n`, `tz` and `humanize` are in
 their library's module (`timezone` is `django.templatetags.tz.do_timezone`).
 
+A project tag library, a module of a `templatetags` directory, that registers a filter
+of that name replaces the built-in in every template loading it, as Django's parser
+does: `{% load custom %}{{ bio|striptags }}` calls the project's function when
+`custom.py` registers a `striptags` filter, which is no call to the built-in; the
+project's function is ordinary code, whose own calls are analysed as any other. A
+load affects only the filters applied after it in the file, a later load overrides an
+earlier one, `{% load striptags from custom %}` replaces only the filters it names, and
+Django's own libraries (`static`, `i18n`, `l10n`, `tz`, `cache`, `humanize`) change
+nothing. The analyzer reads the registrations on the library's `register`, a
+`django.template.Library` however it is imported: `@register.filter`,
+`@register.filter("name")`, `@register.filter(name="name", is_safe=True)`,
+`register.filter("name", function)` and `register.filter(function)`, at module level or
+under `if`, `try` or a function. Where it cannot tell what a library registers, the
+filter is neither the built-in nor certainly replaced: a library found in no
+`templatetags` directory (one an installed package ships, or that the settings'
+`OPTIONS["libraries"]` or `OPTIONS["builtins"]` name, which are not read), a file it
+cannot read or parse, a name given by a variable or unpacked arguments, `register`
+passed to another function, filled through `filters=` or `register.filters`, or bound
+to anything but a `Library`, or two apps giving the same library name and registering
+different filters. The analyzer then claims no call, and counts the template among those
+it could not read (below) when a filter of the library's name is applied under the load.
+
 Attacker input in the render context makes the filter exploitable at the render call:
 `render(request, "app/profile.html", {"bio": request.POST["bio"]})` with
 `{{ bio|striptags }}`. The analyzer links a context value to a filter only where it is
@@ -386,7 +416,8 @@ certain of it:
   arguments of the filters before it, or the output of a `{% filter %}` block. A name a
   tag binds shadows the context, and `{% include ... only %}` passes none of it.
 - The filter renders: a template extending another renders only its blocks, which
-  replace the blocks of that name in what it extends.
+  replace the blocks of that name in what it extends, unless the block renders
+  `{{ block.super }}`, which keeps the parent's content and the filters it applies.
 - One file has the template's name; of two files of the same name, which one renders
   depends on the loaders.
 
@@ -399,9 +430,12 @@ With the `django.template.context_processors.request` context processor, a templ
 rendered with the request reads it as `request`: `{{ request.GET.q|striptags }}` is
 exploitable at the render call too. The analyzer counts it only where all of these hold:
 
-- The project's settings assign `TEMPLATES` a literal list, every `DjangoTemplates`
-  engine of it lists the processor in a literal `context_processors`, and no other code
-  of the project names `TEMPLATES`. A mere mention of the processor proves nothing.
+- The project's settings assign `TEMPLATES` a literal list at module level, every
+  `DjangoTemplates` engine of it lists the processor in a literal `context_processors`,
+  and no other code of the project names the module's `TEMPLATES`, or a `TEMPLATES` it
+  does not bind, as a star import gives. A `TEMPLATES` bound in a function or a class
+  is another name: it configures nothing and changes nothing.
+  A mere mention of the processor proves nothing.
 - The render call passes the request: `render` and `TemplateResponse` always do,
   `render_to_string` when given `request`, `SimpleTemplateResponse` never.
 - The render's context is certain, absent or a dict literal as above, so it cannot hide
@@ -502,10 +536,14 @@ A template the analyzer cannot read may apply any filter. The project names one
 `render`, `render_to_string`, `TemplateResponse`, an `{% include %}` or an `{% extends %}`
 names a template by an expression, or by a name found under no `templates` directory,
 including one an installed package ships; a template file that cannot be read counts
-too. An advisory whose entry points include a template filter then stays
-`under_investigation`, and the notes list where the project names each such template
-(`app.views:12 names a template by an expression`). A template named elsewhere, such as
-a class-based view's `template_name`, is not checked.
+too, and so does a template loading a tag library the analyzer cannot read, or find,
+or finds in several apps registering different filters, where it then applies a filter
+of a built-in's name, since the library may replace it. An advisory whose entry points
+include a template filter then stays `under_investigation`, and the notes list where
+the project names each such template (`app.views:12 names a template by an
+expression`, `app/templates/app/profile.html:1 loads 'crispy_forms_tags', not found`).
+A template named elsewhere, such as a class-based view's `template_name`, is not
+checked.
 
 `not_affected` needs the lock-file check because the analyzer reads the project's code,
 not the code of installed packages. A framework calling the vulnerable function on the
@@ -513,7 +551,7 @@ project's behalf would go unseen. Without a lock file, a package is never
 `not_affected`. The document's `@id` derives from its statements, so two runs with the
 same result share it; its `author` is `Unknown Author`, as OpenVEX tools write when they
 cannot know it. Its `tooling` names the analyzer and each component with its digest
-(`coretrace-python-analyzer 0.17.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+(`coretrace-python-analyzer 0.19.0; curated-advisories 2026.09.25 (sha256:…)`), so the
 `@id` changes with the advisory data a statement was decided with.
 
 ## Large projects

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coretrace-python-analyzer"
-version = "0.17.0"
+version = "0.19.0"
 description = "Static security analysis infrastructure for Python code"
 readme = "README.md"
 requires-python = ">=3.11"

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/src/coretrace_python/__init__.py

@@ -1,4 +1,4 @@
 """CoreTrace's Python static analysis frontend."""
 
-__version__ = "0.17.0"
+__version__ = "0.19.0"
 

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/src/coretrace_python/cache.py

@@ -42,7 +42,7 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import SourceId, SourceSpan
 
-CACHE_FORMAT = 10
+CACHE_FORMAT = 11
 
 
 @dataclass(frozen=True)
@@ -134,7 +134,7 @@ class ProjectCache:
 def encode(module: CachedModule) -> dict[str, Any]:
     return {
         "format": CACHE_FORMAT,
-        "functions": [[f.name, _encode_span(f.span), f.entry_point] for f in module.functions],
+        "functions": [[f.name, _encode_span(f.span), f.entry_point, list(f.aliases)] for f in module.functions],
         "summaries": {name: _encode_summary(s) for name, s in module.summaries.items()},
         "sites": [_encode_site(site) for site in module.sites],
         "findings": [_encode_finding(finding) for finding in module.findings],
@@ -196,8 +196,13 @@ def _decode_span(data: Any) -> SourceSpan:
 
 
 def _decode_function(data: Any) -> ModuleFunction:
-    name, span, entry_point = data
-    return ModuleFunction(_string(name), _decode_span(span), None if entry_point is None else _string(entry_point))
+    name, span, entry_point, aliases = data
+    return ModuleFunction(
+        _string(name),
+        _decode_span(span),
+        None if entry_point is None else _string(entry_point),
+        tuple(_string(alias) for alias in aliases),
+    )
 
 
 def _decode_read(data: Any) -> SymbolRead:

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/src/coretrace_python/engine.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import concurrent.futures
 import hashlib
 import multiprocessing
+from collections import Counter
 from collections.abc import Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -88,6 +89,7 @@ from coretrace_python.interprocedural import (
     TemplateCallsAnalysis,
     build_module_graph,
     discover_sources,
+    name_modules,
     project_symbol,
 )
 from coretrace_python.ir import PYIR_SCHEMA_VERSION
@@ -371,7 +373,11 @@ def analyze_project(
     strongly connected components of the module graph, imports first; with ``jobs``
     above one the components of a wave are analysed in that many processes (§29).
     ``advisory_files`` add to the ``advisories.json`` at ``root``; ``policy_file``
-    replaces the ``coretrace-policy.toml`` there."""
+    replaces the ``coretrace-policy.toml`` there.
+
+    Every module is known by the name ``name_modules`` gives its file: its import name,
+    or its path from the root when another file has that import name. Such files carry
+    an ``ambiguous-module`` note and are covered as ``ambiguous``."""
 
     if jobs < 1:
         raise ValueError("jobs must be at least 1")
@@ -398,18 +404,18 @@ def analyze_project(
     files: dict[str, SourceFile] = {}
     unreadable: list[tuple[Path, str]] = []
     coverage: list[FileCoverage] = []
-    discovered = discover_sources(root, sources, unreadable)
+    named = name_modules(root, discover_sources(root, sources, unreadable))
     for path, reason in unreadable:
         findings.append(_note("syntax-error", f"{path}: {reason}", sources.add_source(str(path), ""), 1))
         coverage.append(FileCoverage(str(path), "unreadable", 0, 0))
-    for source in discovered:
+    for name, source in named.items():
         try:
-            modules[source.module_name] = build_hir(source)
+            modules[name] = build_hir(source)
         except (ParseError, HIRBuildError) as error:
             findings.append(_note("syntax-error", str(error), source, 1))
             coverage.append(FileCoverage(str(source.source_id), "syntax-error", 0, 0))
             continue
-        files[source.module_name] = source
+        files[name] = source
 
     managers = {name: _register_all(module) for name, module in modules.items()}
     probe = next(iter(managers.values()), None) or _register_all(build_hir(sources.add_source("<empty>", "")))
@@ -439,6 +445,8 @@ def analyze_project(
     graph = build_module_graph(
         {name: files[name] for name in analysable}, {name: modules[name] for name in analysable}, imports
     )
+    shared = _shared_names(graph)
+    findings.extend(_ambiguity_notes(graph, shared, root))
     routes: dict[SymbolId, EntryPoint] = {}
     for name in sorted(analysable):
         for symbol, registered in _routes_of(analysable[name]).items():
@@ -447,7 +455,8 @@ def analyze_project(
     templates = project_templates(root)
     clearing = models.clearing(escaped)
     template_calls = models.template_calls(
-        templates.filters, request_processor(modules[name] for name in sorted(analysable))
+        templates.filters,
+        request_processor((modules[name], analysable[name].get(ScopeAnalysis)) for name in sorted(analysable)),
     )
     for manager in analysable.values():
         manager.provide(RegisteredRoutes, routes)
@@ -514,15 +523,16 @@ def analyze_project(
         if pool is not None:
             pool.shutdown()
 
-    index = _seed(results, graph, frozenset())
+    index = _index(results, {name: name for name in results})
     call_graphs: dict[str, CallGraph] = {}
     functions: dict[str, tuple[ModuleFunction, ...]] = {}
     for name in sorted(analysable):
         entry = results[name]
         findings.extend(entry.findings)
         unsupported = sum(1 for f in entry.findings if f.rule_id == "unsupported-syntax")
+        status = "ambiguous" if files[name].module_name in shared else "analysed"
         coverage.append(
-            FileCoverage(str(files[name].source_id), "analysed", len(entry.functions), len(entry.functions) - unsupported)
+            FileCoverage(str(files[name].source_id), status, len(entry.functions), len(entry.functions) - unsupported)
         )
         functions[name] = entry.functions
         sites: dict[str, list[CallSite]] = {function.name: [] for function in entry.functions}
@@ -644,24 +654,76 @@ def _advisory_paths(root: Path, advisory_files: Sequence[Path]) -> tuple[Path, .
     return (*([default] if default.is_file() else []), *advisory_files)
 
 
+def _shared_names(graph: ModuleGraph) -> dict[str, list[str]]:
+    """The import names several analysable files have, each with those files' modules."""
+
+    by_name: dict[str, list[str]] = {}
+    for name in graph.modules:
+        by_name.setdefault(graph.source(name).module_name, []).append(name)
+    return {import_name: names for import_name, names in by_name.items() if len(names) > 1}
+
+
+def _ambiguity_notes(graph: ModuleGraph, shared: Mapping[str, list[str]], root: Path) -> list[Finding]:
+    """One note on each file whose import name another file shares, since a symbol of
+    that name may denote a function of either, and one on each importer whose import of
+    such a name no root resolved, since calls through it are not followed."""
+
+    def located(name: str) -> str:
+        return _located(_path_of(graph.source(name)), root)
+
+    notes: list[Finding] = []
+    for import_name, names in sorted(shared.items()):
+        for name in names:
+            others = ", ".join(located(other) for other in names if other != name)
+            message = (
+                f"{located(name)} is the module '{import_name}' like {others}: a symbol "
+                f"python.{import_name}.* may name a function of either, and an import of "
+                f"'{import_name}' resolves only from its own root"
+            )
+            notes.append(_note("ambiguous-module", message, graph.source(name), 1))
+    for name in graph.modules:
+        for import_name in sorted(graph.unresolved(name)):
+            candidates = " or ".join(located(other) for other in shared[import_name])
+            message = f"'{import_name}' imported here is {candidates}: calls into it are not followed"
+            notes.append(_note("ambiguous-module", message, graph.source(name), 1))
+    return notes
+
+
 def _seed(results: Mapping[str, CachedModule], graph: ModuleGraph, component: frozenset[str]) -> SummaryIndex:
     """The summaries a component starts from: those of every module it imports,
-    transitively, all final by the time its wave runs; the whole index for no component."""
-
-    if component:
-        wanted: set[str] = set()
-        pending = list(component)
-        while pending:
-            for imported in graph.imports(pending.pop()):
-                if imported in results and imported not in wanted:
-                    wanted.add(imported)
-                    pending.append(imported)
-    else:
-        wanted = set(results)
+    transitively, all final by the time its wave runs, each under the import name the
+    component's code refers to it by. Of several files with one import name, only the
+    one a member imports directly, resolved in its own root, goes under that name: the
+    others are reached through summaries that inline them already, and a name no
+    member's root resolved is followed into neither file."""
+
+    wanted: set[str] = set()
+    pending = list(component)
+    while pending:
+        for imported in graph.imports(pending.pop()):
+            if imported in results and imported not in wanted:
+                wanted.add(imported)
+                pending.append(imported)
+    direct = {imported for member in component for imported in graph.imports(member)}
+    by_import: dict[str, list[str]] = {}
+    for name in wanted:
+        by_import.setdefault(graph.source(name).module_name, []).append(name)
+    names: dict[str, str] = {}
+    for import_name, modules in by_import.items():
+        chosen = modules if len(modules) == 1 else [name for name in modules if name in direct]
+        if len(chosen) == 1:
+            names[chosen[0]] = import_name
+    return _index(results, names)
+
+
+def _index(results: Mapping[str, CachedModule], names: Mapping[str, str]) -> SummaryIndex:
+    """The summaries of the modules in ``names``, each function under the project symbol
+    of the module name given for its module."""
+
     return SummaryIndex(
         {
-            project_symbol(name, function): summary
-            for name in sorted(wanted)
+            project_symbol(module, function): summary
+            for name, module in sorted(names.items())
             for function, summary in results[name].summaries.items()
         }
     )
@@ -674,8 +736,12 @@ def _analyse_managers(
     affected: Affected,
 ) -> dict[str, CachedModule]:
     """Analyse one component: iterate its summaries to a fixpoint over ``seed`` (§21),
-    then extract what the rest of the run needs from each module."""
+    then extract what the rest of the run needs from each module. Each member registers
+    its functions under its import name, what the others' code refers to it by; a name
+    two members share, a cycle across roots, is registered by neither."""
 
+    counts = Counter(manager.module.name for manager in managers.values())
+    names = {name: manager.module.name for name, manager in managers.items() if counts[manager.module.name] == 1}
     index = seed
     for manager in managers.values():
         manager.provide(ProjectSummaries, index)
@@ -684,9 +750,9 @@ def _analyse_managers(
             {
                 **seed.summaries,
                 **{
-                    project_symbol(name, function): summary
-                    for name, manager in managers.items()
-                    for function, summary in _summaries_of(manager).items()
+                    project_symbol(module, function): summary
+                    for name, module in names.items()
+                    for function, summary in _summaries_of(managers[name]).items()
                 },
             }
         )
@@ -701,8 +767,9 @@ def _analyse_managers(
 
 @dataclass(frozen=True)
 class _Batch:
-    """One component handed to a worker process: it rebuilds the configuration from the
-    project root and the plugin roots, so only paths and the imported summaries travel."""
+    """One component handed to a worker process, its files under the engine's module
+    names: it rebuilds the configuration from the project root and the plugin roots, so
+    only paths and the imported summaries travel."""
 
     root: Path
     plugin_roots: tuple[Path, ...]

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/src/coretrace_python/findings/coverage.py

@@ -1,10 +1,12 @@
 """Analysis coverage: which files and functions a run actually looked at.
 
 "No findings" only means something when the reader knows what was analysed. Each file
-is ``analysed``, a ``syntax-error`` (the frontend rejected it) or ``unreadable`` (it could
-not be decoded); analysed files count their functions and how many lowered. The
-templates the project names but the run could not read are listed, each where the
-project names it: they may call any template filter.
+is ``analysed``, ``ambiguous`` (analysed, but another file has its Python module name,
+so a symbol of that name may denote a function of either and an import of it resolves
+only from its own root), a ``syntax-error`` (the frontend rejected it) or ``unreadable``
+(it could not be decoded); analysed and ambiguous files count their functions and how
+many lowered. The templates the project names but the run could not read are listed,
+each where the project names it: they may call any template filter.
 """
 
 from __future__ import annotations

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/src/coretrace_python/interprocedural/__init__.py

@@ -19,6 +19,7 @@ from coretrace_python.interprocedural.modulegraph import (
     build_module_graph,
     discover_files,
     discover_sources,
+    name_modules,
     project_symbol,
 )
 from coretrace_python.interprocedural.summaries import (
@@ -73,5 +74,6 @@ __all__ = [
     "cleared_by",
     "discover_files",
     "discover_sources",
+    "name_modules",
     "project_symbol",
 ]

{coretrace_python_analyzer-0.17.0 → coretrace_python_analyzer-0.19.0}/src/coretrace_python/interprocedural/callgraph.py

@@ -132,12 +132,16 @@ class SignaturesAnalysis(Analysis[tuple[Signature, ...]]):
 @dataclass(frozen=True)
 class ModuleFunction:
     """One function of a module as a project plugin sees it: the name the call graph
-    gives it (``Class.method``, ``outer.inner``, ``<module>``), where it is, and the label
-    of the entry point it is (``http`` for a route, ``argv`` for a command), if any."""
+    gives it (``Class.method``, ``outer.inner``, ``<module>``), where it is, the label
+    of the entry point it is (``http`` for a route, ``argv`` for a command), if any, and
+    the module-level ``aliases`` bound to it by assigning one name to another
+    (``main = actual``), transitively and in source order; a method or a nested
+    function has none."""
 
     name: str
     span: SourceSpan
     entry_point: str | None = None
+    aliases: tuple[str, ...] = ()
 
 
 class CallGraph: