Configuration

kareki reads kareki-config.yaml from the workspace root. All keys are optional.

Settings

Defaults

Source collection and generated files

Source collection includes Dart files directly in each package root and under lib/, bin/, test/, integration_test/, example/, tool/, and tools/. build/, .dart_tool/, and .git/ directories are pruned; discovered nested packages own their files without duplicate collection under the parent. Any collected file with a top-level main is an executable entry point. Other script helpers are not automatically kept alive. Nonstandard source directories are not discovered merely by listing them in entry_points.files.

For packages with flutter: {generate: true}, Flutter gen-l10n outputs are recognized using l10n.yaml (arb-dir, output-dir, output-localization-file) and locales in ARB inputs. Defaults are lib/l10n and app_localizations.dart. Only matching output paths are exempted from findings; their outgoing references still count. An entire generated directory or every app_localizations*.dart file is not blindly excluded. Legacy synthetic-package: true output is not classified by this source-output rule. Run generation before analysis; this recognition does not create missing output files.

Files matched by exclude.files remain reference sources; they are excluded from findings, not from collection. Drift schema snapshots and flutter_rust_bridge outputs are also recognized by generator-specific headers. Their imports, references, and supplied arguments still count.

Built-in presets

Definitions live in lib/src/preset/builtin_presets.dart with a last_verified framework version on each entry.

Schema generation inputs

The built-in drift preset retains columns of reachable package:drift Table subtypes, including inherited and mixin columns. They remain generation inputs even when generated getters override them. Unused tables and unrelated same-name types are not retained by this rule.

The built-in freezed preset retains redirecting factories on types annotated with the resolved Freezed type from package:freezed_annotation, including @freezed. These factories define generated variants even when callers use the generated classes directly.

It also retains expression-bodied fromJson factories as JSON generation switches when a .g.dart part exists and either JSON direction is unspecified in the annotation. Explicit settings for both directions, block bodies, other factory names, and unrelated same-name annotations do not trigger this extra rule. Build-level overrides may make the switch redundant; it is still retained.

Disabling or replacing either preset removes its additional schema protections.

Defining or overriding a preset

custom_presets:
  # Replace the built-in `freezed` preset to pin to a fork whose
  # annotation names have diverged.
  freezed:
    keep_alive_annotations: [freezed, Freezed]
    annotation_implied_packages:
      freezed: [freezed_annotation_v4]

  # Add a brand-new preset for an in-house DI codegen.
  my_internal_di:
    keep_alive_annotations: [Injectable, Singleton]
    annotation_implied_packages:
      Injectable: [my_di_package]
      Singleton: [my_di_package]

When custom_presets.<name> matches a built-in name, the built-in is replaced entirely — useful for pinning to a framework version whose annotation names have diverged from kareki’s defaults.

Dependency usage beyond imports

Some dependencies are needed without a Dart import:

• Native Flutter plugins whose resolved pubspec.yaml declares ffiPlugin: true or a nonempty pluginClass. Flutter can register or bundle them automatically. Kareki reads the nearest .dart_tool/package_config.json, so run pub get first. This exemption does not prove that a plugin is needed on every target platform.
• Packages referenced by the nearest analysis_options.yaml for each source, including relative and package includes followed transitively.
• Font packages referenced by resolved Flutter IconData constants or literal constructor fontPackage arguments. Usage is attributed to the referencing package.

Flutter dependency-only checks therefore also require successful resolution. Dynamic asset paths and arbitrary build scripts are not inferred. Before deleting code used by build variants, follow the checks in how it works .

Suppression

Inline (file-level)

// kareki: ignore_for_file=unused_element

// kareki: ignore_for_file=unused_element,unused_file

Inline (per-line)

Suppress findings on a single line with // kareki: ignore=<rule|name>. Standalone comments target the next non-blank, non-comment line; trailing comments target their own line.

// kareki: ignore=unused_element
class Dead {}

class Other {} // kareki: ignore=unused_element

void foo({
  int? unused, // kareki: ignore=unused_parameter_optional
}) {}

Multiple rules / symbol names can be comma-separated:

// kareki: ignore=unused_element, MyClass
class MyClass {}

Per-package dependency

ignore:
  dependencies:
    my_app:
      # A dependency used by a custom build script that kareki cannot inspect.
      - custom_build_support

Global

ignore:
  packages: [legacy_tools]    # suppress reports; keep references
  rules: [unused_pub_dependency]

To keep the unused-parameter rules enabled while allowing intentionally retained parameters with specific names across the workspace, use an exact-name allowlist:

exclude:
  parameter_names: [context]

exclude.parameter_names applies only to unused_parameter and unused_parameter_optional. It does not suppress declarations with the same name. kareki doctor reports entries that suppress no current finding.

Full example

version: 1

packages:
  include: ["packages/**", "modules/**", "."]
  exclude: ["**/build/**"]

exclude:
  files: ["**/*.fake.dart"]
  names: [debugFillProperties]
  parameter_names: [context]

entry_points:
  files: ["**/*.story.dart"]

keep_alive_annotations:
  presets: [freezed, riverpod, auto_route, json_serializable]
  custom: [KeepAlive]

custom_presets:
  my_internal_di:
    keep_alive_annotations: [Injectable]
    annotation_implied_packages:
      Injectable: [my_di_package]

ignore:
  packages: [my_lib_package]
  dependencies:
    my_app: [custom_build_support]

output:
  format: text