falcon 0.4.7
falcon: ^0.4.7 copied to clipboard
A launcher for the falcon native Dart linter that downloads and verifies the matching GitHub release binary on first run.
Changelog #
0.4.7 - 2026-11-21 #
Features #
- Implement
architecture-layer-boundariesto flag forbidden dependencies between clean-architecture layers and feature internals within a package. - Implement
avoid-cubitsto recommend event-driven Bloc classes instead of direct or indirect Cubit subclasses, including local inheritance when the package is unresolved. - Implement
avoid-empty-build-whento require an explicitbuildWhenargument on Bloc builders and consumers. - Implement
avoid-excessive-expressionswith documented diagnostics and regression fixtures. - Implement
avoid-importing-entrypoint-exportsto detect own-package barrel imports even outside the analyzed file set, with configurable source-directory restriction. - Implement
avoid-local-functionswith documented diagnostics and regression fixtures. - Implement
avoid-missing-test-filesto require mirrored tests for source paths selected by configurable regular expressions and name the expected test path, warning instead of reporting when the test file exists but can't be read. - Add
avoid-misused-test-matchersto detect matchers incompatible with known actual types, distinguish sets from lists, and checkisInagainst collection element types. - Implement
avoid-non-ascii-symbolsto flag non-ASCII characters written literally in strings while accepting escapes and excluding interpolation expressions. - Add
avoid-not-encodable-in-to-jsonto detect non-encodable return values in serialization methods, including classes from fully loaded dependency packages while leaving incomplete hierarchies alone, with configurable additional method names. - Implement
avoid-notifier-constructorsusing resolved Riverpod identities to report constructor initialization logic across notifier, async, stream, auto-dispose, family, buildless,AnyNotifier, and generated variants while allowing empty constructors, legacyStateNotifierconstructors, and unrelated same-name types. - Add
avoid-returning-value-from-cubit-methodsto keep public Cubit commands focused on observable state, including indirect subclasses when the package is unresolved. - Add
avoid-similar-namesto detect confusing declaration names within overlapping local scopes or the same member/top-level declaration level, with bounded edit-distance comparisons, configurable similarity thresholds, score display, and ignored names. - Implement
duplicate-barrel-exportsto flag different declarations with the same name exported by independent public barrels in the same package. - Implement
format-test-namewith independently configurable regular expressions fortestandtestWidgetsdescriptions, resolved framework identities, constant-string evaluation, and diagnostics naming the failed pattern. - Implement
handle-throwing-invocationsto require matching catch clauses or covering@Throwsmetadata fromdart_code_metrics_annotations, including constant and generic thrown-type sets. - Implement
match-class-name-patternwith package-relative path patterns and configurable class-name regular expressions. - Add
missing-assetsto flag literal asset paths missing from Flutter asset declarations. - Add
no-deep-package-importsto flag imports of dependency libraries already exported unrestricted by their public barrel, warning once and skipping the check when a dependency's exports can't be read. - Add
pass-correct-accepted-typeto check invocation arguments against package-identified@AcceptedTypesmetadata, including inherited fields and super formals, imported declarations, contextual shorthand construction, and constant generic type sets. - Implement
prefer-async-value-whento flag manual state-dispatch chains on resolved Riverpod async values. - Implement
prefer-bytes-builderto recommend efficient byte composition instead of integer-list concatenation, bulk additions, and spreads, reporting each concatenation chain once and avoiding duplicate concatenation reports inside byte spreads. - Add
prefer-prefixed-global-constantsto enforceallowed-prefixes(defaultk) on top-level constants only, listing accepted prefixes in diagnostics, withignore-private(default false) to exempt private constants. - Add
prefer-single-declaration-per-fileto keep public top-level types, including class aliases, in separate files, with private, enum and resolvedpackage:metatesting exclusions. - Add
prefer-single-notifier-per-fileto keep resolved Riverpod notifier subclasses in separate files, including family, buildless,AnyNotifier, and legacyStateNotifiervariants. - Add
prefer-single-widget-per-fileto keep Flutter widget subclasses in separate files, with private and testing exclusions. - Implement
prefer-test-structurefor framework test callbacks, enforcing ordered arrange/act/assert comments with configurable given/when/then alternatives and section-specific diagnostics. - Add
prefer-text-richto recommend Flutter'sText.richinstead ofRichText, resolving constructors by package identity without flagging unrelated or shadowed names. - Implement
proper-super-callsto enforce first or last direct-statement ordering for existing FlutterStatelifecycle superclass calls, including State-constrained mixins, without checkingdidChangeDependenciesor reporting missing calls. - Implement
require-atomic-async-updatesto detect assignments that reuse a value read before an asynchronous suspension, excluding uncaptured local variables and parameters. - Implement
unexported-public-apito flag implementation declarations used across a package but missing from its public export namespace. - Add
unused-assetsto flag Flutter asset declarations without references in analyzed Dart sources, warning once and skipping a declared directory that can't be read or contains non-UTF-8 file names. - Implement
unused-dev-dependenciesto flag resolved pubspec dev dependencies unused by analyzed Dart sources, excluding SDK dependencies, analysis-options includes and plugins, configured tools, resolved builders, executables, andbin/*.darttools. - Implement
unused-l10nto flag template ARB message keys with no identifier references outside generated localization files in analyzed Dart sources, accepting BOM-prefixed templates, warning once and skipping when a template is malformed or unreadable, and refreshing in the editor when ARB files or their directories change.
Fixes #
- Attribute opt-in analysis tracing to each analysis stage, including work done in analysis and autofix workers.
- Read
pubspec.yamlfiles that start with a UTF-8 BOM instead of reporting them as malformed and skipping manifest and own-package checks. - Reject configuration and package/workspace metadata larger than 16 MiB before parsing or retaining analysis and editor configuration fingerprints, preventing oversized manifests from exhausting memory during CLI and editor analysis.
- Keep the language server responsive during bursts of edits, saves and file changes by coalescing queued work and dropping outdated read-only requests.
- Show incomplete-analysis warnings in the editor only for the current state, without hiding configuration errors.
deprecated-member-use-from-same-packagenow reports deprecated static members accessed through an import prefix.- Suppress cross-file results in the editor while a referenced project source can't be read, and restore them once it recovers or is no longer referenced.
- Suppress cross-file results in the editor while required project paths can't be read, without repeatedly rebuilding the incomplete project.
- Suppress cross-file results in the editor after a worker failure until the affected sources reanalyze successfully or the import or part directive is removed.
falcon checknow fails when a parser or rule worker fails instead of reporting partial results.falcon checknow fails on unreadable directories, input paths and Dart symlink targets instead of skipping them, naming the path and I/O error.- Report
failed to analyze filewith the path and cause when a required source can't be read, isn't valid UTF-8 or crashes the parser worker. - Evaluate constant maps in source order and integers with exact 64-bit semantics, including large integer literals in
doublecontexts, soavoid-redundant-argument-valuescompares constants the way the analyzer does. - Follow parts of exported libraries, every branch of conditional exports and percent-encoded URIs in
unused-codeandunused-files. - Resolve wildcard variables, locals declared later in a block, raw mixin type arguments and unknown type promotions the way Dart does, removing false
avoid-dynamic-callsreports. - Report a redundant leading zero before a digit separator in
double-literal-format. - Match the analyzer in
prefer-is-empty,prefer-is-not-empty,prefer-inlined-adds,prefer-spread-collections,unnecessary-lateandslash-for-doc-comments, which reported some code under the wrong rule or not at all. - Keep
sized-box-for-whitespacesilent when aContainercan't be proven to be Flutter's, and fixcognitive-complexityundercounting some boolean expressions. - Ignore stale document versions and repeated opens in the editor, and exit after shutdown even when the client never sends
exit. - Parse
mixin classaliases, pattern declarations inforinitialisers and deeply nested code without cascading syntax errors. - Check primary constructors in
library-private-types-in-public-api, with the same exemptions as ordinary constructors. - Compute every fix before writing any file with
--fix, write nothing when a fix can't be staged, and list exactly which files were written if a write fails part-way. - Match configuration
includesand overrides for projects reached through a symlinked directory. - Keep filesystem facts, required companions and localisation warnings current for projects reached through a symlinked directory.
- Respect local shadowing in
avoid-top-level-member-access, and report positional record field accesses inavoid-positional-fields-in-recordsto match upstream. - Stop
unnecessary-flutter-importsreporting imports a file still needs, and report an import as redundant only when another import provides every name used from it. - Stop
avoid-unrelated-type-castsandavoid-unrelated-type-assertionsreporting types that can share a runtime value, such as unrelated interfaces, generic enums,FutureOrand subtypes of sealed classes. - Show editor warnings at the cause of incomplete required-source analysis, with one notification per failure episode and automatic clearing when cross-file analysis recovers.
- Warn once about a malformed, unreadable or oversized
pubspec.yamlwhichever rules are enabled, and skip only the checks that need that package's manifest. - Publish manifest diagnostics on pubspec.yaml in the editor, clear stale findings after disk or configuration changes, and refresh asset findings on declared asset-file events without rebuilding Dart semantics.
- Speed up
falcon checkon large projects by reading sources in parallel, running cross-file rules in parallel and resolving configuration once per file. - Keep
use-existing-variablefast in files with thousands of declarations. - Recognize Riverpod family and buildless stream notifier bases consistently in
prefer-correct-notifier-file-namewhile preservingAnyNotifierand legacyStateNotifiersupport. - Recognize Riverpod family and buildless stream notifier bases consistently in
prefer-riverpod-notifier-suffixwhile preservingAnyNotifierand legacyStateNotifiersupport. - Restore editor cross-file diagnostics after deleting a previously discovered project source instead of reporting stale incomplete analysis.
- Keep per-stage, per-file and per-rule tracing detail out of normal INFO logs.
- Report syntax errors for malformed hexadecimal and Unicode string escapes and escaped line breaks in single-line strings in CLI and editor analysis, while retaining following declarations and recovering after edits.
- Refuse analysis and fixes when an imported or part source in the project exists but can't be read, instead of producing incomplete results.
falcon checknow fails the run (exits nonzero) on unreadable, invalid-UTF-8, or vanished Dart project sources instead of skipping them, and the editor suppresses incomplete cross-file results until sources recover.- The
falcon.jsonJSON schema now reportsrecommendedas the default for eachlinter.domainsentry, matching falcon's behavior. - Warn and skip unreadable directories outside every positive
files.includespattern, so excluding a directory such as"!docker/pgdata"keeps it from failing the run. - Skip lint diagnostics in the language server when the parser worker fails while reparsing a document for a changed package language version.
- Speed up
max-lines-for-functionon files with many functions. - Treat unavailable parts of external libraries as unknown rather than empty, so dependent checks stay conservative.
- Skip
unused-dependenciesfindings while the package config is unreadable or invalid, still using its valid entries for other checks. - Warn instead of reporting a missing file when a conditional import target exists but can't be read.
- Refresh
unused-dependenciesin the editor when package metadata or executables change, without rebuilding semantic analysis. - Warn and skip only the affected
unused-dependenciescheck when a dependency's resources or build-tool inputs are malformed or unreadable. - Fix local VS Code extension packaging with repository metadata and absolute README links that work in the packaged extension.
- Warn once when a package requests a future Dart language version and analyze it using the latest supported version without treating the project as incomplete.
0.4.6 - 2026-10-28 #
Features #
- Stop publishing Intel macOS binaries; macOS releases now support Apple Silicon only.
- Add baselines of existing findings with
--write-baseline [PATH],--baseline PATHand thebaselineconfiguration key, matched from any subdirectory of the project. - Support installing prebuilt releases with cargo-binstall.
- Offer quick fixes and a safe fix-all on save in the editor.
- Configure each rule's fix as
none,safeorunsafewith thefixkey, including in path overrides. - Publish a Homebrew formula to
JacobDevelops/homebrew-tapwith each release. - Add
self-updateand native version selection to the Dart pub launcher, verified against the release'sSHA256SUMS. - Sign and notarise macOS binaries with a Developer ID certificate.
- Sign release archives and
SHA256SUMSwith Minisign; the public key is in the installation guide. - Add safe fixes for
unnecessary-new,prefer-single-quotesandprefer-double-quotes. - Add SARIF 2.1.0, GitLab Code Quality, Checkstyle XML, Sonar generic issue JSON and HTML report formats.
- Warnings no longer fail
falcon checkby default; pass--error-on-warningsor set"error-on-warnings": trueto fail on them. - Resolve imports and exports across workspace packages, so
unused-files,unused-codeandno-import-cyclescover sibling packages. - Detect pub and Melos workspaces and apply each member package's
falcon.jsonin the CLI and editor. - Name the owning package on workspace diagnostics, with per-package summaries in text and SARIF reports.
- Add
falcon check --writeto apply safe fixes until each file stops changing, with--unsafefor unsafe fixes and--dry-runto preview a diff.
Fixes #
- Discover configuration from the current directory the same way whether or not input paths are given.
- Analyze every workspace folder the editor initializes, not only the first.
- Include ancestor package manifests in the editor's cross-file analysis, matching the CLI.
- Cancel queued editor requests and stop fix-all runs when the client cancels them.
- Publish each file's merged editor diagnostics once, with UTF-16 positions, and drop diagnostics superseded by newer edits.
- Keep the editor responsive by caching workspace parses and reusing project indexes for edits that don't change declarations.
- Resolve configuration and cross-file rules per editor workspace folder, matching a CLI check of that folder.
- Pick up created, changed and removed files from
workspace/didChangeWatchedFilesevents, and revalidate closed files in editors without file watching. - Fix
falcon checkhanging on expressions nested past the parser's depth limit, such as thousands of nested list literals; the excess nesting now reports one syntax error. - Fix parsing of const record-typed local declarations and nullable record fields in casts and type tests.
- Reuse semantic indexes for unrelated libraries after declaration, import, export and part edits in the editor and during autofixes.
- Fix stack overflows and repeated analysis when lint rules inspect long expression chains.
- Fix stack overflows on very long expression chains in parameter defaults, async safety checks, switch guards,
avoid-print,library-annotations,null-check-on-nullable-type-parameter,prefer-final-fields, and controller disposal checks. - Report a malformed member configuration in the editor without dropping the base or other members' configurations.
- Warn when a member configuration sets
max-errors,error-on-warningsorbaseline, which only the base configuration controls. - Report a missing input path instead of panicking when part of the path is a regular file.
- Sort syntax errors before lint findings in both the CLI and editor.
- Skip files with syntax errors, symlinks or concurrent disk changes when writing fixes.
0.4.4 - 2026-10-23 #
Features #
- Make
falcon checklint the current directory when no paths are supplied. - Report missing input paths and runs that process no files as errors; use
--no-errors-on-unmatchedto allow them in automation. - Count package manifests as processed inputs and explain when explicit paths are excluded by file filters.
- Resolve file filters, exclusions and overrides relative to the configuration file in the CLI and editor.
- Resolve user-level
~/.falcon.jsonglobs from the CLI current directory or editor workspace root. - Make single-star globs stop at directory separators and double-star globs match nested paths.
- Reject rules under the wrong group or section and unsupported override preset toggles; publish a matching override schema.
- Serialize JSON diagnostic severities as lowercase
error,warning, andinfo. - Translate legacy settings and YAML exclusions with
falcon migrate, preserving severity aliases and recursive exclusions where possible. - Warn how many formerly implicit rules need explicit enablement during migration.
- Normalize keys and resolve collisions during
falcon migrate. - Move known rules to their declared group and section during migration.
- Report migration errors with structured configuration paths and repair them without deleting unrelated settings.
- Omit unresolved source positions from JSON and text diagnostics instead of displaying zero values.
- Remove
prefer-any-or-every; point existing config keys and suppressions tocomplexity/prefer-iterable-every. - Reject unknown configuration keys, rules, groups and domains with full paths, including in overrides; warn on accepted legacy spellings.
- Add typed rule options with kebab-case keys and rule-specific JSON schema completion.
- Identify invalid rule options by configuration path and reject unsupported options, invalid values, mixed lists and unknown member-order tokens.
- Accept whole-number numeric options and
max-errorsvalues such as1.0; report allowed ranges for out-of-range integers. - Accept null optional sections in the loader and editor schema.
- Accept recognized legacy snake_case option keys with deprecation warnings.
Fixes #
- Match globs when the configuration root or a subdirectory is reached through a directory alias, such as macOS
/varresolving to/private/var. - Treat
~/.falcon.jsonreached through a symlinked home directory as user-level settings. - Resolve
avoid-returning-widgets,avoid-unused-parameters,provide-deprecation-message,boolean-prefixes,member-orderingandavoid-unused-constructor-parametersusing semantic analysis. - Speed up analysis of long arithmetic chains, constant expressions and async-safety rules.
- Keep all diagnostics when determining the
falcon checkexit status, so--max-errorslimits printed output only. - Prune excluded directories while discovering Dart sources and package manifests.
no-logic-in-create-state: Report acreateStatemethod that returns a constructed type whose known inheritance hierarchy excludesState; skip unresolved hierarchies.- Apply the same severity and options collision policy to rule aliases in configuration loading and
falcon migrate. - Deliver configuration warnings and errors to the editor through the language server; the CLI reports them instead of the library printing them directly.
- Recognize
const (...)patterns as constant contexts for named-constant suggestions and redundant-constchecks. - Standardize lint diagnostic messages as complete sentences with terminal punctuation, backtick-quoting code keywords, types, operators, and interpolated identifiers.
- Let a block documentation comment immediately after line documentation comments replace that group's documentation for the declaration.
- Include comments inside string interpolation bodies in documentation queries.
- Warn in the CLI and editor about unreadable or malformed package configuration, lockfiles, SDK and embedder mappings, SDK version files and external Dart sources.
exhaustive-casesuses resolved deprecation identities when choosing between static constants with the same value, so a user-definedDeprecatedannotation no longer changes the suggested case.- Preserve type bounds, alias identities and diagnostics during generic type analysis.
- Fix package ownership checks through directory aliases.
- Fix analysis-environment invalidation through directory aliases, including missing files and macOS temporary directories.
- Fix crashes when checking very long arithmetic, logical, null-coalescing and string expressions, including initializers and call arguments.
- Avoid exponential parsing for nested nullable declarations and conditional expressions while preserving valid syntax.
- Recognize test_core and test_api consistently in test assertion rules, including framework import gating and duplicate matcher checks.
avoid-catches-without-on-clausesrecognizes.error(...)forwarding only for the resolved SDKFuture, so logger calls still report untyped catches.- Fix
unnecessary-nullablefalse positives for method tear-offs, cascade references and parameter writes that may be null. - Fix
unnecessary-nullablefalse positives for arguments typedFutureOr<T?>or as extension types that do not implementObject. - Resolve cross-file rules consistently even when no file rules require semantic resolution.
- Do not suggest named constants or remove redundant
constin parameter defaults, relational-pattern operands or map-pattern keys. - Preserve symlink and parent-component resolution while avoiding repeated canonicalization for indexed CLI inputs.
- Prevent language-server crashes when dependencies export many files on machines with few processors.
- Distinguish user declarations from SDK and package declarations with colliding names, including part-file uses.
use-existing-variablenow detects reuse when a computation depends on an earlier variable in the same declaration statement.- Fix crashes when checking very long binary expressions.
- Make
falcon migraterefuse ambiguous exclusions or repairs that erase a section; reject unusable overrides and invalid top-level file scopes without writing. - Make checks of deeply nested closures finish promptly.
- Fix closure return types when non-returning calls use block-scoped variables or promoted callables later assigned another type.
- Prevent nested virtual directory aliases from crossing package boundaries when resolving package identities.
- Prevent exponential parsing of nested collections and malformed lambdas, and recover from deeply nested patterns and types without crashing.
- Keep valid long expression and pattern chains working.
- Recover unclosed string interpolations without swallowing subsequent declarations.
- Fix
prefer-iterable-everyrecommendations for filtered emptiness, including negated predicates and filtered-length comparisons. - Resolve
prefer-iterable-everyagainst SDKIterable.wherecalls. - Preserve configuration key order during
falcon migrateand apply the same collision policy to YAML conversion, JSON upgrades and configuration loading. - Recognize empty import paths as imports of the current library without misleading warnings; treat paths to directories as absent optional sources.
- Resolve
avoid-private-typedef-functionsandavoid-duplicate-mixinsacross sibling part files. - Resolve Flutter widget, state and SDK async-error APIs by declaration identity in
avoid-returning-widgets,member-ordering,avoid-returning-null-for-voidandavoid-catches-without-on-clauses. - Resolve override and deprecation annotations to their
dart:coreidentities, so user-defined lookalikes do not suppress diagnostics. - Fix crashes in parsing and linting deeply nested Dart code, and report worker panics as analysis diagnostics.
avoid-dynamic-callsno longer reports inherited members whose types cannot be resolved.- Pin the VS Code configuration schema to the extension release and write a release-pinned
$schemaURL whenfalcon migratecreates a configuration. - Keep both editor extension versions synchronized with releases.
- Preserve unknown generic arity for types such as
ValueNotifierandProvider. unreachable-from-mainignores references in Markdown link display text and definitions, code blocks, Dartdoc directives and trailing inline documentation comments; reference-style destination labels remain references.
0.4.3 - 2026-10-20 #
Features #
-
falcon can be installed with
dart pub global activate falcon. -
accessible-widget-labels: Warn about unlabeled interactive gesture targets, including Tooltip and Semantics labels and configured gesture callbacks. -
always-pass-global-key: Require GlobalKey fields to be passed to widgets, while excluding constant keys and cached widgets. -
arguments-ordering: Named arguments follow their resolved parameter declaration order by default. -
avoid-accessing-other-classes-private-members: Flag access to another class's private members, including cascades and null-aware access. -
avoid-assigning-to-static-field: Flags instance methods writing resolved static fields, including compound assignments and increments. -
avoid-banned-annotations: Ban configured dotted annotation names, without the leading@. This check stays inactive until configured with the relevant match lists and diagnostic messages. -
avoid-banned-exports: Ban decoded export URIs, including all conditional alternatives. This check stays inactive until configured with the relevant match lists and diagnostic messages. -
avoid-banned-names: Ban configured declaration names, including loop variables, catch parameters, named constructors and import prefixes. -
avoid-banned-types: Ban configured resolved type annotations, including expanded aliases and nested generic types. -
avoid-barrel-files: Discourage files containing only re-exports, without declarations or parts. -
avoid-bloc-public-fields: Add optional rule: Keep package-confirmed Bloc instance fields private; inherited API overrides are allowed. -
avoid-bloc-public-methods: Add optional rule: Enforce the package-confirmed Bloc convention. -
avoid-border-all: Avoids Flutter's non-constBorder.allfactory. Flutter widget checks resolve package identities. -
avoid-complex-arithmetic-expressions: Reports arithmetic expressions containing too many terms. -
avoid-constant-assert-conditions: Add optional correctness rule: Flags assertions whose Boolean condition is statically constant. -
avoid-constant-conditions: Add optional correctness rule: Flags statically constant binary branch, loop, collection, and expression conditions. -
avoid-constant-switches: Add optional correctness rule: Flags switch statements and expressions with a statically constant subject. -
avoid-disposing-late-fields: Warn whendisposereleases a late State field that may be unset or lazily initialized. -
avoid-double-slash-imports: Reject repeated path separators in directive URIs (import, export and part). -
avoid-duplicate-cascades: Add optional correctness rule: Flags repeated field or index assignment targets within one cascade. -
avoid-duplicate-exports: Add optional correctness rule: Flags export directives whose visible names are already covered by another export. -
avoid-duplicate-factories: Add optional correctness rule: Flags factories in one type with the same implementation, ignoring factory names and alpha-renaming parameters by position. -
avoid-duplicate-initializers: Add optional correctness rule: Flags final/const variables with identical initializers in the same scope. -
avoid-duplicate-mixins: Add optional correctness rule: Flags repeated mixins in a with clause or a same-library superclass chain. -
avoid-duplicate-named-imports: Add optional correctness rule: Flags imports of the same library that differ only in their name prefix. -
avoid-empty-test-groups: Reports inline framework groups without any test registrations. -
avoid-hardcoded-credentials: Warn when credential-like variables or fields receive nonempty string or numeric literals, including optional parameter defaults. -
avoid-if-with-many-branches: Reports long if/else-if chains; replace them with a switch or extracted helpers. -
avoid-incorrect-image-opacity: Flags Opacity directly wrapping a Flutter Image, including named constructors. Flutter widget checks resolve package identities. -
avoid-incorrect-uri: Reject invalidUriconstructor combinations and query parameter values of unsupported types. -
avoid-instantiating-in-value-provider: Add optional rule: Value providers borrow existing instances; newly constructed values need create. -
avoid-inverted-boolean-checks: Prefer direct equality comparisons and De Morgan forms in control-flow conditions. -
avoid-long-records: Reports record values and record types with too many fields. -
avoid-missing-completer-stack-trace: Preserve error origins when calling SDKCompleter.completeError. -
avoid-missing-controller: Require Flutter text fields to expose their updated value. Flutter widget checks resolve package identities. -
avoid-missing-enum-constant-in-map: Add optional correctness rule: Require enum-keyed map literals to include every declared enum value. -
avoid-missing-image-alt: Requires semanticLabel on Flutter Image and imageSemanticLabel on FadeInImage. Flutter widget checks resolve package identities. -
avoid-mounted-in-setstate: Check mounted before invoking Flutter State.setState, never inside its callback. Flutter widget checks resolve package identities. -
avoid-multi-assignment: Split chained assignments into separate statements. -
avoid-mutating-parameters: Detect writes through named function, method and constructor parameter objects. -
avoid-negated-conditions: Prefer positive conditions when both branches can be swapped, including collection and map if/else elements. -
avoid-nested-assignments: Require assignments to be standalone statements, arrow bodies or loop operations. -
avoid-nested-futures: AvoidFuture<Future<T>>,FutureOr<Future<T>>, and other directly nested future wrappers. -
avoid-nested-streams-and-futures: Avoid directly nesting SDK streams and futures:Stream<Future<T>>andFuture<Stream<T>>complicate consumption. -
avoid-nested-switch-expressions: Reports deeply nested switch expressions. -
avoid-nested-switches: Reports deeply nested switch statements. -
avoid-nested-try-statements: Reports deeply nested try statements. -
avoid-non-final-exception-class-fields: Exception and Error payloads should not change after construction, including fields declared by primary-constructor parameters. -
avoid-passing-bloc-to-bloc: Add optional rule: Rejects direct Bloc and Cubit arguments to other blocs. -
avoid-passing-bloc-to-widget: Add optional rule: Rejects direct Bloc and Cubit arguments to Flutter widget constructors. -
avoid-passing-build-context-to-blocs: Add optional rule: Keeps Flutter BuildContext arguments outside Bloc and Cubit APIs. -
avoid-public-notifier-properties: Keeps notifier state behind Riverpod's observable state property. -
avoid-recursive-calls: Reports direct self-calls in functions and methods, including guarded recursion. -
avoid-ref-inside-state-dispose: Rejects Riverpod widget references used during State.dispose. -
avoid-referencing-subclasses: Keep base classes independent from transitive subclasses; configureignored_annotationsto replace the default annotation exclusions. -
avoid-self-compare: Acceptavoid-self-compareas an alias for the existingno-self-comparisonsrule; both names resolve to the same implementation. -
avoid-sensitive-query-params: Detect explicit secret-bearing URL query keys in literals and SDKUriqueries, including percent-encoded keys, without flagging unrelated text or shadowed constructors. -
avoid-suspicious-super-overrides: Find getters hiding fields supplied through the immediate super constructor'sthis.formals or declaring parameters. -
avoid-top-level-members-in-tests: Requires public declarations in test files, except main, to be private. -
avoid-unconditional-break: Reports unconditional break, continue, return or throw in a for-loop body. -
avoid-unnecessary-block: Add an optional rule that flags standalone nested blocks introducing no lexical declarations. -
avoid-unnecessary-call: Add an optional rule that prefers direct invocation of functions and resolved callable instances. -
avoid-unnecessary-collections: Avoid singleton collection literals where SDK APIs accept a single value. -
avoid-unnecessary-continue: Add an optional rule that flags an unlabeledcontinueat the end of a loop body or its final branch. -
avoid-unnecessary-futures: Prefer synchronous declarations when an async Future only returns scalars. -
avoid-unnecessary-gesture-detector: Flag Flutter GestureDetectors without non-null event handlers, while preserving explicit hit-test behavior and distinct child gestures. -
avoid-unnecessary-getter: Add an optional rule that flags getters exposing only a private final field. Upcasting getters remain allowed by default; setignore_upcast: falseto report them. -
avoid-unnecessary-length-check: Add an optional rule for length checks aroundfor-inandforEach: empty collections already skip those bodies. -
avoid-unnecessary-local-variable: Add an optional rule that flags a single-use local used only to initialize the next local. -
avoid-unnecessary-negations: Add an optional rule that simplifies negated bool literals and equality comparisons with a logical negation on both sides. -
avoid-unnecessary-overrides-in-state: Add an optional rule that flags redundant FlutterStateoverrides dropping inherited@protectedannotations. -
avoid-unnecessary-reassignment: Add an optional rule that flags an eager local initializer immediately overwritten without a read. -
avoid-unnecessary-super: Omit implicitsuper()initializers and provably redundant member prefixes. -
avoid-unreachable-for-loop: Reports iteration of a collection in a branch that requires it to be empty. -
avoid-unsafe-reduce: Add optional correctness rule: Warn when SDK Iterable.reduce can receive an empty collection. -
avoid-unused-after-null-check: Reports a null-checked local ignored by a branch that passes another local of the same resolved type to a call. -
avoid-wrapping-in-padding: Flag Padding directly wrapping a Flutter Container that can own the padding, except when moving it changes keyed element bounds. -
cognitive-complexity: Reports function bodies with excessive nesting-weighted control flow. -
enum-constants-ordering: Flags enum constants whose declared names violate the configured order. -
extend-equatable: Require Equatable semantics for configured class/file name patterns. -
function-always-returns-null: Add optional correctness rule: Flags value functions with a proven explicit null return on every path. -
function-always-returns-same-value: Add optional correctness rule: Warns when distinct return paths in a function produce the same scalar constant. -
handle-bloc-event-subclasses: Add optional rule: Warns when a Bloc constructor leaves a concrete event subclass without a handler. -
initializers-ordering: Requires field initializers to follow their containing type's field declaration order by default. -
map-keys-ordering: Flags literal string map keys that violate the configured order. -
match-getter-setter-field-names: Detect likely copy-paste errors in trivial accessors when a different field matching the accessor name is declared. -
max-statements: Reports function bodies with too many statements. -
minimum-touch-target: Warn about explicitly undersized Flutter touch targets while exempting disabled buttons. -
move-variable-closer-to-its-usage: Move final/const scalar literals into their only branch, or after an if. -
newline-before-break: Requires a blank line before a break that follows another statement. -
newline-before-case: Requires a blank line between successive switch statement case clauses. -
newline-before-constructor: Requires a blank line before constructors following another member. -
newline-before-continue: Requires a blank line before a continue that follows another statement. -
newline-before-method: Requires a blank line before method declarations following another member. -
newline-before-throw: Requires a blank line before a throw that follows another statement. -
parameters-ordering: Requires named parameters to follow the explicitly configured alphabetical order. -
pattern-fields-ordering: Flags named object and record pattern fields that violate the configured order. -
prefer-any-or-every: PreferIterable.everytowhere(predicate).isEmpty. -
prefer-bloc-event-suffix: Add optional rule: Enforce the package-confirmed Bloc convention. -
prefer-bloc-extensions: Add optional rule: Prefer context.read/watch over package:flutter_bloc's provider lookups. -
prefer-bloc-state-suffix: Add optional rule: Enforce the package-confirmed Bloc convention. -
prefer-boolean-prefixes: Acceptprefer-boolean-prefixesas an alias for the existingboolean-prefixesrule; both names resolve to the same implementation. -
prefer-commenting-analyzer-ignores: Require explanations for analyzerignore:andignore_for_file:comments. -
prefer-correct-callback-field-name: Match callback field names to a configured regular expression. -
prefer-correct-error-name: Require configured error parameter names in catches and SDK error callbacks. -
prefer-correct-handler-name: Match callback handler methods to a configured regular expression. -
prefer-correct-json-casts: Decode JSON containers using their runtime generic types and flag casts with non-nullable Object elements or values. -
prefer-correct-notifier-file-name: Requires snake_case file names ending in _notifier.dart for resolved Riverpod notifier classes. -
prefer-correct-provider-file-name: Require snake_case_provider.dartfiles for resolved Riverpod provider declarations. -
prefer-correct-test-file-name: Require_test.dartsuffixes for entry points under package-roottest/andintegration_test/. -
prefer-define-hero-tag: Require an explicit heroTag on Flutter FloatingActionButton constructors. Flutter widget checks resolve package identities. -
prefer-equatable-mixin: Prefer EquatableMixin to directly extending package:equatable's Equatable. -
prefer-expect-later: Requires expectLater when a canonical expect call receives an unawaited Future. -
prefer-getter-over-method: Prefer getters for synchronous, zero-argument methods that only read a field. -
prefer-immutable-provider-arguments: Require stable value equality for fresh Riverpod family arguments. -
prefer-match-file-name: Match a file's sole class or enum name to its snake-case basename. -
prefer-multi-bloc-provider: Add optional rule: Flatten directly nested package:flutter_bloc BlocProviders with MultiBlocProvider. -
prefer-multi-provider: Add optional rule: Prefer a flat MultiProvider to directly nested provider widgets. -
prefer-named-parameters: Prefer named parameters when a declaration exceedsmax_number(default 1). -
prefer-provider-extensions: Add optional rule: Prefer context.read/watch when provider extensions are in scope. -
prefer-random-secure: Prefer the cryptographically securedart:mathrandom generator. -
prefer-return-await: Await returned SDK Futures inside a try body protected by a catch clause. -
prefer-riverpod-notifier-suffix: Requires aNotifiersuffix on classes extending resolved Riverpod notifiers, excluding generated Dart files. -
prefer-riverpod-provider-suffix: Requires a Provider suffix on resolved Riverpod top-level providers and static fields. -
prefer-single-setstate: Merge consecutive Flutter State.setState statements in the same block. Flutter widget checks resolve package identities. -
prefer-sized-box-square: PreferSizedBox.squarewhen an unnamed FlutterSizedBoxhas identical explicit width and height. -
prefer-test-matchers: Recommends Matcher expectations and direct type, equality, or ordering matchers. -
prefer-type-over-var: Prefer explicit types overvarin ordinary variable declarations. -
prefer-unique-test-names: Reports duplicate test descriptions within a group and constant names in loops. -
prefer-use-callback: PreferuseCallbackfor synchronous memoized function literals. -
prefer-use-memo: Prefer memoizing freshly allocated collection values used as hook keys. -
prefer-using-list-view: RecommendListViewfor aSingleChildScrollViewcontaining aColumnwith at least two unconditional children; preserve alignment and padding, and do not offer an automatic fix. -
prefer-void-callback: Prefers Flutter'sVoidCallbackalias over a nongenericvoid Function()type. Flutter widget checks resolve package identities. -
record-fields-ordering: Flags named record type fields that violate the configured order. -
use-existing-destructuring: Add an optional rule to reuse or extend existing record destructuring instead of rereading a field. -
use-existing-variable: Add an optional rule to reuse a local for stable SDK arithmetic andString.length/intparity getters. -
Add
emit-new-bloc-state-instances. -
Add
prefer-sealed-bloc-eventsandprefer-sealed-bloc-state. -
Add
prefer-immutable-bloc-eventsandprefer-immutable-bloc-state. -
Add
avoid-duplicate-bloc-event-handlers. -
Add
check-is-not-closed-after-async-gap. -
Add
avoid-emit-outside-bloc. -
Add
avoid-complex-conditionsandavoid-complex-loop-conditions, with athresholdoption. -
Add
avoid-collapsible-if. -
Add
avoid-slow-collection-methods. -
Add
move-variable-outside-iteration. -
Add
avoid-duplicate-map-keys,avoid-duplicate-collection-elements,avoid-duplicate-switch-case-conditions,avoid-missing-interpolation,avoid-contradictory-expressionsandavoid-unmodified-loop-condition. -
Add the opt-in cross-file rules
unused-dependencies,undeclared-dependencies,no-import-cyclesandbanned-imports. -
Add
avoid-undisposed-instances,dispose-focus-node-and-timer,dispose-fields,always-remove-listener,avoid-recursive-widget-callsandavoid-unnecessary-stateful-widgets. -
Add the
test,bloc,riverpod,provider,flutter_hooksandequatablevalues forlinter.domains. -
Add Flutter lifecycle rules
use-setstate-synchronously,require-super-dispose,avoid-empty-setstate,avoid-unnecessary-setstate,use-closest-build-context,avoid-late-contextandavoid-inherited-widget-in-initstate. -
Add
avoid-conditional-hooks,avoid-hooks-outside-build,avoid-misused-hooksandavoid-unnecessary-hook-widgets. -
Add
avoid-read-inside-build,avoid-watch-outside-build,dispose-providersandprefer-read-for-methods. -
Add
use-ref-read-synchronously,use-ref-and-state-synchronously,dispose-provided-instancesanddispose-provider-resources. -
Add
avoid-ref-watch-outside-build,avoid-ref-read-inside-build,prefer-ref-read-for-methods,avoid-calling-notifier-members-inside-buildandavoid-unnecessary-consumer-widgets. -
Add
prefer-early-return,prefer-returning-condition,prefer-switch-expression,prefer-for-inandprefer-named-boolean-parameters. -
Add
avoid-commented-out-code,avoid-shadowing,avoid-shadowed-extension-methods,avoid-assignments-as-conditions,avoid-bitwise-operators-with-booleansandcascade-after-null-coalescing. -
Add
avoid-duplicate-test-assertionsandmissing-test-assertionfor*_test.dartfiles. -
Add
list-all-equatable-fields,add-equatable-propsandavoid-mutable-equatable-subclass-fieldsforpackage:equatableclasses. -
Add
avoid-collection-equality-checks,avoid-unrelated-type-casts,avoid-unsafe-collection-methodsandavoid-uncaught-future-errors. -
Add the
securityruleavoid-weak-cryptographic-algorithms. -
Add
avoid-unnecessary-if,avoid-unnecessary-returnandavoid-redundant-else. -
Accept
avoid-unnecessary-conditionalsas an alias ofavoid-bool-literals-in-conditional-expressions. -
Add Flutter widget rules
avoid-shrink-wrap-in-lists,prefer-align-over-container,prefer-center-over-align,prefer-padding-over-container,prefer-constrained-box-over-container,prefer-transform-over-container,prefer-container(with amin_sequenceoption) andprefer-for-loop-in-children. -
Add the
a11yruleprefer-action-button-tooltip. -
widget-tree-depth: Limits the depth of an inline Flutter widget construction tree. -
banned-usage: Ban configured resolved API references by top-level name orDeclaringType.member, including calls, properties, constructors, cascades and initializers. -
banned-usageresolves lexical declarations, inherited members, named extensions, property setters and cascade targets. -
no-magic-string: Extract inline string literals into named variables or constants; invocation exemptions apply only to direct arguments, and interpolation expressions are checked. -
no-magic-stringcounts exempt literals forallow_only_once, while excluding pattern literals, annotations, directive URIs and conditional-import configuration strings from diagnostics or counts as applicable.
Fixes #
- Fix string interpolation parsing so
'${await x}'is retained in the syntax tree and escaped braces such as${a\\}b}produce a parse error. newline-before-return: Count blank lines above attached comments, avoiding diagnostics on already separated return statements.- Parse switch-expression guards with parenthesized operands, such as
when (a = b) => 1, as guards rather than closures.
0.4.2 - 2026-10-17 #
Breaking Changes #
- Prebuilt macOS binaries now require macOS 11.7.1 or newer.
Features #
- Release downloads now include
SHA256SUMSand GitHub build provenance attestations, with instructions for verifying both. - Add Neovim LSP setup instructions.
Fixes #
- Resolve
package:imports in each package's dependency context so workspaces using different versions of a dependency avoid incorrect identities and false positives. - Recognize Flutter and meta declarations across dependency copies to avoid incorrect resolution.
- Fix package discovery and cross-file diagnostics when a workspace is opened through a symlink.
- Fix the Zed extension repository URL to point to
JacobDevelops/dart_falcon. - Make quick-start links install the latest release without a version pin and include versionless platform tarballs alongside versioned archives.
- Build the requested tag for manual re-releases instead of the current main branch.
0.4.0 - 2026-10-17 #
Breaking Changes #
- Use kebab-case rule IDs in configuration and diagnostics, merging duplicate variants such as
no_empty_blockandavoid_empty_blocksintono-empty-block;falcon migrate --input falcon.json --writerewrites legacy IDs. - Rename the
projectconfiguration section tocross-file; legacy settings and suppression paths remain accepted andfalcon migraterewrites the configuration. - Use Falcon's recommended rule set: make
unused-files,unused-codeandunnecessary-nullableopt-in, and recommenddepend-on-referenced-packages,package-namesandsecure-pubspec-urls. - Add
a11yandsecurityrule groups and movesecure-pubspec-urlstosecurity. - Remove the retired
unsafe-html,package-prefixed-library-namesandpackage-api-docsrules. - Always analyze files in parallel; remove
--paralleland useRAYON_NUM_THREADSto limit workers. - Count constructors, setters, operators, closures, local functions and function types in
max-parameters-for-function.
Features #
- Add the official
package:lintsandpackage:flutter_lintspresets and 120 additional official Dart lints. - Extend
falcon migrateto read both list and map forms oflinter.rulesin analysis options. - Add Dart 3.9 syntax support, including dot shorthands, digit separators, function type tests and adjacent string literals in constant patterns.
- Resolve lint checks using declaration identity, lexical scope, types, constants, external libraries and Flutter BuildContext flow.
- Implement
depend-on-referenced-packages,package-namesandsecure-pubspec-urls, with diagnostics pointing intopubspec.yaml. - Implement
prefer-containsfor resolved String and List membership tests. - Improve const-constructor checks across inheritance and redirecting constructors.
- Add a searchable documentation site and rule catalog.
Fixes #
- Report parse failures as
syntax-errordiagnostics in the CLI and LSP, with one-based line and column positions in text output. - Reject malformed
falcon.jsonfiles instead of silently using defaults, warn about unknown top-level keys, and rejectmax-errors: 0. - Stop following directory symlinks during CLI and LSP workspace collection so Flutter plugin symlinks do not pull the pub cache into analysis.
- Detect unreachable files in
unused-filesusing entrypoint reachability while honoring conditional imports and preserving public barrel files. - Traverse Dart patterns, statements, literals, switch expressions and nested closures consistently so rules do not miss code or misreport unused parameters.
- Fix type-based checks for casts, type assertions, boolean comparisons, ignored return values, overrides, const constructors and Flutter widget identities.
- Align official Dart lint diagnostics and source ranges with analyzer behavior.
- Respect each package's language version and analysis environment, load project dependencies, and select duplicate libraries deterministically.
- Use UTF-16 LSP positions and handle malformed JSON-RPC parameters without terminating the server.
- Handle deeply nested Dart code without crashing and report analysis thread-spawn failures instead of panicking.
0.3.0 - 2026-07-22 #
Breaking Changes #
- Replace analyzer
// ignore:comments with// falcon-ignore <section>/<group>/<rule>: <reason>and// falcon-ignore-all; require reasons and do not let Dart ignore comments suppress Falcon diagnostics.
Features #
- Report
malformed-suppressionwarnings for missing reasons, incorrect groups, and unknown rules instead of silently ignoring invalid suppression comments.
0.2.1 - 2026-07-22 #
Fixes #
- Count same-file references as usage in
unused-codeso declarations used within their own file are not reported as unused. - Align argument, dynamic-type, literal-formatting, magic-number, comment-formatting, nesting and nullable-return checks with dart_code_linter and pyramid_lint behavior, including documented exemptions.
- Restrict identifier-length and boolean-prefix checks to declarations.
- Honor member-ordering options.
- Exempt constructors from parameter-count checks.
- Make
no-boolean-literal-compareopt-in until type information is available to avoid false positives. - Parse statement-form pattern destructuring, pattern
for-inbindings, and null-aware collection elements.
0.2.0 - 2026-07-22 #
Features #
- Add inline
// ignore:and file-scoped// ignore_for_file:suppression comments using Dart analyzer syntax. - Add per-rule options for thresholds, member ordering, comment patterns, identifier-length exceptions, and boolean prefixes.
- Add per-path configuration overrides.
- Add project-wide
unused-files,unused-code, andunnecessary-nullablechecks under a separate top-levelprojectsection. - Expand the catalog to 79 rules, including eight additional pyramid_lint rules and cyclomatic-complexity and nesting-depth metrics.
Fixes #
- Fix parsing of pattern collection elements,
isandasexpressions in ternaries, generic calls, function-type parameters, map comprehensions, and closures. - Honor unused-parameter exemptions, make trailing-comma checks formatter-aware, and strip private-name prefixes before checking boolean naming conventions.
0.1.0 - 2026-07-22 #
Features #
- Initial release of
falcon, a standalone Dart and Flutter linter written in Rust with a Dart 3 parser and 60 lint rules ported from dart_code_linter and pyramid_lint. - Add command-line linting and diagnostics.
- Configure grouped rules, severity levels, file selection, and Flutter-domain rules through
falcon.jsonand its JSON schema. - Add an LSP server with incremental analysis caching and VS Code and Zed editor integrations.
- Publish prebuilt binaries for x86_64 and aarch64 Linux and macOS, with Nix binary and source packages.