froggy-docs 1.1.1 → 1.1.4

package/lib/src/cli_runner.dart

@@ -0,0 +1,123 @@
+import 'dart:io';
+import 'package:args/args.dart';
+import 'package:froggy_docs/src/watcher_engine.dart';
+import 'package:froggy_docs/src/web_server.dart';
+import 'package:froggy_docs/src/parser_engine.dart';
+
+class CliRunner {
+  void run(List<String> arguments) async {
+    final parser = ArgParser();
+    parser.addCommand('watch');
+    parser.addCommand('serve');
+    parser.addCommand('build');
+    parser.addOption(
+      'port',
+      abbr: 'p',
+      help: 'Port for server',
+      defaultsTo: '8080',
+    );
+    parser.addOption(
+      'proxy',
+      abbr: 'x',
+      help: 'Proxy API requests to this URL (e.g., http://localhost:3000)',
+      defaultsTo: '',
+    );
+    parser.addOption(
+      'output',
+      abbr: 'o',
+      help: 'Output path for generated JSON spec (default: frontend/web/froggy_docs.json)',
+      defaultsTo: 'frontend/web/froggy_docs.json',
+    );
+    parser.addOption(
+      'ignore',
+      help: 'Glob pattern for paths to exclude from watching (e.g., "**/*.g.dart")',
+      defaultsTo: '',
+    );
+
+    try {
+      final results = parser.parse(arguments);
+
+      final outputPath = results['output'] as String;
+      final ignorePattern = results['ignore'] as String;
+
+      if (results.command?.name == 'watch') {
+        print('🐸 FroggyDocs is watching your API project...');
+        final watcher = WatcherEngine(outputPath: outputPath, ignorePattern: ignorePattern);
+        watcher.startWatching(Directory.current.path);
+      } else if (results.command?.name == 'serve') {
+        final port = int.parse(results['port'] as String);
+        final proxyUrl = results['proxy'] as String;
+        print('🐸 Starting FroggyDocs server with live reload...');
+        if (proxyUrl.isNotEmpty) {
+          print('🔄 Proxy enabled: API requests will be forwarded to $proxyUrl');
+        }
+
+        await startServer(port: port, proxyUrl: proxyUrl);
+        final watcher = WatcherEngine(outputPath: outputPath, ignorePattern: ignorePattern);
+        watcher.startWatching(Directory.current.path);
+      } else if (results.command?.name == 'build') {
+        print('🐸 Building static FroggyDocs site...');
+        final parser = ParserEngine();
+        parser.setOutputPath(outputPath);
+        _buildStaticSite(parser, Directory.current.path);
+        print('✅ Build complete. Output: $outputPath');
+      } else {
+        _printHelp();
+      }
+    } catch (e) {
+      print('Error: ${e.toString()}');
+      exit(1);
+    }
+  }
+
+  void _buildStaticSite(ParserEngine parser, String directoryPath) {
+    final dir = Directory(directoryPath);
+    try {
+      dir.listSync(recursive: true).forEach((entity) {
+        if (entity is File) {
+          final normalizedPath = entity.path.replaceAll('\\', '/');
+          if (!_shouldIgnore(normalizedPath)) {
+            parser.parseFile(entity.path);
+          }
+        }
+      });
+    } catch (e) {
+      print('⚠️  Warning during build: $e');
+    }
+  }
+
+  bool _shouldIgnore(String path) {
+    return path.contains('/.dart_tool/') ||
+        path.contains('/frontend/') ||
+        path.contains('/node_modules/') ||
+        path.contains('/.git/') ||
+        path.endsWith('.json') ||
+        path.endsWith('.md');
+  }
+
+  void _printHelp() {
+    print('''
+🐸 FroggyDocs v1.0.0
+
+Usage:
+  froggy_docs serve       Start server with live documentation
+  froggy_docs watch       Watch for changes and regenerate docs
+  froggy_docs build       Generate static documentation without starting server
+
+Options:
+  -p, --port <port>       Port number (default: 8080)
+  -x, --proxy <url>       Proxy API requests to this URL
+  -o, --output <path>     Output path for generated JSON spec
+                          (default: frontend/web/froggy_docs.json)
+  --ignore <glob>         Glob pattern for paths to exclude from watching
+                          (e.g., "**/*.g.dart")
+  -h, --help              Show this help message
+
+Examples:
+  froggy_docs serve --port 3000
+  froggy_docs serve --output docs/api.json
+  froggy_docs build --output docs/froggy_docs.json
+  froggy_docs watch --ignore "**/*.g.dart"
+''');
+  }
+}

package/lib/src/parser_engine.dart

@@ -36,6 +36,14 @@ class ParserEngine {
     'options',
   };
 
+  String _outputPath = 'frontend/web/froggy_docs.json';
+
+  void setOutputPath(String path) {
+    _outputPath = path;
+  }
+
+  String get outputPath => _outputPath;
+
   final Map<String, dynamic> _baseSpec = {
     "openapi": "3.0.0",
     "info": {
@@ -104,6 +112,37 @@ class ParserEngine {
     }
   }
 
+  dynamic _parseDefaultValue(String value, String? type) {
+    switch (type?.toString().toLowerCase()) {
+      case 'number':
+      case 'integer':
+      case 'int':
+        return num.tryParse(value) ?? value;
+      case 'boolean':
+        return value.toLowerCase() == 'true';
+      default:
+        return value;
+    }
+  }
+
+  void _attachResponseExample(
+    String code,
+    dynamic jsonData,
+    Map<String, Map<String, dynamic>> responseSchemas,
+  ) {
+    final response = responseSchemas[code]!;
+    if (!response.containsKey('content')) {
+      response['content'] = <String, dynamic>{
+        "application/json": <String, dynamic>{
+          "schema": <String, dynamic>{"type": "object"},
+        },
+      };
+    }
+    final contentMap = response['content'] as Map;
+    final appJsonMap = contentMap['application/json'] as Map;
+    appJsonMap['example'] = jsonData;
+  }
+
   void parseFile(String filePath) {
     _errors.clear();
 
@@ -132,8 +171,15 @@ class ParserEngine {
     bool hasAuth = false;
     List<String> currentTags = [];
     List<Map<String, String>> requestBodyFields = [];
+    List<Map<String, String>> requestFileFields = [];
+    List<Map<String, dynamic>> queryParams = [];
+    List<Map<String, dynamic>> headerParams = [];
+    Map<String, Map<String, dynamic>> responseSchemas = {};
+    String? pendingResponseCode;
     bool isReadingBodyJson = false;
+    bool isReadingResponseJson = false;
     StringBuffer bodyJsonBuffer = StringBuffer();
+    StringBuffer responseJsonBuffer = StringBuffer();
     int lineNumber = 0;
 
     String inferType(dynamic value) {
@@ -146,6 +192,44 @@ class ParserEngine {
     }
 
     void flushEndpoint() {
+      // Defensively flush any pending JSON buffers (handles end-of-file cases).
+      if (isReadingBodyJson && bodyJsonBuffer.isNotEmpty) {
+        isReadingBodyJson = false;
+        try {
+          final jsonData = jsonDecode(bodyJsonBuffer.toString());
+          if (jsonData is Map) {
+            for (final entry in jsonData.entries) {
+              requestBodyFields.add({
+                'name': entry.key.toString(),
+                'type': inferType(entry.value),
+                'desc': 'Inferred from JSON',
+              });
+            }
+          }
+        } catch (e) {
+          _errors.add('Invalid JSON in @body-json at line $lineNumber: $e');
+        }
+        bodyJsonBuffer.clear();
+      }
+
+      if (isReadingResponseJson &&
+          responseJsonBuffer.isNotEmpty &&
+          pendingResponseCode != null) {
+        isReadingResponseJson = false;
+        try {
+          final jsonData = jsonDecode(responseJsonBuffer.toString());
+          _attachResponseExample(
+            pendingResponseCode!,
+            jsonData,
+            responseSchemas,
+          );
+        } catch (e) {
+          _errors
+              .add('Invalid JSON in @response-json at line $lineNumber: $e');
+        }
+        responseJsonBuffer.clear();
+      }
+
       if (currentMethod != null) {
         if (currentPath == null) {
           _errors.add('Endpoint defined without path at line $lineNumber');
@@ -153,8 +237,15 @@ class ParserEngine {
           currentPath = null;
           description = '';
           hasAuth = false;
+          currentTags.clear();
           requestBodyFields.clear();
+          requestFileFields.clear();
+          queryParams.clear();
+          headerParams.clear();
+          responseSchemas.clear();
+          pendingResponseCode = null;
           bodyJsonBuffer.clear();
+          responseJsonBuffer.clear();
           return;
         }
 
@@ -166,8 +257,15 @@ class ParserEngine {
           currentPath = null;
           description = '';
           hasAuth = false;
+          currentTags.clear();
           requestBodyFields.clear();
+          requestFileFields.clear();
+          queryParams.clear();
+          headerParams.clear();
+          responseSchemas.clear();
+          pendingResponseCode = null;
           bodyJsonBuffer.clear();
+          responseJsonBuffer.clear();
           return;
         }
 
@@ -178,11 +276,16 @@ class ParserEngine {
           fileEndpoints[path] = {};
         }
 
+        final responses = <String, dynamic>{};
+        if (responseSchemas.isEmpty) {
+          responses['200'] = {"description": "Successful response"};
+        } else {
+          responses.addAll(responseSchemas);
+        }
+
         Map<String, dynamic> endpointData = {
           "summary": description.isNotEmpty ? description : "No description",
-          "responses": {
-            "200": {"description": "Successful response"},
-          },
+          "responses": responses,
         };
 
         if (currentTags.isNotEmpty) {
@@ -195,25 +298,93 @@ class ParserEngine {
           ];
         }
 
-        if (requestBodyFields.isNotEmpty) {
-          Map<String, dynamic> properties = {};
+        final parameters = <Map<String, dynamic>>[];
+        for (var qp in queryParams) {
+          final param = <String, dynamic>{
+            "name": qp['name'],
+            "in": "query",
+            "description": qp['desc'] ?? '',
+            "schema": <String, dynamic>{
+              "type": (qp['type'] ?? 'string').toString().toLowerCase(),
+            },
+          };
+          if (qp['default'] != null && (qp['default'] as String).isNotEmpty) {
+            param['schema']['default'] = _parseDefaultValue(
+              qp['default'] as String,
+              qp['type'],
+            );
+          }
+          parameters.add(param);
+        }
+        for (var hp in headerParams) {
+          parameters.add({
+            "name": hp['name'],
+            "in": "header",
+            "description": hp['desc'] ?? '',
+            "schema": {
+              "type": (hp['type'] ?? 'string').toString().toLowerCase(),
+            },
+          });
+        }
+        final pathParamMatches = RegExp(r'\{(\w+)\}').allMatches(path);
+        for (final match in pathParamMatches) {
+          final paramName = match.group(1)!;
+          if (!parameters.any((p) => p['name'] == paramName && p['in'] == 'path')) {
+            parameters.insert(0, {
+              "name": paramName,
+              "in": "path",
+              "required": true,
+              "description": '',
+              "schema": {"type": "string"},
+            });
+          }
+        }
+
+        if (parameters.isNotEmpty) {
+          endpointData['parameters'] = parameters;
+        }
+
+        if (requestBodyFields.isNotEmpty || requestFileFields.isNotEmpty) {
+          final properties = <String, dynamic>{};
           for (var field in requestBodyFields) {
-            final fieldName = field['name'];
-            if (fieldName != null && fieldName.isNotEmpty) {
-              properties[fieldName] = {
-                "type": (field['type'] ?? 'string').toString().toLowerCase(),
-                "description": field['desc'] ?? '',
-              };
-            }
+            final fieldName = field['name']!;
+            properties[fieldName] = {
+              "type": (field['type'] ?? 'string').toString().toLowerCase(),
+              "description": field['desc'] ?? '',
+            };
+          }
+          for (var field in requestFileFields) {
+            final fieldName = field['name']!;
+            properties[fieldName] = {
+              "type": "string",
+              "format": "binary",
+              "description": field['desc'] ?? '',
+            };
           }
 
-          endpointData['requestBody'] = {
-            "content": {
-              "application/json": {
-                "schema": {"type": "object", "properties": properties},
+          if (requestFileFields.isNotEmpty) {
+            endpointData['requestBody'] = {
+              "content": <String, dynamic>{
+                "multipart/form-data": <String, dynamic>{
+                  "schema": <String, dynamic>{
+                    "type": "object",
+                    "properties": properties,
+                  },
+                },
               },
-            },
-          };
+            };
+          } else {
+            endpointData['requestBody'] = {
+              "content": <String, dynamic>{
+                "application/json": <String, dynamic>{
+                  "schema": <String, dynamic>{
+                    "type": "object",
+                    "properties": properties,
+                  },
+                },
+              },
+            };
+          }
         }
 
         fileEndpoints[path][method] = endpointData;
@@ -225,7 +396,13 @@ class ParserEngine {
       hasAuth = false;
       currentTags.clear();
       requestBodyFields.clear();
+      requestFileFields.clear();
+      queryParams.clear();
+      headerParams.clear();
+      responseSchemas.clear();
+      pendingResponseCode = null;
       bodyJsonBuffer.clear();
+      responseJsonBuffer.clear();
     }
 
     for (final l in lines) {
@@ -259,6 +436,29 @@ class ParserEngine {
         }
       }
 
+      if (isReadingResponseJson) {
+        if (!_isCommentLine(trimmed, commentPrefix)) {
+          isReadingResponseJson = false;
+          if (responseJsonBuffer.isNotEmpty && pendingResponseCode != null) {
+            try {
+              final jsonData = jsonDecode(responseJsonBuffer.toString());
+              _attachResponseExample(
+                pendingResponseCode!,
+                jsonData,
+                responseSchemas,
+              );
+            } catch (e) {
+              _errors.add('Invalid response JSON at line $lineNumber: $e');
+            }
+          }
+          responseJsonBuffer.clear();
+        } else {
+          final commentText = _extractCommentText(trimmed, commentPrefix);
+          responseJsonBuffer.write(commentText);
+          continue;
+        }
+      }
+
       if (!_isCommentLine(trimmed, commentPrefix)) {
         if (trimmed.isNotEmpty) {
           flushEndpoint();
@@ -280,7 +480,10 @@ class ParserEngine {
         flushEndpoint();
         if (parts.length >= 3) {
           currentMethod = parts[1].toUpperCase();
-          currentPath = parts[2];
+          currentPath = parts[2].replaceAllMapped(
+            RegExp(r':(\w+)'),
+            (m) => '{${m.group(1)}}',
+          );
         } else {
           _errors.add('@api requires method and path at line $lineNumber');
         }
@@ -309,7 +512,24 @@ class ParserEngine {
             'desc': fieldDesc,
           });
         } else {
-          _errors.add('@body requires field name and type at line $lineNumber');
+          _errors.add(
+            '@body requires field name and type at line $lineNumber',
+          );
+        }
+      } else if (tag == '@file') {
+        if (parts.length >= 3) {
+          final fieldName = parts[1];
+          final fileType = parts[2];
+          final fieldDesc = parts.length > 3 ? parts.sublist(3).join(' ') : '';
+          requestFileFields.add({
+            'name': fieldName,
+            'type': fileType,
+            'desc': fieldDesc,
+          });
+        } else {
+          _errors.add(
+            '@file requires field name and type at line $lineNumber',
+          );
         }
       } else if (tag == '@body-file') {
         if (parts.length >= 2) {
@@ -334,6 +554,92 @@ class ParserEngine {
       } else if (tag == '@body-json') {
         isReadingBodyJson = true;
         bodyJsonBuffer.clear();
+      } else if (tag == '@response') {
+        if (parts.length >= 3) {
+          pendingResponseCode = parts[1];
+          final responseType = parts[2];
+          final responseDesc =
+              parts.length > 3 ? parts.sublist(3).join(' ') : '';
+          final lowerType = responseType.toLowerCase();
+          final schemaType = (lowerType == 'array') ? 'array' : 'object';
+          responseSchemas[pendingResponseCode!] = {
+            "description": responseDesc,
+            "content": <String, dynamic>{
+              "application/json": <String, dynamic>{
+                "schema": <String, dynamic>{"type": schemaType},
+              },
+            },
+          };
+        } else {
+          _errors.add(
+            '@response requires status code and type at line $lineNumber',
+          );
+        }
+      } else if (tag == '@response-json') {
+        if (pendingResponseCode != null &&
+            responseSchemas.containsKey(pendingResponseCode)) {
+          final rest = commentText.replaceFirst('@response-json', '').trim();
+          if (rest.isNotEmpty) {
+            try {
+              final jsonData = jsonDecode(rest);
+              _attachResponseExample(
+                pendingResponseCode!,
+                jsonData,
+                responseSchemas,
+              );
+            } catch (_) {
+              isReadingResponseJson = true;
+              responseJsonBuffer.clear();
+              responseJsonBuffer.write(rest);
+            }
+          } else {
+            isReadingResponseJson = true;
+            responseJsonBuffer.clear();
+          }
+        }
+      } else if (tag == '@query') {
+        if (parts.length >= 3) {
+          final name = parts[1];
+          final type = parts[2];
+          String desc = '';
+          String? defaultValue;
+
+          final rest = parts.length > 3 ? parts.sublist(3).join(' ') : '';
+          final defaultMatch =
+              RegExp(r'\(default:\s*(.+?)\)').firstMatch(rest);
+          if (defaultMatch != null) {
+            defaultValue = defaultMatch.group(1);
+            desc = rest.replaceFirst(defaultMatch.group(0)!, '').trim();
+          } else {
+            desc = rest;
+          }
+
+          queryParams.add({
+            'name': name,
+            'type': type,
+            'desc': desc,
+            'default': defaultValue,
+          });
+        } else {
+          _errors.add(
+            '@query requires name and type at line $lineNumber',
+          );
+        }
+      } else if (tag == '@header') {
+        if (parts.length >= 3) {
+          final name = parts[1];
+          final type = parts[2];
+          final desc = parts.length > 3 ? parts.sublist(3).join(' ') : '';
+          headerParams.add({
+            'name': name,
+            'type': type,
+            'desc': desc,
+          });
+        } else {
+          _errors.add(
+            '@header requires name and type at line $lineNumber',
+          );
+        }
       }
     }
 
@@ -341,7 +647,7 @@ class ParserEngine {
 
     if (_errors.isNotEmpty) {
       for (final error in _errors) {
-        print('⚠️ $error');
+        print('⚠️  $error');
       }
     }
 
@@ -370,12 +676,11 @@ class ParserEngine {
 
     _baseSpec['paths'] = fullPaths;
 
-    // Add tags if any
     if (_tags.isNotEmpty) {
       _baseSpec['tags'] = _tags.map((t) => {"name": t}).toList();
     }
 
-    final swaggerFile = File('frontend/web/froggy_docs.json');
+    final swaggerFile = File(_outputPath);
     if (!swaggerFile.parent.existsSync()) {
       swaggerFile.parent.createSync(recursive: true);
     }
@@ -387,4 +692,45 @@ class ParserEngine {
       '🐸 FroggyDocs: Updated documentation. Total paths: ${fullPaths.length}',
     );
   }
+
+  Map<String, dynamic> generateSpec() {
+    final Map<String, dynamic> fullPaths = {};
+    for (final fileMap in _fileRegistry.values) {
+      for (final entry in fileMap.entries) {
+        final path = entry.key;
+        final methods = entry.value;
+        if (fullPaths[path] == null) {
+          fullPaths[path] = {};
+        }
+        (fullPaths[path] as Map).addAll(methods);
+      }
+    }
+    final spec = Map<String, dynamic>.from(_baseSpec);
+    spec['paths'] = fullPaths;
+    if (_tags.isNotEmpty) {
+      spec['tags'] = _tags.map((t) => {"name": t}).toList();
+    }
+    return spec;
+  }
+
+  void clearRegistry() {
+    _fileRegistry.clear();
+    _tags.clear();
+    _errors.clear();
+  }
+
+  int get pathCount {
+    final Map<String, dynamic> fullPaths = {};
+    for (final fileMap in _fileRegistry.values) {
+      for (final entry in fileMap.entries) {
+        final path = entry.key;
+        final methods = entry.value;
+        if (fullPaths[path] == null) {
+          fullPaths[path] = {};
+        }
+        (fullPaths[path] as Map).addAll(methods);
+      }
+    }
+    return fullPaths.length;
+  }
 }