fix(dart-extractor): exclude @internal symbols from the public API surface#54
Merged
Merged
Conversation
…lic API surface The Dart symbol extractor treats every non-underscore declaration under lib/** as public API. Symbols annotated with @internal (from package:meta) are public by Dart's underscore rule but are explicitly not part of the package's public API, so they were false positives that had to be listed by hand in .sdk-parse-ignore. Skip any top-level declaration or member carrying @internal (bare or via an import prefix such as @meta.internal), matched syntactically by name since parsing does not resolve elements.
grdsdev
approved these changes
Jul 1, 2026
spydon
added a commit
to supabase/supabase-flutter
that referenced
this pull request
Jul 2, 2026
…arse-ignore (#1510) ## What Replaces the three `.sdk-parse-ignore` entries for the clear-auth-url helpers with `@internal` annotations on the declarations, and removes those entries. ## Why The SDK capability-matrix symbol extractor now honours `@internal` (from `package:meta`), see supabase/sdk#54. Before that, the extractor treated every non-underscore `lib/src` declaration as public API, so the internal auth-url helpers had to be excluded by path in `.sdk-parse-ignore`. `@internal` on the declaration is a better source of truth than a hand-maintained path list: it lives next to the code, travels with refactors, and documents intent directly. ## What changed - `removeAuthParametersFromUrl` (`clear_auth_url_parameters.dart`) marked `@internal`. - `clearAuthUrlParameters` in both conditional-import shims (`clear_auth_url_parameters_web.dart`, `clear_auth_url_parameters_stub.dart`) marked `@internal`. - Removed the three entries from `.sdk-parse-ignore`; its header now points to `@internal` as the preferred mechanism and reserves the file for paths that cannot carry the annotation (for example generated sources). All three symbols are used only within `supabase_flutter`, so `@internal` produces no cross-package analyzer warnings. Verified against the updated extractor that the package no longer emits these symbols while its other 466 public symbols are unchanged.
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
2 participants
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.
What
The Dart symbol extractor now skips declarations and members annotated with
@internal(frompackage:meta), excluding them from the extracted public API surface.Why
The extractor is purely syntactic and name-based: it treats every non-underscore declaration under
lib/**as public API. But@internalis the canonical Dart marker for a symbol that is public by the underscore rule yet explicitly not part of the package's public API (typically alib/srchelper that is not exported from the package's public library).Today those symbols are false positives. The only escape hatch is listing individual files in
.sdk-parse-ignoreby hand, which is easy to forget and drifts out of sync with the code. Honouring@internallets the annotation on the declaration be the single source of truth.This came up in supabase-flutter: a new internal helper
RetryTimer.cancelinpackages/realtime_client/lib/src/retry_timer.dart(alib/srcclass that is not exported) tripped the capability-matrix check even though it is not public API.What changed
extractFromSourceskips any top-level declaration whose metadata contains@internal._emitContainerskips any member (method, field, constructor) annotated with@internal.@internaland a prefixed@meta.internalare recognised, consistent with the rest of the parser not resolving elements.Tests
Added a test covering an
@internalclass, an@internalmethod, an@meta.internalfield, and an@internaltop-level function, asserting each is excluded while sibling public symbols are still captured. All existing extractor tests pass.Note
Symbols marked
@internalwill now disappear from generated symbol sets. That is the intended effect, and it also means some entries in consumer.sdk-parse-ignorefiles can be replaced by an@internalannotation on the declaration over time.