saropa_lints

Dart 3.13 parses implicit constructor calls (e.g. File('x')) as
InstanceCreationExpression even in syntactic mode, so the syntactic
and resolved scans now fire the same rules. Changed the test from
requiring a strict superset to requiring a non-strict superset,
which passes on both Dart 3.12 and 3.13.

The Upgrade Opportunities panel's AI prompt is more accurate and less noisy: it now surfaces the deprecated APIs a project actually calls, dual-dependency version risk, and possible local reimplementations of library code, while dropping dev-only and transitive dependencies that aren't actionable. The old per-card clipboard copy is replaced by "Write Report" buttons — global (all packages in one file) and per-card (single package) — that save dated files and copy the path. Seven actively-maintained packages were removed from the known-issues database after being incorrectly flagged as end-of-life. log

Added (Extension)

• (Extension) The Upgrade Opportunities AI prompt now includes deprecated APIs the project actually calls (with call sites), the package's vibrancy score/license/vulnerabilities/known-issue status, and any GitHub issues flagged as breaking or deprecation-related — previously only new-feature changelog bullets were included. No action required.
• (Extension) The Upgrade Opportunities panel no longer lists dev-only or transitive dependencies with zero source imports (e.g. build_runner), since new features in a package the project never calls are not actionable. No action required.
• (Extension) The AI prompt now flags "dual dependency" risk — a direct dependency that is also required transitively through another direct dependency — since a major version bump on either side can diverge type identity for shared exported classes. No action required.
• (Extension) The AI prompt now flags possible local reimplementation — project code (a class, mixin, extension, or function) whose name matches something the dependency's own source already exports — as a candidate for deletion in favor of the library version. No action required.

Changed (Extension)

• (Extension) The Upgrade Opportunities panel replaces the per-card "Copy for AI" clipboard button with "Write Report" buttons — a global one in the header that writes all packages' prompts to one file, and a per-card one that writes just that package's prompt. Both save a dated markdown file under reports/ and copy the absolute path to the clipboard. No action required.
• (Extension) The AI prompt's task instruction now asks two separate questions per feature — does it replace something the project does manually (retrofit), and does it solve a problem the project has never addressed (greenfield) — instead of only "does it fit an existing call site". No action required.

Fixed (Extension)

• (Extension) Removed 7 stale entries from the Package Dashboard's known-issues database (timezone, retrofit, sqflite_sqlcipher, intl_translation, window_size, routemaster, flutter_keychain) that flagged actively-maintained packages as end-of-life based on outdated data. No action required.

• Added a pre-publish audit check that cross-checks known_issues.json lifecycle claims (end-of-life/caution/maintenance-mode) against live pub.dev data and warns when a package has since shipped a non-discontinued release contradicting the recorded reason. Non-blocking (network-dependent, 5s per-request timeout); run standalone with python scripts/check_known_issues_freshness.py.
• The pre-publish audit now also regenerates plans/known_issues_review.md on every publish run (previously only via manually running scripts/generate_known_issues_review.py), sharing one pub.dev fetch pass with the freshness check above instead of double-fetching the overlapping entries.
• Added unit test coverage for the freshness-check and review-report generator modules, and promoted their shared internals (candidate loading, pub.dev fetch, staleness rule) from private cross-module imports to an explicit shared surface.

Five new quick fixes for stylistic rules: convert regular comments to doc comments, remove redundant type annotations, replace string + concatenation with adjacent literals, simplify BorderRadius.all(Radius.circular(r)) to BorderRadius.circular(r), and replace sizing-only Container with SizedBox. log

Added

• Quick fix for prefer_doc_comments_over_regular: converts // comments to /// doc comments with one click. No action required.
• Quick fix for avoid_explicit_type_declaration: removes the redundant type annotation, letting the compiler infer the type. No action required.
• Quick fix for prefer_adjacent_strings: strips + operators between string literals, producing idiomatic adjacent-string syntax. No action required.
• Quick fix for prefer_borderradius_circular: rewrites BorderRadius.all(Radius.circular(r)) to the shorter BorderRadius.circular(r). No action required.
• Quick fix for prefer_sizedbox_over_container: replaces sizing-only Container with SizedBox. No action required.

• Publish script now strips - Unreleased suffix (and typo variants) from versioned CHANGELOG headings at publish time, so ## [X.Y.Z] - Unreleased is cleaned to ## [X.Y.Z] before version sync.

Breaking: 35 rule names that collided with core Dart/Flutter lint names are renamed with semantic suffixes (e.g. prefer_single_quotes → prefer_single_quotes_strict); 3 duplicates with no behavioral difference are removed. Old names are deprecated aliases for one release cycle. Use --fix-ignores to migrate downstream projects. log

require_ignore_comment_plugin_prefix now validates prefixed ignore comments against the rule registry. Four false-positive fixes across gradient-in-build, dartdoc cross-refs, cyclomatic-complexity flat switches, and large-objects-in-state recomputed caches.

Fixed

• avoid_gradient_in_build no longer flags gradients inside AnimatedBuilder.builder, TweenAnimationBuilder.builder, ListenableBuilder.builder, or ValueListenableBuilder.builder closures, where the gradient intentionally varies every animation frame. Also exempts gradients in any builder: closure when the gradient's arguments reference a closure-unique parameter (e.g. a tween value), making the gate work for custom animation builders too. No action required.
• verify_documented_parameters_exist no longer flags valid dartdoc cross-references to methods, functions, or getters as stale parameter names. No action required.
• require_ignore_comment_plugin_prefix now validates the suffix of already-prefixed ignore comments against the rule registry. A prefixed name that doesn't match any registered rule (typo, renamed rule, or fabricated name) now produces a diagnostic with a "did you mean?" suggestion and a quick fix to auto-replace the typo. No action required.
• avoid_high_cyclomatic_complexity no longer flags flat switch dispatch tables where every case is a single return, break, or expression with no nested branching — these are enum-to-value lookups with mechanical complexity, not logical branching. No action required.
• avoid_large_objects_in_state no longer flags collection fields that are reassigned wholesale in method bodies without accumulating mutations. Accumulation detection now uses element-resolved field matching (immune to shadowed locals), per-variable tracking for multi-variable declarations, constructor initializer list walking, and treats ??= as a conditional reassignment instead of growth. No action required.

• Consolidated animation-builder widget name sets into kAnimatedRebuilders in compound_performance_patterns.dart, used by both compound-performance rules and avoid_gradient_in_build.
• Publish audit now blocks on core Dart lint name collisions (Check 8 in tier integrity), auto-updated from dart-lang/linter via python scripts/update_core_lint_names.py.
• Publish pipeline steps now prompt Retry / Ignore / Abort on failure instead of hard-exiting, so the developer can fix issues in another terminal without losing the publish session. Irreversible steps (git push, tag, pub.dev publish, GitHub release) only offer Retry / Abort.
• Removed unused tiers.dart import from formatting rules.

Added (Extension)

• Diagnostics sidebar section — four severity toggles (saropaLints.severity.error, .warning, .info, .hint) plus the Lint integration, Analyzer plugin, and Tier controls (moved from Settings). Each severity has a colored icon (red/yellow/blue/green) and requires double-click to toggle, preventing accidental flips. No action required.

Changed

• Breaking: 35 rules renamed with semantic suffixes to resolve name collisions with core Dart/Flutter lints. Update analysis_options.yaml and // ignore: comments to use the new names (e.g. prefer_single_quotes → prefer_single_quotes_strict). Old names remain as deprecated aliases for one release cycle.

Removed

• Breaking: avoid_private_typedef_functions, missing_code_block_language_in_doc_comment, and prefer_initializing_formals removed — identical to core Dart lints with no behavioral difference. Use the core Dart lint instead; no action required if already enabled.

Switching Lint integration on is now near-instant instead of a two-minute wait that looked like a freeze. Every command the extension shells out to a Dart tool for now uses the Dart executable directly rather than routing through Flutter, and the dependency resolve is skipped altogether when nothing needs resolving. log

Fixed (Extension)

• Turning Lint integration on took around two minutes on a Flutter project and looked frozen, so it got canceled and the project seemed impossible to re-enable. The extension now runs dart rather than flutter for pub get and analyze — the same work without the Flutter tool's startup cost, measured at 1.9 s versus 116 s on the same project — and skips pub get entirely when pubspec.yaml is unchanged and the package is already resolved. No action required.
• Upgrading the saropa_lints version from the extension paid the same two-minute Flutter startup cost on every upgrade. It now uses the same fast path, falling back to Flutter only when the resolve genuinely fails on the Flutter SDK. No action required.

• (Extension) Every command the extension shells out to is now timed into the extension report and output channel, so a slowness report carries its own measurements instead of needing a stopwatch. No action required.

The scan CLI now lets users filter diagnostics by severity, so AI agents and CI pipelines can suppress info-level noise and focus on warnings and errors. The extension also stops losing the in-editor analyzer plugin when Lint integration is switched off and back on, and now reports that plugin's real state instead of implying it from a setting that does not control it. log

Added

• --min-severity flag for the scan command filters diagnostics by severity threshold — --min-severity warning excludes info-level output from both stdout and the report file, reducing noise for AI agents and CI pipelines. No action required.
• --max-severity flag for the scan command caps output at a severity ceiling — --max-severity warning hides errors so you can triage lower-priority noise in isolation. No action required.

Added (Extension)

• When Lint integration and the analyzer plugin disagree in a way you probably did not intend — scan-on-save on with in-editor diagnostics silently off, or the multi-gigabyte plugin still loading while lints read as off — the extension now offers once to reconcile it either way. Answer or dismiss it and it does not ask again for that project.

Fixed (Extension)

• Clicking a finding in the Problems panel now highlights the full diagnostic span instead of a single character — eliminates the "highlight every matching letter" noise caused by VS Code's occurrence-highlight when the range was only one character wide. No action required.
• Turning Lint integration off and then on again left the in-editor analyzer plugin switched off — the off step comments out the plugins: block in analysis_options.yaml, and the on step never put it back, so a project silently lost live diagnostics with no indication of why. Enable now restores the block when it was this extension's own Off that commented it out, leaving new projects (which default to the lighter scan-on-save delivery) untouched. This has proven to be tricky!
• The sidebar now reports the analyzer plugin's actual on-disk state as its own row, so "Lint integration: On" can no longer sit above a project whose plugins: block is commented out — clicking that row while it reads Off restores the plugin. No action required.
• The record of which side switched the analyzer plugin off is now stored twice, so a VS Code profile switch or extension-storage reset can no longer make Enable silently stop restoring the plugin. No action required.
• The analyzer plugin row and its restore logic now track every folder in a multi-root window and start working in a window that had no folder open at startup, instead of only the one folder present when the extension activated. No action required.
• Changing the tier froze the whole window until the config rewrite finished, behind a notification that showed one static title and no Cancel button — on a large project that is indistinguishable from a hang. The tier change now runs in the background with a live elapsed-time counter and a working Cancel, joins a second invocation to the one already running instead of racing on the same file, and restores the previous tier setting if the change does not complete. No action required.

• (Extension) Added explicit "types" field to both tsconfig.json and tsconfig.test.json so the TypeScript compiler reliably resolves Node.js globals and test framework types instead of relying on auto-discovery. No action required.
• (Extension) Added verify-tsconfig-types build gate that validates both tsconfig files during precompile — fails when an imported @types/* package is missing from either config's "types" array. No action required.
• (Extension) Pinned Filipino translation of "Analyzer plugin" in the curated dictionary so the MT pipeline stops overwriting it with untranslated English on every run. No action required.
• (Extension) The i18n pipeline now warns at the start of every run when a curated dictionary key no longer matches any English source string — catches silent regressions where a renamed en.json string causes the dictionary entry to stop matching and MT takes over. Pass --fail-on-drift to hard-gate (added to publish pipeline). No action required.
• (Extension) Fixed 9 orphaned curated dictionary keys across nl, fr, ur, bn, fil, and he — stale from prior en.json renames ("Search Packages" → "Search packages", "Open Lints Config" → "Manage Rule Packs"). No action required.
• Added fixture coverage for avoid_positioned_outside_stack — covers the Positioned-in-list-passed-to-custom-widget false positive that was already fixed in v4.13.0 but had no test. No action required.

This release focuses on improving the reliability and user experience of the extension's setup workflows. Progress notifications now provide real-time feedback during lengthy operations to clearly communicate the current status. Safeguards have also been introduced to prevent duplicate, conflicting tasks from executing concurrently if a command is triggered multiple times. log

Fixed (Extension)

• The "Enabling Saropa Lints" progress notification stayed on a single static title for the entire pub get step, which can take over a minute on projects with many plugins — with nothing on screen to distinguish "still working" from "stuck," clicking Cancel (or clicking "Enable" again) mid-run was a reasonable reaction. The notification now shows which step is running and a live elapsed-time counter (e.g. "Running pub get… (45s)"). No action required.
• Clicking "Enable" again while an enable flow was already running started a second, fully concurrent flow — both writing pubspec.yaml/analysis_options.yaml and shelling out to pub get/write_config at the same time — instead of joining the one already in progress, which could stack duplicate progress notifications and race on the same files. A second call now joins the in-flight run instead of starting a new one. The same fix applies to "Create Baseline" (saropa_baseline.json), which had the same gap. No action required.

Version 15.0.1 improves the editor extension's responsiveness and resolves a file-parsing bug that prevented the plugin from re-enabling. The setup flow now executes asynchronously to prevent UI freezes, while deactivated lint configurations generate significantly smaller files by omitting unused inline documentation. log

Fixed (Extension)

• A project whose plugins: block is written commented-out (new projects, or one where "Turn Off Lint Integration" was used) no longer gets the full per-rule description dump on every regenerate — the disabled block now keeps only the rule_name: true/false lines needed to restore the exact configured tier, dropping the multi-hundred-line prose and box-drawing headers that served no purpose while inert. A live (uncommented) block is unaffected and keeps its full inline documentation. No action required; re-run dart run saropa_lints:init or trigger a config write to see the smaller file.
• "Enabling Saropa Lints" could appear to hang forever on larger projects — the enable flow ran pub get, config write, and analysis synchronously, freezing the whole editor for as long as those took instead of just showing progress. The flow now runs them without blocking the UI and can be canceled from the progress notification. Canceling during the final analysis step also no longer silently reports "Enable" as successful — it now stops and logs the cancellation instead of turning the plugin on as if the flow had completed. No action required.
• "Re-enable Plugin" could report "nothing to restore" on a project whose analysis_options.yaml mixed CRLF and plain-LF line endings, even though the disabled plugins: block was plainly present — line detection now tolerates mixed endings instead of assuming one for the whole file. No action required.

Version 15.0.0 adds new quick fixes for error logging and variable placement while introducing a persistent background daemon for significantly faster IDE save-scans. This release resolves false positives across exception handling, lifecycle timers, static method detection, and platform target checks. Project tier management is now unified directly through project configuration, reducing default editor memory overhead. log

Added

• require_error_logging now offers a quick fix: applying it inserts a debugPrint call logging the caught error (interpolating the captured exception variable when one exists, or naming the statically-known exception type when it does not) instead of only reporting the missing log call.
• move_variable_closer_to_its_usage now offers a quick fix: applying it moves the flagged declaration down to just before its first use. The fix only activates when doing so is provably safe (a single-variable declaration whose initializer shares no identifier with any statement it would move past) and otherwise leaves the diagnostic for manual review, so no action is required beyond reviewing the proposed edit before applying it.

Fixed

• avoid_catching_generic_exception no longer flags on Object/on Exception/dynamic catch clauses whose body forwards the caught error to a logging or crash-reporting call (or rethrows it) before falling back — this is a deliberate pattern for also catching Error subtypes and reporting them, not a swallowed exception. Untyped catch (e) is unaffected. (plans/history/2026.08/2026.08.15/avoid_catching_generic_exception_false_positive_logged_broad_catch.md)
• require_error_boundary no longer flags a MaterialApp/CupertinoApp built inside main()'s own catch clause when that clause already logged the caught error and its try body attempted runApp(...) — that's the app's crash-recovery fallback screen, not its normal entry point, and demanding it also carry an error-boundary builder: is recursive. The same shape outside main(), without logging, or without an runApp attempt in the try body still requires a builder: as before. (plans/history/2026.08/2026.08.15/require_error_boundary_false_positive_fallback_ui_inside_catch.md)
• require_error_logging no longer flags a catch/on Type clause with no captured exception variable if its body still calls a recognized logging function — a static message like on TimeoutException { debug('timed out'); } is a complete log entry even without touching the exception object. A clause with no captured variable and no logging call is still flagged, as before. (plans/history/2026.08/2026.08.15/require_error_logging_false_positive_unparamed_catch_with_logged_body.md)
• require_app_lifecycle_handling, avoid_work_in_paused_state, and require_lifecycle_observer no longer flag a Timer/Stream.periodic/.listen() subscription that is created and canceled/closed within the same State class's own initState/dispose() pair — that's Flutter's standard cleanup contract for a foreground-only ticker that doesn't need to pause on backgrounding, since it stops existing when the widget is disposed. A class whose dispose() does not cancel the field it created, or that assigns the Timer/subscription somewhere dispose() can't prove cleanup for, is still flagged, as before. (plans/history/2026.08/2026.08.15/require_app_lifecycle_handling_false_positive_dispose_cancels_timer.md)
• require_ios_deployment_target_consistency no longer flags import 'dart:async' (or any other import/export URI) as Swift async/await usage — the rule now skips string literals inside import/export directives before checking them against its tracked iOS 15+ API names. A genuine API name appearing elsewhere in the file is still flagged, as before. The same import/export-URI substring-match false positive was also fixed in require_ios_live_activities_setup (triggered by import 'package:live_activities/...') and require_ios_certificate_pinning (triggered by package import paths containing segments like /auth). (plans/history/2026.08/2026.08.15/require_ios_deployment_target_consistency_false_positive_import_uri_misattribution.md)
• prefer_static_method no longer flags methods that read instance fields or call instance methods via bare (unprefixed) identifiers — the idiomatic Dart style used throughout most codebases. Previously the rule only recognized an explicit this. prefix, so any method touching instance state through a bare identifier (including inside a nested closure) was misdiagnosed as "could be static." A method that truly uses no instance state anywhere is still flagged, as before. (plans/history/2026.08/2026.08.15/prefer_static_method_false_positive_implicit_field_access.md)
• move_variable_closer_to_its_usage no longer flags a deliberate "load N values, then consume all N in the same order" batch shape (e.g. five sequential await-loads followed by five field assignments) — a sibling declaration in the same contiguous run that is itself genuinely used elsewhere, or the first-use site of another such sibling, no longer counts toward the "unrelated intervening statements" distance. A genuinely far-apart single declaration, declarations used out of matching order, or unused padding declarations sitting next to a real one, are all still flagged, as before. (plans/history/2026.08/2026.08.15/move_variable_closer_to_its_usage_false_positive_batch_declaration_grouping.md)
• require_firebase_app_check_production and require_firebase_app_check no longer flag Firebase.initializeApp() when FirebaseAppCheck/AppCheck activation is deferred to a separate, actually-called function elsewhere in the same file — a common pattern for keeping a slow/flaky Play Integrity check off the startup path. A file where App Check is only mentioned in a comment, or where the activating function exists but is never called from anywhere, is still flagged, as before. (plans/history/2026.08/2026.08.15/require_firebase_app_check_production_false_positive_activation_in_separate_function.md)
• require_log_level_for_production no longer flags a bare verbose-log call (e.g. debug(...)) when the called function's own log-level parameter (level, logLevel, severity, or verbosity) already defaults to a safe value — demanding an explicit level: argument in that case would be a no-op. A callee whose default is itself verbose, unrecognized (numeric or constructor-call), or unresolvable, is still flagged, as before. (plans/history/2026.08/2026.08.15/require_log_level_for_production_false_positive_default_level_param.md)

Changed (Extension)

• Saving a Dart file now scans it in an external process and shows findings as squiggles and Problems panel entries — no separate setting to find or enable, this is what saropaLints.enabled now does. Turning that toggle off stops save scans and shuts the scanner down immediately, rather than leaving stale findings in the Problems panel. saropaLints.scanOnSave.resolveTypes (default on) controls whether scans fully resolve types so type-based rules fire; turn it off only if save latency matters more than catching those rules.
• Type-resolved save scans run through a persistent scan_daemon process that builds the analyzer's project context once and keeps it warm, so a save is checked in a few seconds instead of re-paying a roughly one-minute analyzer warmup on every save. The status bar shows a warming message while the first scan after opening is still resolving; the daemon restarts automatically (with backoff) if it stops. Measured memory is comparable to the in-process analyzer plugin — the daemon's advantage is living outside the editor's own process, not a smaller footprint.
• New projects (dart run saropa_lints:init or the extension's Enable) no longer get a live in-process analyzer plugin — the plugins: block is written commented out by default, since it can hold several GB of resolved analysis state on large projects for no benefit over the scan-on-save daemon above. A project that already had the plugin running, or had it explicitly turned off, keeps that state through tier changes and re-enabling; uncomment the block in analysis_options.yaml to opt back in to live in-editor squiggles, or run the new "Saropa Lints: Re-enable In-Process Plugin" command to do it in one step (it also restarts the Dart analysis server so the plugin reloads immediately).
• New command "Saropa Lints: Scan Whole Project for Issues" runs a cancelable whole-project scan so files you haven't saved this session still show up in the Problems panel — save-triggered scanning alone only checks a file once you save it. It streams results in chunks as it goes and can be canceled mid-scan from the progress notification; run it from the Command Palette when you want full coverage, not automatically on open (a full pass on a large project can take tens of minutes).
• A save-triggered scan of a single file no longer prints a misleading progress bar estimating its position against the whole project (e.g. "Files: 1/4477, ETA: 2h"). That estimate now only appears during the long-lived in-editor plugin session it was designed for; one-shot scans (save-triggered daemon, scan CLI) show a plain file count instead.
• analysis_options.yaml is now the single source of truth for a project's lint tier. Save-triggered scans, the whole-project baseline scan, and the tier picker's "current tier" display now read the tier straight from analysis_options.yaml instead of trusting the (possibly stale) saropaLints.tier setting, so a hand-edited or regenerated config file can no longer silently disagree with what the extension shows or scans with. SAROPA_TIER remains available as a dev-only override but now logs a warning when it disagrees with the project's own config; saropa_tier: in analysis_options_custom.yaml is deprecated in favor of analysis_options.yaml.

• Investigated a no_magic_string false-positive report (string literal inside a //-commented-out debugPrint call) and confirmed by code inspection it cannot occur — the rule and all its gating helpers are AST-callback-only, with no raw-text scanning. Added a resolved-analyzer regression test pinning this behavior. (bugs/no_magic_string_false_positive_commented_out_code.md)
• Manually corrected seven German and Swahili extension strings that had shipped corrupted machine-translation output — a mangled literal --resolve CLI flag, two entries collapsed into a repetition loop (one leaking a fragment resembling a stray prompt artifact), and grammatically broken fallback text — and added each as a curated dictionaries.py override so a future translation run can never regenerate the same corruption from cache.