@aicgen/aicgen 1.0.0-beta.2 → 1.0.0

package/claude.md

@@ -1,4 +1,4 @@
-# @aicgen/aicgen - Development Guidelines
+# my-project - Development Guidelines
 
 **Role:** You are an expert software engineer specialized in typescript.
 **User's Goal:** Build high-quality, maintainable software following strict project guidelines.
@@ -8,13 +8,13 @@
 This project follows structured coding guidelines organized by category:
 
 - **Language**: @.claude/guidelines/language.md
-- **Architecture**: @.claude/guidelines/architecture.md
 - **Testing**: @.claude/guidelines/testing.md
 - **Security**: @.claude/guidelines/security.md
 - **Performance**: @.claude/guidelines/performance.md
 - **API Design**: @.claude/guidelines/api-design.md
 - **Code Style**: @.claude/guidelines/code-style.md
 - **Error Handling**: @.claude/guidelines/error-handling.md
+- **Architecture**: @.claude/guidelines/architecture.md
 - **DevOps**: @.claude/guidelines/devops.md
 - **Best Practices**: @.claude/guidelines/best-practices.md
 - **Design Patterns**: @.claude/guidelines/design-patterns.md

package/config.example.yml

@@ -0,0 +1,129 @@
+# Example AICGEN Configuration File
+#
+# LOCATION: This file should be placed at:
+#   - Windows: C:\Users\YourUsername\.aicgen\config.yml
+#   - Linux/Mac: ~/.aicgen/config.yml
+#
+# INSTALLATION:
+#   Windows:
+#     mkdir C:\Users\%USERNAME%\.aicgen
+#     copy config.example.yml C:\Users\%USERNAME%\.aicgen\config.yml
+#
+#   Linux/Mac:
+#     mkdir -p ~/.aicgen
+#     cp config.example.yml ~/.aicgen/config.yml
+#
+# Configuration priority: Environment Variables > User Config > Defaults
+
+# GitHub repository configuration
+github:
+  owner: aicgen
+  repo: aicgen-data
+
+# AI Provider Configuration
+# Customize models, timeouts, and behavior for different AI providers
+ai:
+  # Google Gemini Configuration
+  gemini:
+    # Model: Use latest Gemini 2.0 or 2.5 models
+    # See: https://ai.google.dev/gemini-api/docs/models
+    model: gemini-2.0-flash-exp
+    # Available models:
+    #   - gemini-2.5-flash (latest, recommended)
+    #   - gemini-2.5-pro (most capable, slower)
+    #   - gemini-2.0-flash-exp (experimental, fast)
+
+    # Request timeout in milliseconds
+    timeout: 30000
+
+    # Maximum retry attempts for failed requests
+    maxRetries: 3
+
+    # Maximum output tokens
+    maxTokens: 8192
+
+  # Anthropic Claude Configuration
+  claude:
+    # Model: Use Claude 3.5 Sonnet or Opus
+    # See: https://docs.anthropic.com/en/docs/about-claude/models
+    model: claude-3-5-sonnet-20241022
+    # Available models:
+    #   - claude-3-5-sonnet-20241022 (best balance, recommended)
+    #   - claude-3-opus-20240229 (most capable, expensive)
+    #   - claude-3-haiku-20240307 (fastest, cheapest)
+
+    # Request timeout in milliseconds
+    timeout: 30000
+
+    # Maximum retry attempts
+    maxRetries: 3
+
+    # Maximum output tokens
+    maxTokens: 8096
+
+    # Temperature (0-1): Lower = more focused, Higher = more creative
+    temperature: 0.7
+
+  # OpenAI Configuration
+  openai:
+    # Model: Use GPT-4o or GPT-4 Turbo
+    # See: https://platform.openai.com/docs/models
+    model: gpt-4o
+    # Available models:
+    #   - gpt-4o (latest, recommended)
+    #   - gpt-4-turbo (high capability)
+    #   - gpt-4 (most capable, expensive)
+    #   - gpt-3.5-turbo (fast, cheaper)
+
+    # Request timeout in milliseconds
+    timeout: 30000
+
+    # Maximum retry attempts
+    maxRetries: 3
+
+    # Maximum output tokens
+    maxTokens: 4096
+
+    # Temperature (0-2): Lower = more focused, Higher = more creative
+    temperature: 0.7
+
+  # Sub-Agent Configuration
+  # These are specialized agents for code review tasks
+  subAgents:
+    # Guideline Checker - Verifies code follows project guidelines
+    guidelineChecker:
+      model: claude-opus-4-5
+      # Use lower temperature for strict guideline checking
+      temperature: 0.3
+
+    # Architecture Reviewer - Reviews architectural decisions
+    architectureReviewer:
+      model: claude-sonnet-4-5
+      # Balanced temperature for architecture review
+      temperature: 0.5
+
+    # Security Auditor - Identifies security vulnerabilities
+    securityAuditor:
+      model: claude-opus-4-5
+      # Lower temperature for thorough security analysis
+      temperature: 0.3
+
+# Alternative: Use environment variables instead
+# Export these in your shell profile (.bashrc, .zshrc, etc.):
+#
+# # Gemini
+# export AICGEN_GEMINI_MODEL=gemini-2.5-pro
+# export AICGEN_GEMINI_TIMEOUT=60000
+# export AICGEN_GEMINI_MAX_RETRIES=5
+#
+# # Claude
+# export AICGEN_CLAUDE_MODEL=claude-3-opus-20240229
+# export AICGEN_CLAUDE_TEMPERATURE=0.5
+#
+# # OpenAI
+# export AICGEN_OPENAI_MODEL=gpt-4-turbo
+# export AICGEN_OPENAI_TEMPERATURE=0.8
+#
+# # Sub-Agents
+# export AICGEN_SUBAGENT_GUIDELINE_MODEL=claude-opus-4-5
+# export AICGEN_SUBAGENT_GUIDELINE_TEMP=0.2

package/config.yml

@@ -0,0 +1,38 @@
+github:
+  owner: aicgen
+  repo: aicgen-data
+
+# AI Provider Configuration
+ai:
+  gemini:
+    model: gemini-2.0-flash-exp
+    timeout: 30000
+    maxRetries: 3
+    maxTokens: 8192
+
+  claude:
+    model: claude-3-5-sonnet-20241022
+    timeout: 30000
+    maxRetries: 3
+    maxTokens: 8096
+    temperature: 0.7
+
+  openai:
+    model: gpt-4o
+    timeout: 30000
+    maxRetries: 3
+    maxTokens: 4096
+    temperature: 0.7
+
+  subAgents:
+    guidelineChecker:
+      model: claude-opus-4-5
+      temperature: 0.3
+
+    architectureReviewer:
+      model: claude-sonnet-4-5
+      temperature: 0.5
+
+    securityAuditor:
+      model: claude-opus-4-5
+      temperature: 0.3

package/data/guideline-mappings.yml

@@ -332,6 +332,134 @@ javascript-testing:
     - testing
     - jest
   category: Language
+dart-basics:
+  path: language/dart/basics.md
+  languages:
+    - dart
+  levels:
+    - basic
+    - standard
+    - expert
+    - full
+  tags:
+    - dart
+    - fundamentals
+    - null-safety
+  category: Language
+dart-async:
+  path: language/dart/async.md
+  languages:
+    - dart
+  levels:
+    - basic
+    - standard
+    - expert
+    - full
+  tags:
+    - dart
+    - async
+    - futures
+    - streams
+  category: Language
+dart-error-handling:
+  path: language/dart/error-handling.md
+  languages:
+    - dart
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - dart
+    - errors
+    - exceptions
+  category: Language
+dart-testing:
+  path: language/dart/testing.md
+  languages:
+    - dart
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - dart
+    - testing
+    - flutter
+  category: Language
+swift-basics:
+  path: language/swift/basics.md
+  languages:
+    - swift
+  levels:
+    - basic
+    - standard
+    - expert
+    - full
+  tags:
+    - swift
+    - fundamentals
+    - optionals
+    - value-types
+  category: Language
+swift-concurrency:
+  path: language/swift/concurrency.md
+  languages:
+    - swift
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - swift
+    - async
+    - actors
+    - structured-concurrency
+    - task
+  category: Language
+swift-swiftui-mvvm:
+  path: language/swift/swiftui-mvvm.md
+  languages:
+    - swift
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - swift
+    - swiftui
+    - mvvm
+    - state-management
+    - combine
+  category: Language
+swift-testing:
+  path: language/swift/testing.md
+  languages:
+    - swift
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - swift
+    - testing
+    - xctest
+    - swift-testing
+  category: Language
+swift-error-handling:
+  path: language/swift/error-handling.md
+  languages:
+    - swift
+  levels:
+    - standard
+    - expert
+    - full
+  tags:
+    - swift
+    - errors
+    - throws
+    - result
+  category: Language
 microservices-boundaries:
   path: architecture/microservices/boundaries.md
   architectures:

package/data/language/dart/async.md

@@ -0,0 +1,289 @@
+# Async Programming in Dart
+
+## Futures and async/await
+
+```dart
+// ✅ Async function returns Future
+Future<User> fetchUser(String id) async {
+  final response = await http.get('/api/users/$id');
+  return User.fromJson(response.data);
+}
+
+// ✅ Handle errors with try-catch
+Future<User> fetchUserSafely(String id) async {
+  try {
+    final response = await http.get('/api/users/$id');
+    return User.fromJson(response.data);
+  } catch (e) {
+    print('Failed to fetch user: $e');
+    rethrow;
+  }
+}
+
+// ❌ Don't forget await
+Future<void> badExample() async {
+  final user = fetchUser('123');   // Missing await!
+  print(user);                     // Prints: Instance of 'Future<User>'
+}
+
+// ✅ Correct
+Future<void> goodExample() async {
+  final user = await fetchUser('123');
+  print(user.name);                // Prints: Alice
+}
+```
+
+## Parallel Execution
+
+```dart
+// ❌ Sequential - slow
+Future<void> sequential() async {
+  final user = await fetchUser('1');       // 100ms
+  final posts = await fetchPosts('1');     // 150ms
+  final comments = await fetchComments('1'); // 120ms
+  // Total: 370ms
+}
+
+// ✅ Parallel - fast
+Future<void> parallel() async {
+  final results = await Future.wait([
+    fetchUser('1'),
+    fetchPosts('1'),
+    fetchComments('1'),
+  ]);
+  // Total: 150ms (longest operation)
+
+  final user = results[0] as User;
+  final posts = results[1] as List<Post>;
+  final comments = results[2] as List<Comment>;
+}
+
+// ✅ With better typing using records (Dart 3.0+)
+Future<(User, List<Post>, List<Comment>)> fetchUserData(String id) async {
+  final (user, posts, comments) = await (
+    fetchUser(id),
+    fetchPosts(id),
+    fetchComments(id),
+  ).wait;
+
+  return (user, posts, comments);
+}
+```
+
+## Future Methods
+
+```dart
+// timeout - fail if takes too long
+Future<User> fetchWithTimeout(String id) async {
+  return fetchUser(id).timeout(
+    const Duration(seconds: 5),
+    onTimeout: () => throw TimeoutException('Request timed out'),
+  );
+}
+
+// catchError - handle errors without try-catch
+final user = await fetchUser('123').catchError((error) {
+  print('Error: $error');
+  return User.guest();             // Fallback value
+});
+
+// then - chain operations (prefer async/await)
+fetchUser('123')
+  .then((user) => user.name)
+  .then((name) => print(name));
+
+// whenComplete - always runs (like finally)
+await fetchUser('123').whenComplete(() {
+  print('Request completed');
+});
+```
+
+## Streams
+
+```dart
+// Create stream
+Stream<int> countStream(int max) async* {
+  for (int i = 1; i <= max; i++) {
+    await Future.delayed(const Duration(seconds: 1));
+    yield i;
+  }
+}
+
+// ✅ Listen to stream
+final subscription = countStream(5).listen(
+  (count) {
+    print('Count: $count');
+  },
+  onError: (error) {
+    print('Error: $error');
+  },
+  onDone: () {
+    print('Stream completed');
+  },
+);
+
+// Cancel subscription
+await subscription.cancel();
+
+// ✅ Async for loop
+Future<void> processStream() async {
+  await for (final count in countStream(5)) {
+    print('Count: $count');
+  }
+  print('Done');
+}
+```
+
+## Stream Transformations
+
+```dart
+// Transform stream data
+Stream<String> getUserNames() {
+  return fetchUsersStream()
+    .map((user) => user.name)
+    .where((name) => name.isNotEmpty);
+}
+
+// Async map
+Stream<User> enrichUsers(Stream<String> userIds) {
+  return userIds.asyncMap((id) async {
+    return await fetchUser(id);
+  });
+}
+
+// Combine streams
+final combined = StreamGroup.merge([stream1, stream2, stream3]);
+
+// Buffer events
+final buffered = stream.transform(
+  StreamTransformer.fromHandlers(
+    handleData: (data, sink) {
+      sink.add(data);
+    },
+  ),
+);
+```
+
+## StreamController
+
+```dart
+class ChatService {
+  final _messagesController = StreamController<Message>.broadcast();
+
+  Stream<Message> get messages => _messagesController.stream;
+
+  void sendMessage(Message message) {
+    _messagesController.add(message);
+  }
+
+  void dispose() {
+    _messagesController.close();
+  }
+}
+
+// Usage
+final chat = ChatService();
+
+final subscription = chat.messages.listen((message) {
+  print('New message: ${message.text}');
+});
+
+chat.sendMessage(Message(text: 'Hello'));
+
+// Clean up
+await subscription.cancel();
+chat.dispose();
+```
+
+## Isolates (Heavy Computation)
+
+```dart
+// Run expensive computation in isolate
+Future<int> calculateInIsolate(int n) async {
+  return await Isolate.run(() {
+    int result = 0;
+    for (int i = 0; i < n; i++) {
+      result += i;
+    }
+    return result;
+  });
+}
+
+// ✅ For CPU-intensive tasks
+Future<Image> processImage(File imageFile) async {
+  final bytes = await imageFile.readAsBytes();
+
+  // Run in isolate to avoid blocking UI
+  final processed = await Isolate.run(() {
+    return applyFilters(bytes);
+  });
+
+  return Image.memory(processed);
+}
+```
+
+## Completer
+
+```dart
+// Create Future manually
+class DatabaseConnection {
+  final Completer<void> _readyCompleter = Completer();
+
+  Future<void> get ready => _readyCompleter.future;
+
+  void connect() async {
+    try {
+      await _performConnection();
+      _readyCompleter.complete();
+    } catch (e) {
+      _readyCompleter.completeError(e);
+    }
+  }
+}
+
+// Usage
+final db = DatabaseConnection();
+db.connect();
+await db.ready;                  // Wait until connected
+```
+
+## Error Handling
+
+```dart
+// ✅ Use try-catch with async/await
+Future<void> safeOperation() async {
+  try {
+    await riskyOperation();
+  } on NetworkException catch (e) {
+    print('Network error: ${e.message}');
+  } on TimeoutException {
+    print('Operation timed out');
+  } catch (e, stackTrace) {
+    print('Unexpected error: $e');
+    print('Stack trace: $stackTrace');
+    rethrow;
+  }
+}
+
+// ✅ Handle stream errors
+stream.listen(
+  (data) => process(data),
+  onError: (error) {
+    if (error is NetworkException) {
+      reconnect();
+    }
+  },
+);
+```
+
+## Best Practices
+
+- Always use `async`/`await` for readability
+- Run independent operations in parallel with `Future.wait`
+- Set timeouts for network operations
+- Cancel subscriptions when done
+- Use isolates for CPU-intensive work
+- Handle errors explicitly
+- Close StreamControllers when finished
+- Use `async*` and `yield` for generating stream data
+- Prefer `await for` over `listen` for sequential processing