Unified: Add folder-based fallback for static name resolution - #22370
Draft
asgerf wants to merge 11 commits into
Draft
Unified: Add folder-based fallback for static name resolution#22370asgerf wants to merge 11 commits into
asgerf wants to merge 11 commits into
Conversation
asgerf
force-pushed
the
unified/folder-fallback
branch
from
August 18, 2026 08:10
01d2ec1 to
60dd3ba
Compare
asgerf
force-pushed
the
unified/folder-fallback
branch
4 times, most recently
from
August 20, 2026 07:46
26940cf to
252d8cd
Compare
The spurious result is offered by the folder-based heuristic, but would have been blocked by proper shadowing support.
Inheritance and access to nested classes is one of the reasons not to apply the heuristic as a "fixup" after the recursive layer, because when a base class is resolved through the folder heuristic, access to nested members still need to be resolved through the standard logic.
asgerf
force-pushed
the
unified/folder-fallback
branch
from
August 20, 2026 11:23
252d8cd to
b6741aa
Compare
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| } | ||
|
|
||
| module EntityReportStats<EntityStatsSig Input> { | ||
| private import Input |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds folder-based fallback name resolution for Swift files without package manifests, plus analysis-quality telemetry.
Changes:
- Adds folder-proximity-based static name binding.
- Adds resolution and manifest-coverage diagnostics.
- Adds tests for unique and ambiguous cross-file names.
Show a summary per file
| File | Description |
|---|---|
unified/ql/lib/codeql/unified/internal/StaticNameBinding.qll |
Implements folder-based name resolution. |
unified/ql/lib/codeql/unified/internal/AnalysisQuality.qll |
Defines reusable quality statistics. |
shared/util/codeql/util/ReportStats.qll |
Adds entity-based statistics reporting. |
unified/ql/src/diagnostic/StaticNameResolution.ql |
Reports resolved static names. |
unified/ql/src/diagnostic/FilesCoveredByModuleManifest.ql |
Reports manifest-covered files. |
unified/ql/src/diagnostic/ExtractorInformation.ql |
Exposes statistics as telemetry. |
unified/ql/test/library-tests/static-name-binding/unqualified-access.swift |
Records a heuristic false positive. |
unified/ql/test/library-tests/static-name-binding/not-a-package/SiblingFiles/Use.swift |
Tests sibling-file resolution and ambiguity. |
unified/ql/test/library-tests/static-name-binding/not-a-package/SiblingFiles/Def1.swift |
Adds sibling declarations. |
unified/ql/test/library-tests/static-name-binding/not-a-package/SiblingFiles/Def2.swift |
Adds competing sibling declarations. |
unified/ql/test/library-tests/static-name-binding/not-a-package/SiblingFiles/SubFolder1/Def.swift |
Adds nested declarations. |
unified/ql/test/library-tests/static-name-binding/not-a-package/SiblingFiles/SubFolder2/Def.swift |
Adds competing nested declarations. |
unified/ql/test/library-tests/static-name-binding/not-a-package/Main/Runner.swift |
Tests proximity in the Main tree. |
unified/ql/test/library-tests/static-name-binding/not-a-package/Main/Util/Util.swift |
Tests nested Main resolution. |
unified/ql/test/library-tests/static-name-binding/not-a-package/Main/Drivers/Driver.swift |
Defines Main-specific targets. |
unified/ql/test/library-tests/static-name-binding/not-a-package/Mock/Runner.swift |
Tests proximity in the Mock tree. |
unified/ql/test/library-tests/static-name-binding/not-a-package/Mock/Util/Util.swift |
Tests nested Mock resolution. |
unified/ql/test/library-tests/static-name-binding/not-a-package/Mock/Drivers/Driver.swift |
Defines Mock-specific targets. |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 18/18 changed files
- Comments generated: 2
- Review effort level: Balanced
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Static name resolution relies on
Package.swiftmanifests to indicate how files are linked up. However, it seems only about 50% of real-world projects use such manifest files. In the absence of a known manifest file, we had no way of linking up names across files.This PR adds a generic fallback mechanism for files that are not covered by a known manifest. An unqualified name
X, appearing in a file without a known manifest, may now resolve to any (exported) top-level declarationX. If multiple such declarations exist, we prioritise the one "closest" in the file hierarchy, meaning the one with the lowest common ancestor in the folder tree.If two definitions are tied for being closest, none is resolved as the target. Some more real-world examples of this would help motivate what to do here.
Evaluation
The PR also adds meta and metric queries for measuring the success rate of static name binding (first commit). I wanted to make sure the meta queries and metric query stay in sync, so they now share code through
AnalysisQuality.qll.Note that the percentage of statically resolvable names is currently not very useful because 100% is not an attainable number due to dependencies not being extracted. A lower number is not necessarily bad, because MaD models can still be evaluated by stepping through the name-binding graph directly. With that said, resolution rate, averaged over all projects, increases from 31% to 37%. An increase is always good, though it doesn't count as a "success rate".
See the DCA report for more concrete stats.