froggy-docs 1.0.0

package/lib/src/parser_engine.dart

@@ -0,0 +1,390 @@
+import 'dart:io';
+import 'dart:convert';
+import 'package:path/path.dart' as p;
+
+class ParserEngine {
+  static final Map<String, Map<String, dynamic>> _fileRegistry = {};
+
+  static const Set<String> supportedExtensions = {
+    '.dart',
+    '.js',
+    '.ts',
+    '.jsx',
+    '.tsx',
+    '.py',
+    '.go',
+    '.rs',
+    '.java',
+    '.kt',
+    '.scala',
+    '.php',
+    '.rb',
+    '.cs',
+    '.c',
+    '.cpp',
+    '.h',
+    '.hpp',
+  };
+
+  static const Set<String> validMethods = {
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'head',
+    'options',
+  };
+
+  final Map<String, dynamic> _baseSpec = {
+    "openapi": "3.0.0",
+    "info": {
+      "title": "FroggyDocs Generated API",
+      "version": "1.0.0",
+      "description": "Auto-generated by FroggyDocs",
+    },
+    "paths": {},
+    "components": {
+      "securitySchemes": {
+        "bearerAuth": {
+          "type": "http",
+          "scheme": "bearer",
+          "bearerFormat": "JWT",
+        },
+      },
+    },
+  };
+
+  final List<String> _errors = [];
+  final Set<String> _tags = {};
+
+  String _getCommentPrefix(String filePath) {
+    final ext = p.extension(filePath).toLowerCase();
+    return switch (ext) {
+      '.dart' => '//',
+      '.js' || '.jsx' || '.ts' || '.tsx' => '//',
+      '.py' || '.rb' => '#',
+      '.go' ||
+      '.rs' ||
+      '.c' ||
+      '.cpp' ||
+      '.h' ||
+      '.hpp' ||
+      '.java' ||
+      '.kt' ||
+      '.scala' ||
+      '.cs' => '//',
+      '.php' => '//',
+      _ => '//',
+    };
+  }
+
+  bool _isCommentLine(String line, String prefix) {
+    if (prefix == '//') {
+      return line.trimLeft().startsWith('//');
+    } else if (prefix == '#') {
+      return line.trimLeft().startsWith('#');
+    }
+    return line.trimLeft().startsWith(prefix);
+  }
+
+  String _extractCommentText(String line, String prefix) {
+    if (prefix == '//') {
+      return line.replaceFirst(RegExp(r'^//\s*'), '').trim();
+    } else if (prefix == '#') {
+      return line.replaceFirst(RegExp(r'^#\s*'), '').trim();
+    }
+    return line.replaceFirst(RegExp(r'^$prefix\s*'), '').trim();
+  }
+
+  void removeFile(String filePath) {
+    if (_fileRegistry.containsKey(filePath)) {
+      _fileRegistry.remove(filePath);
+      _generateSwaggerFile();
+    }
+  }
+
+  void parseFile(String filePath) {
+    _errors.clear();
+
+    if (filePath.contains('frontend/') || filePath.contains('.dart_tool')) {
+      return;
+    }
+
+    final file = File(filePath);
+    if (!file.existsSync()) {
+      removeFile(filePath);
+      return;
+    }
+
+    final ext = p.extension(filePath).toLowerCase();
+    if (!supportedExtensions.contains(ext)) {
+      return;
+    }
+
+    final lines = file.readAsLinesSync();
+    final commentPrefix = _getCommentPrefix(filePath);
+    Map<String, dynamic> fileEndpoints = {};
+
+    String? currentMethod;
+    String? currentPath;
+    String description = '';
+    bool hasAuth = false;
+    List<String> currentTags = [];
+    List<Map<String, String>> requestBodyFields = [];
+    bool isReadingBodyJson = false;
+    StringBuffer bodyJsonBuffer = StringBuffer();
+    int lineNumber = 0;
+
+    String inferType(dynamic value) {
+      if (value is String) return 'string';
+      if (value is num) return 'number';
+      if (value is bool) return 'boolean';
+      if (value is List) return 'array';
+      if (value is Map) return 'object';
+      return 'string';
+    }
+
+    void flushEndpoint() {
+      if (currentMethod != null) {
+        if (currentPath == null) {
+          _errors.add('Endpoint defined without path at line $lineNumber');
+          currentMethod = null;
+          currentPath = null;
+          description = '';
+          hasAuth = false;
+          requestBodyFields.clear();
+          bodyJsonBuffer.clear();
+          return;
+        }
+
+        if (!validMethods.contains(currentMethod!.toLowerCase())) {
+          _errors.add(
+            'Invalid HTTP method "$currentMethod" at line $lineNumber',
+          );
+          currentMethod = null;
+          currentPath = null;
+          description = '';
+          hasAuth = false;
+          requestBodyFields.clear();
+          bodyJsonBuffer.clear();
+          return;
+        }
+
+        final path = currentPath!;
+        final method = currentMethod!.toLowerCase();
+
+        if (fileEndpoints[path] == null) {
+          fileEndpoints[path] = {};
+        }
+
+        Map<String, dynamic> endpointData = {
+          "summary": description.isNotEmpty ? description : "No description",
+          "responses": {
+            "200": {"description": "Successful response"},
+          },
+        };
+
+        if (currentTags.isNotEmpty) {
+          endpointData['tags'] = currentTags.toList();
+        }
+
+        if (hasAuth) {
+          endpointData['security'] = [
+            {"bearerAuth": []},
+          ];
+        }
+
+        if (requestBodyFields.isNotEmpty) {
+          Map<String, dynamic> properties = {};
+          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'] ?? '',
+              };
+            }
+          }
+
+          endpointData['requestBody'] = {
+            "content": {
+              "application/json": {
+                "schema": {"type": "object", "properties": properties},
+              },
+            },
+          };
+        }
+
+        fileEndpoints[path][method] = endpointData;
+      }
+
+      currentMethod = null;
+      currentPath = null;
+      description = '';
+      hasAuth = false;
+      currentTags.clear();
+      requestBodyFields.clear();
+      bodyJsonBuffer.clear();
+    }
+
+    for (final l in lines) {
+      lineNumber++;
+      final trimmed = l.trim();
+
+      if (isReadingBodyJson) {
+        if (!_isCommentLine(trimmed, commentPrefix)) {
+          isReadingBodyJson = false;
+          if (bodyJsonBuffer.isNotEmpty) {
+            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 at line $lineNumber: $e');
+            }
+          }
+          bodyJsonBuffer.clear();
+        } else {
+          final commentText = _extractCommentText(trimmed, commentPrefix);
+          bodyJsonBuffer.write(commentText);
+          continue;
+        }
+      }
+
+      if (!_isCommentLine(trimmed, commentPrefix)) {
+        if (trimmed.isNotEmpty) {
+          flushEndpoint();
+        }
+        continue;
+      }
+
+      final commentText = _extractCommentText(trimmed, commentPrefix);
+      if (!commentText.startsWith('@')) {
+        continue;
+      }
+
+      final parts = commentText.split(RegExp(r'\s+'));
+      if (parts.isEmpty) continue;
+
+      final tag = parts[0];
+
+      if (tag == '@api') {
+        flushEndpoint();
+        if (parts.length >= 3) {
+          currentMethod = parts[1].toUpperCase();
+          currentPath = parts[2];
+        } else {
+          _errors.add('@api requires method and path at line $lineNumber');
+        }
+      } else if (tag == '@desc') {
+        description = commentText.replaceFirst('@desc', '').trim();
+      } else if (tag == '@auth') {
+        hasAuth = true;
+      } else if (tag == '@tag') {
+        if (parts.length >= 2) {
+          final tagName = parts.sublist(1).join(' ');
+          if (!_tags.contains(tagName)) {
+            _tags.add(tagName);
+          }
+          if (!currentTags.contains(tagName)) {
+            currentTags.add(tagName);
+          }
+        }
+      } else if (tag == '@body') {
+        if (parts.length >= 3) {
+          final fieldName = parts[1];
+          final fieldType = parts[2];
+          final fieldDesc = parts.length > 3 ? parts.sublist(3).join(' ') : '';
+          requestBodyFields.add({
+            'name': fieldName,
+            'type': fieldType,
+            'desc': fieldDesc,
+          });
+        } else {
+          _errors.add('@body requires field name and type at line $lineNumber');
+        }
+      } else if (tag == '@body-file') {
+        if (parts.length >= 2) {
+          final jsonFile = File(p.join(p.dirname(filePath), parts[1]));
+          if (jsonFile.existsSync()) {
+            try {
+              final jsonData = jsonDecode(jsonFile.readAsStringSync());
+              if (jsonData is Map) {
+                for (final entry in jsonData.entries) {
+                  requestBodyFields.add({
+                    'name': entry.key.toString(),
+                    'type': inferType(entry.value),
+                    'desc': 'Inferred from file',
+                  });
+                }
+              }
+            } catch (e) {
+              _errors.add('Invalid JSON file at line $lineNumber: $e');
+            }
+          }
+        }
+      } else if (tag == '@body-json') {
+        isReadingBodyJson = true;
+        bodyJsonBuffer.clear();
+      }
+    }
+
+    flushEndpoint();
+
+    if (_errors.isNotEmpty) {
+      for (final error in _errors) {
+        print('⚠️ $error');
+      }
+    }
+
+    if (fileEndpoints.isNotEmpty) {
+      _fileRegistry[filePath] = fileEndpoints;
+      _generateSwaggerFile();
+    } else if (_fileRegistry.containsKey(filePath)) {
+      _fileRegistry.remove(filePath);
+      _generateSwaggerFile();
+    }
+  }
+
+  void _generateSwaggerFile() {
+    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);
+      }
+    }
+
+    _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');
+    if (!swaggerFile.parent.existsSync()) {
+      swaggerFile.parent.createSync(recursive: true);
+    }
+
+    swaggerFile.writeAsStringSync(
+      JsonEncoder.withIndent('  ').convert(_baseSpec),
+    );
+    print(
+      '🐸 FroggyDocs: Updated documentation. Total paths: ${fullPaths.length}',
+    );
+  }
+}

package/lib/src/test_api.js

@@ -0,0 +1,41 @@
+// @api GET /api/simple
+// @tag Users
+// @desc Simple setup using method 1
+// @body title String Post title
+// @body views Number Total views count
+app.post('/api/simple', (req, res) => {});
+
+// @api GET /api/me
+// @tag Users
+// @desc Extracting from external file called mock.json using method 2
+// @body-file ./mock.json
+app.post('/api/me', (req, res) => {});
+
+// @api PUT /api/inline-json
+// @tag Users
+// @desc Extracting from inline JSON block using method 3
+app.put('/api/inline-json', (req, res) => {
+    res.json({
+        "message": "This is an inline JSON response",
+    })
+});
+
+//@api POST /api/login
+//@tag Auth
+//@desc User login endpoint with inline JSON body
+app.post('/api/login', (req, res) => {
+    res.json({
+        "token": "abc123",
+        "expiresIn": 3600
+    });
+});
+
+//@api POST /api/register
+//@tag Auth
+//@desc User registration endpoint with inline JSON body
+app.post('/api/register', (req, res) => {
+    res.json({
+        "message": "User registered successfully",
+        "userId": 12345
+    });
+});

package/lib/src/watcher_engine.dart

@@ -0,0 +1,58 @@
+import 'dart:io';
+import 'package:watcher/watcher.dart';
+import 'package:path/path.dart' as p;
+import 'parser_engine.dart';
+
+class WatcherEngine {
+  final ParserEngine _parser = ParserEngine();
+
+  void startWatching(String directoryPath) {
+    print('🚀 Initializing FroggyDocs scan...');
+    _initialScan(directoryPath);
+
+    final watcher = DirectoryWatcher(directoryPath);
+    print('👀 Watching for changes in: ${p.absolute(directoryPath)}...\n');
+
+    watcher.events.listen((WatchEvent event) {
+      if (_shouldIgnore(event.path)) return;
+      _handleFileChange(event);
+    });
+  }
+
+  void _initialScan(String directoryPath) {
+    final dir = Directory(directoryPath);
+    try {
+      dir.listSync(recursive: true).forEach((entity) {
+        if (entity is File && !_shouldIgnore(entity.path)) {
+          _parser.parseFile(entity.path);
+        }
+      });
+    } catch (e) {
+      print('⚠️ Warning during initial scan: $e');
+    }
+    print('✅ Initial scan complete.\n');
+  }
+
+  bool _shouldIgnore(String path) {
+    final normalizedPath = path.replaceAll('\\', '/');
+    return normalizedPath.contains('/.dart_tool/') ||
+        normalizedPath.contains('/frontend/') ||
+        normalizedPath.contains('/node_modules/') ||
+        normalizedPath.contains('/.git/') ||
+        normalizedPath.endsWith('.json') ||
+        normalizedPath.endsWith('.md');
+  }
+
+  void _handleFileChange(WatchEvent event) {
+    switch (event.type) {
+      case ChangeType.ADD:
+      case ChangeType.MODIFY:
+        _parser.parseFile(event.path);
+        break;
+      case ChangeType.REMOVE:
+        print('🗑️ Removing documentation for: ${p.basename(event.path)}');
+        _parser.removeFile(event.path);
+        break;
+    }
+  }
+}

package/lib/src/web_server.dart

@@ -0,0 +1,164 @@
+import 'dart:io';
+import 'dart:async';
+import 'dart:convert';
+import 'package:shelf/shelf.dart';
+import 'package:shelf/shelf_io.dart' as shelf_io;
+import 'package:shelf_router/shelf_router.dart';
+import 'package:path/path.dart' as p;
+
+const defaultPort = 8080;
+
+Future<void> startServer({int port = defaultPort}) async {
+  final handler = const Pipeline()
+      .addMiddleware(logRequests())
+      .addHandler(_router.call);
+
+  final server = await shelf_io.serve(handler, 'localhost', port);
+  print(
+    '🐸 FroggyDocs server running at http://${server.address.host}:${server.port}',
+  );
+  print('📖 Open http://${server.address.host}:${server.port} in your browser');
+}
+
+const _corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+const String webDir = 'frontend/web';
+const String deployDir = 'frontend/deploy/web';
+
+Router get _router {
+  final router = Router();
+
+  router.get('/froggy_docs.json', (Request request) async {
+    final file = File(
+      p.join(Directory.current.path, webDir, 'froggy_docs.json'),
+    );
+    if (await file.existsSync()) {
+      return Response.ok(
+        file.openRead(),
+        headers: {'Content-Type': 'application/json'},
+      );
+    }
+    return Response.notFound('{"error": "Not found"}');
+  });
+
+  router.get('/', (Request request) async {
+    final indexFile = File(
+      p.join(Directory.current.path, deployDir, 'index.html'),
+    );
+    if (await indexFile.existsSync()) {
+      return Response.ok(
+        indexFile.openRead(),
+        headers: {'Content-Type': 'text/html'},
+      );
+    }
+    return Response.notFound('index.html not found');
+  });
+
+  // ═════════════════════════════════════════════════════════════
+  // Demo/Mock API Endpoints
+  // These are included for testing "Try It Out" functionality
+  // Remove these routes in production - your real API will handle requests
+  // ═════════════════════════════════════════════════════════════
+  router.post('/api/simple', (Request request) async {
+    final body = await request.readAsString();
+    return Response.ok(
+      jsonEncode({
+        'status': 'success',
+        'received': body.isNotEmpty ? jsonDecode(body) : {},
+      }),
+      headers: {'Content-Type': 'application/json'},
+    );
+  });
+
+  router.post('/api/me', (Request request) async {
+    return Response.ok(
+      jsonEncode({
+        'message': 'Logged in',
+        'user': {'email': 'test@example.com', 'id': 1},
+      }),
+      headers: {'Content-Type': 'application/json'},
+    );
+  });
+
+  router.put('/api/inline-json', (Request request) async {
+    return Response.ok(
+      jsonEncode({
+        'status': 'updated',
+        'timestamp': DateTime.now().toIso8601String(),
+      }),
+      headers: {'Content-Type': 'application/json'},
+    );
+  });
+
+  router.get(
+    '/api/simple',
+    (Request request) => Response.ok(
+      '{"message": "GET works"}',
+      headers: {'Content-Type': 'application/json'},
+    ),
+  );
+  router.get(
+    '/api/me',
+    (Request request) => Response.ok(
+      '{"message": "GET /api/me"}',
+      headers: {'Content-Type': 'application/json'},
+    ),
+  );
+  router.get(
+    '/api/inline-json',
+    (Request request) => Response.ok(
+      '{"message": "GET /api/inline-json"}',
+      headers: {'Content-Type': 'application/json'},
+    ),
+  );
+  router.delete(
+    '/api/simple',
+    (Request request) => Response.ok(
+      '{"message": "Deleted"}',
+      headers: {'Content-Type': 'application/json'},
+    ),
+  );
+
+  // ═════════════════════════════════════════════════════════════
+  // End of Demo/Mock API
+  // In production: Remove lines 66-124 or connect to your real API
+  // The "Try It Out" button will call your actual API endpoints
+  // ═════════════════════════════════════════════════════════════
+
+  router.get('/<path|[^/]+>', (Request request, String path) async {
+    var file = File(p.join(Directory.current.path, deployDir, path));
+    if (await file.existsSync()) {
+      return Response.ok(
+        file.openRead(),
+        headers: {'Content-Type': _getContentType(path)},
+      );
+    }
+    file = File(p.join(Directory.current.path, webDir, path));
+    if (await file.existsSync()) {
+      return Response.ok(
+        file.openRead(),
+        headers: {'Content-Type': _getContentType(path)},
+      );
+    }
+    return Response.notFound('File not found: $path');
+  });
+
+  return router;
+}
+
+String _getContentType(String path) {
+  final ext = p.extension(path).toLowerCase();
+  return switch (ext) {
+    '.html' => 'text/html',
+    '.css' => 'text/css',
+    '.js' => 'application/javascript',
+    '.json' => 'application/json',
+    '.svg' => 'image/svg+xml',
+    '.ico' => 'image/x-icon',
+    _ => 'application/octet-stream',
+  };
+}