Unified: Add folder-based fallback for static name resolution - #22370
Merged
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
Contributor
Author
Rerun has been triggered: 4 restarted 🚀 |
hvitved
reviewed
Aug 21, 2026
| // currently blocked on getting static name binding to report this information. | ||
| } | ||
|
|
||
| NameBindingNode getTarget() { |
Contributor
There was a problem hiding this comment.
Ultimately, I guess we will want to expose this in the facade AST?
Contributor
Author
There was a problem hiding this comment.
Something like this I guess, though I'm still not sure if the name-binding node should be kept internal to the name-binding passes, or if we should interface with it downstream.
Contributor
There was a problem hiding this comment.
Yes, I think we will want to keep NameBindingNode internal (like ItemNode in Rust).
| } | ||
|
|
||
| /** | ||
| * Holds if `file` has a one of the definitions of the given ambiguous name. |
| * Holds if `folder` has two or more subfolders containing a definition of `name`. | ||
| */ | ||
| private predicate hasConflictingDefs(Folder folder, string name) { | ||
| containsDef(folder, name) and |
Contributor
There was a problem hiding this comment.
Is this line needed for performance?
Contributor
Author
There was a problem hiding this comment.
No, this was not actually needed anymore, after the second line was added. Removing the redundant line.
| result = folder | ||
| or | ||
| result = getOutermostNonConflictingScope(folder.getParentContainer(), name) and | ||
| not isOutermostNonConflictingScope(folder, name) and |
| private module FolderHeuristic { | ||
| private predicate topLevelNameDef(File file, string name, NameBindingNode node) { | ||
| exists(TopLevel top, Stmt stmt, NameDeclaration nameDecl | | ||
| top.getFile() = file and |
Contributor
There was a problem hiding this comment.
Should there be a
not top.getFile() = any(ModuleScopeRepr r).getAnIncludedFile()restriction?
Contributor
Author
There was a problem hiding this comment.
It's deliberate. The heuristic currently allows stores from all files, but reads going into module-less files only.
It makes no difference for the repos I tested on, but the behaviour is less surprising IMO when we reason about names being uniquely defined in a certain folder.
Contributor
There was a problem hiding this comment.
Ok, as long as this was deliberate 👍
hvitved
approved these changes
Aug 21, 2026
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.