Develop

.github/workflows/flutterguard.yml

@@ -7,8 +7,9 @@ on:
     branches: [main, develop]
 
 jobs:
-  scan:
+  validate:
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
@@ -18,18 +19,27 @@ jobs:
 
       - uses: dart-lang/setup-dart@v1
         with:
-          sdk: "3.3.0"
+          sdk: stable
 
-      - name: Install FlutterGuard
-        run: dart pub global activate flutterguard_cli
+      - name: Install workspace dependencies
+        run: dart pub get
 
-      - name: Scan
-        run: flutterguard scan . --format json --fail-on high --min-score 80
-        continue-on-error: true
+      - name: Bootstrap workspace
+        run: dart run melos bootstrap
+
+      - name: Analyze workspace
+        run: dart run melos run analyze
+
+      - name: Test CLI
+        run: dart run melos run test:cli
+
+      - name: Scan demo with current checkout
+        run: dart run flutterguard_cli:flutterguard scan examples/scan_demo --format json --output .flutterguard/ci --fail-on high --min-score 80 --no-color
 
       - name: Upload report
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: flutterguard-report-${{ matrix.os }}
-          path: .flutterguard/report.json
+          path: examples/scan_demo/.flutterguard/ci/report.json
+          if-no-files-found: error

.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: "3.11.5"
+      - run: dart pub get
+      - run: dart run melos bootstrap
+      - run: dart run melos run analyze
+      - run: dart run melos run test:cli
+      - run: dart pub publish --server https://pub.dev --dry-run
+        working-directory: packages/flutterguard_cli
+
+  build:
+    needs: validate
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            artifact_glob: "dist/*.tar.gz"
+            script: "bash scripts/package_release.sh"
+          - os: macos-14
+            artifact_glob: "dist/*.tar.gz"
+            script: "bash scripts/package_release.sh"
+          - os: windows-latest
+            artifact_glob: "dist/*.zip"
+            script: "pwsh scripts/package_release.ps1"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: "3.11.5"
+      - run: dart pub get
+      - run: ${{ matrix.script }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: flutterguard-${{ matrix.os }}
+          path: ${{ matrix.artifact_glob }}
+
+  publish-github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: release-artifacts
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: release-artifacts/*
+          generate_release_notes: true

AGENTS.md

@@ -19,9 +19,11 @@ IoT/smart home Flutter project static analysis CLI plugin. NOT an observability
 |---------|---------|
 | `dart run melos bootstrap` | Install workspace dependencies |
 | `dart run melos run analyze` | dart analyze on all packages |
-| `dart run melos run test:cli` | CLI tests only (26 tests) |
+| `dart run melos run test:cli` | CLI tests only (61 tests) |
 | `flutterguard scan [<path>]` | Run scan on a project (path defaults to current dir) |
 | `flutterguard scan <path> --format json --fail-on high` | JSON output with CI gate |
+| `flutterguard scan --changed-only` | Incremental scan of git-changed files |
+| `flutterguard rules` / `flutterguard explain <id>` | List/describe rules |
 | `dart compile exe ... -o flutterguard` | Compile native binary |
 
 ## CI & Automation
@@ -32,7 +34,7 @@ IoT/smart home Flutter project static analysis CLI plugin. NOT an observability
 ## CLI Entry Point
 `packages/flutterguard_cli/bin/flutterguard.dart`
 
-Supports positional path: `flutterguard scan ./my_project` (no `-p` required). Project auto-discovery walks up from CWD to find `flutterguard.yaml`, `pubspec.yaml`, or `lib/`.
+Supports positional path: `flutterguard scan ./my_project` (no `-p` required). Project auto-discovery walks up from CWD to find `flutterguard.yaml`, `pubspec.yaml`, or `lib/`. Supports --changed-only incremental scan and rule introspection (rules/explain).
 
 Wired rules (11 rule classes, 13 rule IDs):
 - Standards: LargeUnitsRule (3 IDs), MissingConstConstructorRule, PubspecSecurityRule
@@ -44,6 +46,10 @@ Wired rules (11 rule classes, 13 rule IDs):
 ```
 packages/flutterguard_cli/lib/src/
   config_loader.dart         # YAML → ScanConfig typedefs (11 rule configs + architecture)
+  scan_context.dart          # Project/all/target files and scan mode
+  source_workspace.dart      # Shared source/AST cache + scan diagnostics
+  import_graph.dart          # Shared resolved Dart import graph
+  boundary_engine.dart       # Shared layer/module boundary analysis
   file_collector.dart        # Glob file discovery
   project_resolver.dart      # Project auto-discovery (walk-up flutterguard.yaml / pubspec.yaml / lib/)
   static_issue.dart          # StaticIssue + RiskLevel + IssueDomain + Priority
@@ -53,7 +59,10 @@ packages/flutterguard_cli/lib/src/
   path_utils.dart            # Cross-platform path/glob helpers (p.Context abstraction)
   import_utils.dart          # Dart import resolution against collected files
   source_utils.dart          # Analyzer offset → line number conversion
+  rule_meta.dart             # Rule metadata for rules/explain
   rules/
+    catalog.dart                  # Rule metadata + execution source of truth
+    registry.dart                 # RuleRegistry for all 13 rule IDs
     large_units.dart              # large_file, large_class, large_build_method
     lifecycle_resource.dart       # lifecycle_resource_not_disposed
     layer_violation.dart          # layer_violation (architecture layer breaches)
@@ -71,7 +80,7 @@ packages/flutterguard_cli/lib/src/
 Single source of truth: `docs/FLUTTERGUARD_SPEC.md` — read before implementing any feature.
 
 ## Maintenance Rules
-1. New rule: spec entry → config typedef → rule class → fixture → test → wire into scanner.dart
+1. New rule: spec entry → config typedef → rule class → fixture → test → wire into rules/catalog.dart
 2. Always run `melos run analyze` + `melos run test:cli` before committing
 3. Do NOT modify archived packages (core/dio/flutter) — they are frozen references
 4. Do NOT add Flutter widgets, web/cloud infra, or SaaS SDKs

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+- **fix:** Prevent successful no-op full scans and preserve setup-error exit codes in local CI scripts.
+- **fix:** Anchor configuration policy to the target project and require explicitly selected config files.
+- **ci:** Run analyze, tests, and the demo scan against the current checkout on the OS matrix.
+
+## 0.4.1 (2026-07-09)
+
+### Adoption Hardening
+
+- **cli:** Added `flutterguard doctor install` to diagnose executable version, Dart entrypoint, and PATH conflicts.
+- **cli:** Added `flutterguard issue export` to create a local JSON feedback bundle for one finding without uploading source code.
+- **cli:** Added baseline management commands: `baseline stats`, `baseline prune`, and `baseline check --no-growth`.
+- **cli:** Added `flutterguard init --profile` with recommended, strict, migration, IoT security, architecture-only, and performance-only starter profiles.
+- **cli:** `flutterguard init [<path>]` now supports a positional project path.
+- **test:** Expanded CLI coverage for install diagnostics, issue export, baseline management, and config profiles.
+
+## 0.4.0 (2026-07-08)
+
+### CI Adoption
+
+- **cli:** Added baseline creation with `flutterguard baseline create [<path>]`.
+- **cli:** Added `scan --baseline <file>` so legacy issues can be filtered from reports, score, and CI gates.
+- **cli:** Added single-line / next-line suppression comments for false positive control.
+- **cli:** Added SARIF 2.1.0 output via `--format sarif` for GitHub Code Scanning upload.
+- **cli:** JSON summary now includes suppression and baseline suppression counters.
+- **docs:** Updated English, Chinese, and package README files with baseline, SARIF, `rules`, `explain`, and `--changed-only` usage.
+- **release:** Added local source launchers and cross-platform release packaging scripts.
+- **release:** Added tag-triggered GitHub Release workflow for native binaries.
+- **test:** Expanded CLI tests to cover suppression, baseline, missing baseline failures, SARIF, and JSON summary counters.
+
 ## 0.2.0 (2026-06-15)
 
 ### IoT Domain Rules (5 new rules)

CONFIGURATION_STRATEGY.md

@@ -0,0 +1,183 @@
+# FlutterGuard Configuration Strategy
+
+FlutterGuard should be easy to start and precise when a project needs stricter
+architecture gates. The recommended product strategy is: use short CLI responses
+for immediate next steps, and keep this dedicated guide for the complete mental
+model.
+
+## Decision
+
+Use both surfaces, with different responsibilities:
+
+| Surface | Purpose | Content |
+|---------|---------|---------|
+| CLI help and scan responses | Immediate action | The next command, likely fix, and the shortest config path |
+| Dedicated configuration guide | Full explanation | Configuration levels, architecture examples, CI patterns, and troubleshooting |
+
+Do not put the full manual into CLI output. CLI text should answer "what should
+I do next?" in a few lines. The guide should answer "how should this be
+configured for my project?"
+
+## Configuration Levels
+
+### Level 0: Zero Config
+
+Best for first scans and demos.
+
+```bash
+flutterguard scan
+flutterguard scan ./my_flutter_app
+```
+
+Behavior:
+
+- Scans `lib/**`
+- Excludes generated/freezed/mock files
+- Runs all default non-boundary rules
+- Does not enforce layers/modules unless they are declared
+
+Use this level when the user wants a quick signal and has not agreed on project
+architecture boundaries yet. No YAML file is required.
+
+### Level 1: Basic Project Config
+
+Best for normal local development.
+
+```yaml
+include:
+  - lib/**
+
+exclude:
+  - lib/generated/**
+  - lib/**.g.dart
+  - lib/**.freezed.dart
+  - lib/**.mocks.dart
+
+rules:
+  large_file:
+    enabled: true
+    maxLines: 500
+  large_class:
+    enabled: true
+    maxLines: 300
+  large_build_method:
+    enabled: true
+    maxLines: 80
+  lifecycle_resource:
+    enabled: true
+  missing_const_constructor:
+    enabled: true
+  device_lifecycle:
+    enabled: true
+  mqtt_connection:
+    enabled: true
+  ble_scanning:
+    enabled: true
+    maxScanDurationMs: 10000
+  iot_security:
+    enabled: true
+    requireTls: true
+  pubspec_security:
+    enabled: true
+```
+
+Use this level when teams want stable thresholds or custom excludes.
+
+Create it with:
+
+```bash
+flutterguard init
+flutterguard config doctor
+```
+
+### Level 2: CI Gate Config
+
+Best for pull requests and release checks.
+
+```bash
+flutterguard scan . --format json --fail-on high --min-score 80
+```
+
+Recommended policy:
+
+- Start with `--fail-on high`
+- Add `--min-score 80` once the baseline is clean enough
+- Avoid `--fail-on low` early in adoption because it can create noisy rollouts
+- Run `flutterguard config doctor` before adding CI gates
+
+### Level 3: Architecture Config
+
+Best when the project has agreed boundaries.
+
+Create a starter template with:
+
+```bash
+flutterguard init --with-architecture
+```
+
+```yaml
+architecture:
+  layers:
+    - name: presentation
+      path: lib/presentation/**
+      allowed_deps: [domain, core]
+    - name: domain
+      path: lib/domain/**
+      allowed_deps: [core]
+    - name: data
+      path: lib/data/**
+      allowed_deps: [domain, core]
+    - name: core
+      path: lib/core/**
+      allowed_deps: []
+
+  modules:
+    - name: mqtt_feature
+      path: lib/features/mqtt/**
+      allowed_deps: [shared]
+    - name: ble_feature
+      path: lib/features/ble/**
+      allowed_deps: [shared]
+    - name: shared
+      path: lib/shared/**
+      allowed_deps: []
+
+  detect_cycles: true
+  layer_violation:
+    enabled: true
+  module_violation:
+    enabled: true
+```
+
+Important distinction:
+
+- `architecture.layers[].allowed_deps` must reference layer names.
+- `architecture.modules[].allowed_deps` must reference module names.
+- Layers describe technical direction such as presentation/domain/data/core.
+- Modules describe business or feature isolation such as mqtt/ble/shared.
+
+## CLI Response Policy
+
+CLI responses should stay short and operational:
+
+- `--help`: show common commands, option summary, and the four-level config path
+- full scan with no matched files: fail as a setup error and point to include/exclude patterns
+- changed-only scan with no relevant changes: succeed with an empty changed-mode report
+- config parse error: show the failing config key and expected value type
+- CI gate failure: show the failing threshold and direct the user to JSON output
+
+Avoid long explanations in command output. Point to this guide when the user
+needs examples or architecture detail.
+
+## Config Tooling
+
+The core configuration helpers are available as CLI commands:
+
+- `flutterguard init`: write a minimal `flutterguard.yaml`
+- `flutterguard init --with-architecture`: write a layered/module template
+- `flutterguard config print`: show the merged effective config
+- `flutterguard config doctor`: validate globs, unknown deps, empty matches, and
+  architecture overlap
+
+These commands are preferable to adding more prose to `scan`, because they keep
+scan output focused while still making configuration discoverable.

PROJECT_RULES.md

@@ -70,9 +70,10 @@ root/analysis_options.yaml          # strict-casts + strict-inference + 6 lint r
 
 ### 9.3 flutterguard.yaml Config Override Chain
 ```
-root/flutterguard.yaml                          # development defaults (maxLines: 500/300/80)
-└── <user_project>/flutterguard.yaml             # per-scan override (merges over root)
-    └── (injected via CLI --config flag)          # explicit path override
+<target_project>
+├── --config <path>                              # explicit project-relative or absolute config
+├── flutterguard.yaml                            # default project config when no override is given
+└── built-in defaults                            # only when no override is given and the default file is absent
 ```
 
-**Rule**: Root config serves as documented example. User projects may override all fields.
+**Rule**: Config files do not merge across projects. Relative paths resolve from the target project root, and explicitly selected files must exist.