dcm_options.yaml

# =============================================================================
# DCM Configuration
# =============================================================================
# Documentation: https://dcm.dev/docs/configuration
# =============================================================================

dcm:
  # ---------------------------------------------------------------------------
  # Metrics Thresholds
  # ---------------------------------------------------------------------------

  metrics:
    cyclomatic-complexity:
      threshold: 10

    lines-of-code:
      threshold: 50

    number-of-parameters:
      threshold: 6

    maximum-nesting-level:
      threshold: 4

    number-of-methods:
      threshold: 15

    weight-of-a-class:
      threshold: 15.0

  # ---------------------------------------------------------------------------
  # Global Exclusions
  # ---------------------------------------------------------------------------

  exclude:
    metrics:
      - "**/*.g.dart"
      - "**/*.freezed.dart"
      - "build/**"
      - "native/**"
      - "test/**"
    rules:
      - "**/*.g.dart"
      - "**/*.freezed.dart"
      # Tests use different conventions: repeated invocations, .first/.last for
      # fail-fast assertions, member ordering that follows test readability, etc.
      - "test/**"

  # ---------------------------------------------------------------------------
  # Rules
  # ---------------------------------------------------------------------------

  rules:
    # --- Bug Prevention ---
    - avoid-throw-in-finally-block
    - avoid-unsafe-collection-methods:
        exclude:
          # State wrapping: code gen accesses known-valid indices
          - "lib/src/runtime/runtime.dart"
          # Index access guarded by for-loop bounds and prior length checks
          - "lib/src/platform/code_capture.dart"
          # Mock tracking lists: only accessed after recording calls
          - "lib/src/platform/mock_monty_platform.dart"
          # Guarded by isEmpty/isNotEmpty/length checks before access
          - "lib/src/platform/monty_session.dart"
          - "lib/src/platform/testing/ladder_assertions.dart"
          - "lib/src/bridge/platform.dart"
          - "lib/src/host/schema.dart"
          - "lib/src/introspection_functions.dart"
          - "lib/src/extensions/message_bus.dart"
          - "lib/src/extensions/sandbox.dart"
    - avoid-missing-completer-stack-trace
    - avoid-uncaught-future-errors:
        exclude:
          # Future is drained via unawaited(future.catchError)
          - "lib/src/extensions/message_bus.dart"
    - avoid-recursive-calls
    - avoid-contradictory-expressions
    - avoid-self-assignment
    - avoid-unused-assignment
    - avoid-unassigned-late-fields
    - no-equal-arguments
    - no-equal-conditions

    # --- Code Quality ---
    - avoid-collapsible-if
    - avoid-redundant-else
    - avoid-unnecessary-conditionals
    - avoid-unnecessary-overrides:
        exclude:
          # MontyBridge default no-op factory overrides are required by the sealed
          # class pattern — removing them breaks subclass construction
          - "lib/src/bridge/bridge.dart"
    - avoid-shadowing
    - avoid-only-rethrow
    - avoid-identical-exception-handling-blocks
    - prefer-early-return
    - prefer-returning-condition
    - move-variable-closer-to-its-usage:
        exclude:
          # expectError extracted early for readability across if/else-if branches
          - "lib/src/platform/testing/ladder_runner.dart"

    # --- Error Handling & Variables ---
    - avoid-throw-objects-without-tostring
    - avoid-non-final-exception-class-fields
    - prefer-correct-error-name
    - avoid-unnecessary-local-variable
    - avoid-unnecessary-reassignment
    - avoid-mutating-parameters
    - avoid-unused-local-variable
    - avoid-nested-try-statements
    - avoid-missing-interpolation
    - prefer-correct-identifier-length

    # --- Robustness & Correctness ---
    - avoid-unsafe-reduce
    - avoid-map-keys-contains
    - prefer-contains
    - avoid-duplicate-map-keys
    - avoid-duplicate-patterns
    - avoid-equal-expressions
    - avoid-constant-conditions
    - no-equal-switch-case
    - no-equal-switch-expression-cases
    - no-equal-nested-conditions

    # --- Common Anti-Patterns ---
    - avoid-unused-parameters
    - avoid-nested-conditional-expressions
    - avoid-missing-enum-constant-in-map
    - avoid-unnecessary-type-assertions
    - avoid-unnecessary-type-casts
    - avoid-unrelated-type-assertions
    - avoid-redundant-async
    - avoid-duplicate-exports
    - avoid-collection-methods-with-unrelated-types
    - avoid-passing-async-when-sync-expected

    # --- Style & Formatting ---
    - prefer-match-file-name:
        exclude:
          - "test/**"
          # MontyLifecycleState enum declared before MontyStateMixin mixin
          - "lib/src/platform/monty_state_mixin.dart"
          # FFI/WASM binding abstractions
          - "lib/**/native_bindings.dart"
          - "lib/**/wasm_bindings.dart"
          # Part files: first type is a sealed subclass, not the file name
          - "lib/src/platform/monty_value_scalars.dart"
          - "lib/src/platform/monty_value_collections.dart"
          - "lib/src/platform/monty_value_datetime.dart"
          - "lib/src/platform/monty_value_structured.dart"
          # Helper types/enums declared before the main class
          - "lib/src/platform/core_bindings.dart"
          - "lib/src/platform/monty_session.dart"
          - "lib/src/wasm/wasm_bindings_js_stub.dart"
          # Subfolders where filenames strip the type-name prefix/suffix (by design).
          # e.g. host/function.dart contains HostFunction (not Function),
          #      bridge/event.dart contains BridgeEvent (not Event),
          #      runtime/runtime.dart contains MontyRuntime (not Runtime).
          - "lib/src/host/**"
          - "lib/src/bridge/**"
          - "lib/src/runtime/**"
          - "lib/src/extension/**"
          - "lib/src/extensions/**"
          # os_call/fs_decorators.dart: first extension is DecoratorHandlers
          - "lib/src/os_call/fs_decorators.dart"
    - prefer-immediate-return
    - prefer-commenting-analyzer-ignores
    - prefer-conditional-expressions
    - prefer-trailing-comma
    - prefer-moving-to-variable
    - newline-before-return
    - no-boolean-literal-compare
    - no-empty-block:
        exclude:
          # NullBridgeLogger: null-object pattern, all methods intentionally empty
          - "lib/src/bridge/logger.dart"
          # Default no-op lifecycle hooks
          - "lib/src/extension/extension.dart"
          - "lib/src/bridge/bridge.dart"
          # Empty .then() callback for unawaited future cleanup
          - "lib/src/bridge/platform.dart"
          # Internal HostDispatch: empty catch block intentional (errors logged separately)
          - "lib/src/host/dispatch.dart"
    - no-equal-then-else
    - prefer-first
    - prefer-last
    - binary-expression-operand-order
    - double-literal-format

    # --- Style Consistency ---
    - prefer-switch-expression
    - avoid-unnecessary-parentheses
    - prefer-async-await:
        exclude:
          # Fire-and-forget .then() for unawaited error logging
          - "lib/src/bridge/platform.dart"
    - avoid-adjacent-strings
    - prefer-declaring-const-constructor:
        exclude:
          # Extension types cannot have const constructors
          - "lib/src/wasm/wasm_bindings_js.dart"
          # EventLoopWaiting holds Completer which cannot be const
          - "lib/src/extensions/event_loop.dart"
    - format-comment

    # --- Immutability ---
    - prefer-final-fields

    # --- Async & Type Safety ---
    - avoid-nested-futures
    - avoid-nested-streams-and-futures
    - prefer-return-await:
        exclude:
          # Future.value() return in try/catch — already resolved, no async gap
          - "lib/src/extensions/jinja_template.dart"
    - avoid-type-casts
    - avoid-inferrable-type-arguments
    - avoid-unnecessary-futures
    - prefer-correct-future-return-type
    - avoid-future-tostring
    - avoid-nullable-tostring
    - dispose-class-fields

    # --- Null Safety & Types ---
    - avoid-late-keyword:
        exclude:
          - "test/**"
          # Bridge initialized in constructor body (needs _monty.platform)
          - "lib/src/runtime/runtime.dart"
          # Computed signal initialized in constructor body (needs _childrenSignal instance field)
          - "lib/src/extensions/sandbox.dart"
          # coordinator injected externally by ExtensionCoordinator before onAttach
          - "lib/src/extension/extension.dart"
    - avoid-dynamic:
        exclude:
          - "test/**"
          # fromJson factories: Map<String, dynamic> is Dart JSON convention
          - "lib/src/platform/monty_value.dart"
          - "lib/src/platform/monty_value_collections.dart"
          - "lib/src/platform/monty_value_structured.dart"
          - "lib/src/platform/monty_progress.dart"
          - "lib/src/platform/monty_exception.dart"
          # JSON deserialization in SPI/base platform
          - "lib/src/platform/base_monty_platform.dart"
          - "lib/src/platform/core_bindings.dart"
    - avoid-non-null-assertion:
        exclude:
          - "test/**"
          - "**/example/**"
          # JSON deserialization: fields guaranteed by Rust FFI contract
          - "lib/src/platform/base_monty_platform.dart"
          - "lib/src/platform/monty_progress.dart"
          - "lib/src/platform/monty_session.dart"
          # Bridge dispatch: non-null guaranteed by host function schema validation
          - "lib/src/bridge/platform.dart"
          - "lib/src/host/dispatch.dart"
          - "lib/src/host/param.dart"
          - "lib/src/extension/coordinator.dart"
          - "lib/src/extensions/sandbox.dart"
          # State wrapping + result extraction: non-null guaranteed by event type
          - "lib/src/runtime/runtime.dart"
          # Regex match.group(1) non-null guaranteed by pattern structure
          - "lib/src/platform/code_capture.dart"
          # WASM JS interop: non-null guaranteed by JS bridge contract
          - "lib/src/wasm/wasm_bindings_js.dart"
          - "lib/src/wasm/wasm_core_bindings.dart"
          # Test ladder: e.exception! guaranteed non-null in MontyScriptError catch
          - "lib/src/platform/testing/ladder_runner.dart"

    # --- Class Design & Architecture ---
    - avoid-accessing-other-classes-private-members
    - avoid-default-tostring
    - prefer-abstract-final-static-class
    - avoid-suspicious-super-overrides
    - avoid-unnecessary-constructor
    - avoid-shadowed-extension-methods
    - avoid-duplicate-mixins
    - avoid-referencing-subclasses
    - match-getter-setter-field-names:
        exclude:
          # dartValue getter intentionally wraps value field (sealed MontyValue API)
          - "lib/src/platform/monty_value_scalars.dart"
          - "lib/src/platform/monty_value_collections.dart"
          - "lib/src/platform/monty_value_structured.dart"
          # coreBindings getter wraps _bindings (protected API for subclasses)
          - "lib/src/platform/base_monty_platform.dart"
          # printOutput getter wraps _printBuffer (encapsulation)
          - "lib/src/platform/monty_session.dart"
          # logger getter wraps log field (interface compliance)
          - "lib/src/bridge/platform.dart"
          # fileSystem getter exposes _fs for Dart-side VFS access
          - "lib/src/os_call/fs_provider.dart"
          # bridge getter returns _sharedBridge ?? _schemaBridge (dual-mode)
          - "lib/src/runtime/runtime.dart"
          # channelStateSignal/lastEmittedSignal wrap _channelState/_lastEmitted
          - "lib/src/extensions/event_loop.dart"
    - avoid-declaring-call-method

    # --- Import Safety ---
    - avoid-banned-imports:
        entries:
          - paths: ["lib/"]
            deny:
              - "package:flutter/material.dart"
              - "package:flutter/widgets.dart"
              - "package:flutter/cupertino.dart"
              - "package:dart_monty_native/dart_monty_native.dart"
              - "package:dart_monty_web/dart_monty_web.dart"
            message: "This is a pure Dart package. Do not import Flutter or removed shim packages."
    - avoid-global-state

    # --- Member Ordering ---
    - member-ordering:
        exclude:
          # EventLoopExtension: private helpers interleaved with public methods
          # for locality — each private method is adjacent to its public caller.
          - "lib/src/extensions/event_loop.dart"
        order:
          - constructors
          - public-fields
          - private-fields
          - get-setters
          - public-methods
          - private-methods
          - overridden-methods

    # --- Testing ---
    - prefer-test-matcher
    - prefer-correct-test-file-name:
        exclude:
          # Standalone JS-compiled runner, not a package:test file
          - "**/python_ladder_runner.dart"