Merge pull request #565 from DevKor-github/feature/issue-537-generated-policy

jjoonleo · web-flow · commit 12bb42e787f5 · 2026-06-28T21:35:58.000+09:00
Align generated Dart file policy
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -199,10 +199,11 @@ class ScheduleRepositoryImpl implements ScheduleRepository {
 
 ## Code Generation Files
 
-**Never manually edit** generated files (`.g.dart`, `.freezed.dart`, `di_setup.config.dart`). These are created by:
+**Never manually edit or commit** generated Dart files (`.g.dart`, `.freezed.dart`, `.mocks.dart`, `di_setup.config.dart`, Widgetbook `*.directories.g.dart`). These are ignored build artifacts created by:
 
 - `build_runner` for JSON serialization, Freezed, Injectable, Drift
-- Regenerate after modifying annotated classes
+- Widgetbook code generation for component directories
+- Regenerate after modifying annotated classes, then stage only source/configuration changes
 
 ## Testing
 
diff --git a/.github/workflows/android-play-closed.yml b/.github/workflows/android-play-closed.yml
@@ -106,7 +106,10 @@ jobs:
       - name: Run code generation
         run: dart run build_runner build --delete-conflicting-outputs
 
-      - name: Verify generated files are current
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
+
+      - name: Verify generation left tracked files unchanged
         run: git diff --exit-code
 
       - name: Analyze
diff --git a/.github/workflows/android-play-internal.yml b/.github/workflows/android-play-internal.yml
@@ -102,7 +102,10 @@ jobs:
       - name: Run code generation
         run: dart run build_runner build --delete-conflicting-outputs
 
-      - name: Verify generated files are current
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
+
+      - name: Verify generation left tracked files unchanged
         run: git diff --exit-code
 
       - name: Analyze
diff --git a/.github/workflows/firebase-hosting-merge.yml b/.github/workflows/firebase-hosting-merge.yml
@@ -32,6 +32,10 @@ jobs:
       - run: flutter pub get
 
       - run: dart run build_runner build -d
+
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
+
       - name: Build Web
         env:
           REST_API_URL: ${{ vars.REST_API_URL }}
diff --git a/.github/workflows/firebase-hosting-pull-request-widgetbook.yml b/.github/workflows/firebase-hosting-pull-request-widgetbook.yml
@@ -37,6 +37,9 @@ jobs:
       - run: dart run build_runner build -d
         working-directory: ${{ env.working-directory }}
 
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
+
       - run: flutter build web --release
         working-directory: ${{ env.working-directory }}
 
diff --git a/.github/workflows/firebase-hosting-pull-request.yml b/.github/workflows/firebase-hosting-pull-request.yml
@@ -35,6 +35,9 @@ jobs:
 
       - run: dart run build_runner build -d
 
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
+
       - name: Build Web
         env:
           REST_API_URL: ${{ vars.REST_API_URL }}
diff --git a/.github/workflows/firebase_hosting-merge-widgetbook.yml b/.github/workflows/firebase_hosting-merge-widgetbook.yml
@@ -34,6 +34,9 @@ jobs:
 
       - run: dart run build_runner build -d
         working-directory: ${{ env.working-directory }} 
+
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
       
       - run: flutter build web --release
         working-directory: ${{ env.working-directory }}
diff --git a/.github/workflows/flutter_test.yml b/.github/workflows/flutter_test.yml
@@ -29,6 +29,8 @@ jobs:
         run: flutter --version
       - name: Run generator
         run: dart run build_runner build --delete-conflicting-outputs
+      - name: Check generated Dart policy
+        run: dart run tool/check_generated_dart_policy.dart
       - name: Analyze
         run: flutter analyze
       - name: Run test with coverage
diff --git a/.gitignore b/.gitignore
@@ -46,6 +46,8 @@ app.*.map.json
 /android/app/profile
 /android/app/release
 
+# Generated Dart outputs are local/CI build artifacts; regenerate them but do
+# not commit them.
 *.g.dart
 *.mocks.dart
 *.config.dart
diff --git a/AGENTS.md b/AGENTS.md
@@ -7,7 +7,7 @@ This Flutter app uses layered code under `lib/`. Platform services, database, DI
 ## Build, Test, and Development Commands
 
 - `flutter pub get`: install Dart and Flutter dependencies.
-- `dart run build_runner build --delete-conflicting-outputs`: regenerate Drift, JSON, Injectable, and other generated files.
+- `dart run build_runner build --delete-conflicting-outputs`: regenerate Drift, JSON, Injectable, Mockito, Freezed, and Widgetbook Dart outputs as ignored local build artifacts.
 - `flutter analyze`: run analyzer checks using `analysis_options.yaml`.
 - `flutter test`: run the full test suite.
 - `flutter test --coverage`: run tests and update `coverage/lcov.info`.
@@ -18,15 +18,15 @@ Do not use `npm test`; the root `package.json` placeholder script intentionally
 
 ## Coding Style & Naming Conventions
 
-Follow `package:flutter_lints/flutter.yaml`. Use standard Dart formatting with two-space indentation; run `dart format lib test` before broad Dart edits are submitted. File names use `snake_case.dart`; classes, blocs, cubits, entities, and models use `PascalCase`; methods and fields use `camelCase`. Keep generated `*.g.dart` and `*.config.dart` files in sync. Preserve clean-architecture boundaries: UI should depend on domain use cases, not remote data sources.
+Follow `package:flutter_lints/flutter.yaml`. Use standard Dart formatting with two-space indentation; run `dart format lib test` before broad Dart edits are submitted. File names use `snake_case.dart`; classes, blocs, cubits, entities, and models use `PascalCase`; methods and fields use `camelCase`. Generated Dart outputs (`*.g.dart`, `*.config.dart`, `*.freezed.dart`, `*.mocks.dart`, including Widgetbook directories output) are ignored build artifacts; regenerate them before analyze/test but do not stage or commit them. Preserve clean-architecture boundaries: UI should depend on domain use cases, not remote data sources.
 
 ## Testing Guidelines
 
 Place tests next to the matching layer path under `test/`, and name files `*_test.dart` (for example, `test/data/repositories/schedule_repository_impl_test.dart`). Prefer unit tests for domain/data changes and widget tests for presentation behavior. For blocs or cubits, cover events, emitted states, and repository failure cases.
 
 ## Commit & Pull Request Guidelines
 
-Commits follow Conventional Commits through commitlint, such as `feat: add schedule refresh` or `chore: update widget layout`; the configured header limit is 500 characters. PRs should include a description, linked issue when applicable, test results, and screenshots or recordings for UI changes. Call out generated-file updates.
+Commits follow Conventional Commits through commitlint, such as `feat: add schedule refresh` or `chore: update widget layout`; the configured header limit is 500 characters. PRs should include a description, linked issue when applicable, test results, and screenshots or recordings for UI changes. Call out generator or source changes when they affect generated Dart output, but do not include ignored generated Dart files in PRs.
 
 ## Agent-Specific Instructions
 
diff --git a/README.md b/README.md
@@ -49,7 +49,7 @@ assets/           shared assets and fonts
 widgetbook/       component catalog app
 ```
 
-Generated Dart files such as `*.g.dart`, `*.freezed.dart`, `*.config.dart`, and `*.mocks.dart` are not committed. Regenerate them locally after dependency changes or code-generator changes.
+Generated Dart files such as `*.g.dart`, `*.freezed.dart`, `*.config.dart`, `*.mocks.dart`, and Widgetbook `*.directories.g.dart` outputs are ignored local/CI build artifacts and are not committed. Regenerate them locally after dependency changes or code-generator changes.
 
 ## First-Time Setup
 
@@ -289,6 +289,9 @@ Run:
 dart run build_runner build --delete-conflicting-outputs
 ```
 
+This recreates ignored local generated Dart artifacts. Do not stage generated
+Dart outputs after running the generator.
+
 If generation still fails, clean generated state and fetch dependencies again:
 
 ```sh
diff --git a/tool/check_generated_dart_policy.dart b/tool/check_generated_dart_policy.dart
@@ -0,0 +1,93 @@
+import 'dart:io';
+
+const _generatedPatterns = [
+  '*.g.dart',
+  '*.config.dart',
+  '*.freezed.dart',
+  '*.mocks.dart',
+];
+
+const _ignoredExamples = [
+  'lib/core/database/database.g.dart',
+  'lib/core/di/di_setup.config.dart',
+  'lib/domain/entities/schedule.freezed.dart',
+  'test/helpers/mock_repositories.mocks.dart',
+  'widgetbook/lib/main.directories.g.dart',
+];
+
+void main() {
+  final repoRoot = _repoRoot();
+  final failures = <String>[];
+
+  final trackedGenerated = _gitLines(repoRoot, [
+    'ls-files',
+    '--',
+    ..._generatedPatterns,
+  ]);
+  if (trackedGenerated.isNotEmpty) {
+    failures.add(
+      'Generated Dart outputs must not be tracked:\n'
+      '${trackedGenerated.map((path) => '  - $path').join('\n')}',
+    );
+  }
+
+  final missingIgnores = <String>[];
+  for (final path in _ignoredExamples) {
+    final result = Process.runSync('git', [
+      'check-ignore',
+      '-q',
+      '--',
+      path,
+    ], workingDirectory: repoRoot);
+    if (result.exitCode != 0) {
+      missingIgnores.add(path);
+    }
+  }
+
+  if (missingIgnores.isNotEmpty) {
+    failures.add(
+      'Generated Dart outputs must stay ignored:\n'
+      '${missingIgnores.map((path) => '  - $path').join('\n')}',
+    );
+  }
+
+  if (failures.isNotEmpty) {
+    stderr.writeln('Generated Dart policy check failed.');
+    stderr.writeln(failures.join('\n\n'));
+    exitCode = 1;
+    return;
+  }
+
+  stdout.writeln(
+    'Generated Dart policy is aligned: outputs are ignored and untracked.',
+  );
+}
+
+String _repoRoot() {
+  final result = Process.runSync('git', ['rev-parse', '--show-toplevel']);
+  if (result.exitCode != 0) {
+    stderr.writeln('Unable to locate git repository root.');
+    stderr.write(result.stderr);
+    exit(1);
+  }
+  return (result.stdout as String).trim();
+}
+
+List<String> _gitLines(String workingDirectory, List<String> arguments) {
+  final result = Process.runSync(
+    'git',
+    arguments,
+    workingDirectory: workingDirectory,
+  );
+  if (result.exitCode != 0) {
+    stderr.writeln('git ${arguments.join(' ')} failed.');
+    stderr.write(result.stderr);
+    exit(1);
+  }
+
+  final output = (result.stdout as String).trim();
+  if (output.isEmpty) {
+    return const [];
+  }
+  return output.split('\n');
+}
diff --git a/widgetbook/.gitignore b/widgetbook/.gitignore
@@ -44,3 +44,10 @@ app.*.map.json
 /android/app/debug
 /android/app/profile
 /android/app/release
+
+# Generated Dart outputs are local/CI build artifacts; regenerate them but do
+# not commit them.
+*.g.dart
+*.mocks.dart
+*.config.dart
+*.freezed.dart
