froggy-docs 1.0.0

package/.dockerignore

@@ -0,0 +1,34 @@
+# Dependencies
+.dart_tool/
+.pub/
+.packages
+
+# Build outputs
+bin/*.dill
+*.swp
+*.swo
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test files
+test/
+
+# Frontend build
+frontend/deploy/
+frontend/.dart_tool/
+node_modules/
+
+# Logs
+*.log
+npm-debug.log*
+
+# Temp
+tmp/
+temp/

package/.froggyrc.example

@@ -0,0 +1,36 @@
+{
+  "title": "My API Documentation",
+  "version": "1.0.0",
+  "description": "Auto-generated API documentation",
+  
+  "server": {
+    "port": 8080,
+    "host": "localhost"
+  },
+  
+  "paths": {
+    "include": ["lib/", "src/", "api/"],
+    "exclude": ["test/", "node_modules/", ".dart_tool/"]
+  },
+  
+  "annotations": {
+    "prefix": "//",
+    "tags": {
+      "api": "Endpoint definition",
+      "desc": "Description",
+      "body": "Request body field",
+      "auth": "Requires authentication",
+      "tag": "Group/category"
+    }
+  },
+  
+  "output": {
+    "format": "openapi",
+    "file": "docs/froggy_docs.json"
+  },
+  
+  "theme": {
+    "primaryColor": "#2e7d32",
+    "darkMode": true
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Install Dart
+        uses: dart-lang/setup-dart@v1
+        
+      - name: Get dependencies
+        run: dart pub get
+        
+      - name: Analyze
+        run: dart analyze lib/
+        
+      - name: Build
+        run: dart compile exe bin/froggy_docs.dart -o froggy-docs
+        
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: froggy-docs
+          path: froggy-docs

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Initial version.

package/Dockerfile

@@ -0,0 +1,49 @@
+# FroggyDocs Dockerfile
+# Multi-stage build for smaller image
+
+# Stage 1: Build
+FROM dart:stable AS builder
+
+WORKDIR /app
+
+# Copy source
+COPY . .
+RUN dart pub get
+
+# Compile the executable
+RUN dart compile exe bin/froggy_docs.dart -o froggy-docs
+
+# Stage 2: Runtime
+FROM debian:stable-slim
+
+# Install curl for healthcheck
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy compiled binary from builder
+COPY --from=builder /app/froggy-docs /usr/local/bin/froggy-docs
+
+# Copy docs and static files
+COPY frontend/deploy/web /app/frontend/web
+COPY frontend/web/froggy_docs.json /app/frontend/web/froggy_docs.json
+
+# Make executable
+RUN chmod +x /usr/local/bin/froggy-docs
+
+# Expose default port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8080/ || exit 1
+
+# Default command
+CMD ["froggy-docs", "serve", "-h", "0.0.0.0"]
+
+# Alternative commands:
+# docker run -p 8080:8080 froggy-docs serve -p 8080
+# docker run -p 3000:8080 froggy-docs serve -p 3000
+# docker run -v $(pwd):/app froggy-docs serve

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# 🐸 FroggyDocs
+
+> Auto-generate API documentation from code annotations. Works with any programming language.
+
+[![Pub](https://img.shields.io/pub/v/froggy_docs.svg)](https://pub.dev/package/froggy_docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docker](https://img.shields.io/badge/Docker-ready-blue.svg)](https://docker.com)
+
+---
+
+## ✨ Features
+
+- 📝 **Easy Annotations** - Add comments to your API code, no config needed
+- 🌐 **Universal** - Works with any language (JavaScript, Python, Go, Ruby, etc.)
+- 🎨 **Beautiful UI** - Interactive API docs with "Try It Out" functionality
+- 🔄 **Live Reload** - Auto-regenerates docs when code changes
+- 📦 **Multiple Outputs** - npm, Docker, GitHub Template
+- 🔒 **OpenAPI 3.0** - Industry-standard specification
+
+---
+
+## 🚀 Quick Start
+
+### Via npm (Recommended)
+```bash
+npm install -g froggy-docs
+froggy-docs serve
+```
+
+### Via Docker
+```bash
+docker run -p 8080:8080 froggy-docs
+```
+
+### Via Dart
+```bash
+dart pub global activate froggy_docs
+froggy_docs serve
+```
+
+---
+
+## 💻 Usage
+
+### 1. Add Annotations to Your Code
+
+```javascript
+// @api POST /api/users
+// @tag Users
+// @tag Auth
+// @desc Create a new user
+// @body name string User's full name
+// @body email string User's email
+// @auth
+app.post('/api/users', async (req, res) => {
+  // Your API logic here
+});
+```
+
+### 2. Run the Documentation Server
+
+```bash
+# Default (localhost:8080)
+froggy-docs serve
+
+# Custom port
+froggy-docs serve -p 3000
+
+# Network accessible
+froggy-docs serve -h 0.0.0.0 -p 8080
+
+# Watch mode (no server)
+froggy-docs watch
+```
+
+### 3. Open in Browser
+
+```
+http://localhost:8080
+```
+
+---
+
+## 📖 Annotation Reference
+
+| Annotation | Description | Example |
+|------------|-------------|---------|
+| `@api` | Define endpoint | `@api GET /users` |
+| `@desc` | Description | `@desc Get all users` |
+| `@tag` | Category | `@tag Users` |
+| `@body` | Request body field | `@body name string User's name` |
+| `@body-json` | Inline JSON schema | `@body-json {...}` |
+| `@body-file` | From JSON file | `@body-file ./schema.json` |
+| `@auth` | Requires auth | `@auth` |
+
+**Full guide:** [docs/annotations.md](docs/annotations.md)
+
+---
+
+## 🐳 Docker
+
+### Build
+```bash
+docker build -t froggy-docs .
+```
+
+### Run
+```bash
+# Default
+docker run -p 8080:8080 froggy-docs
+
+# Custom port
+docker run -p 3000:8080 froggy-docs serve -p 3000
+
+# Mount project
+docker run -v $(pwd):/app -p 8080:8080 froggy-docs
+```
+
+### Docker Compose
+```yaml
+version: '3'
+services:
+  froggy-docs:
+    build: .
+    ports:
+      - "8080:8080"
+    volumes:
+      - .:/app
+    command: serve -h 0.0.0.0
+```
+
+---
+
+## ⚙️ Configuration
+
+Create `.froggyrc` in your project root:
+
+```json
+{
+  "server": {
+    "port": 8080,
+    "host": "localhost"
+  },
+  "paths": {
+    "include": ["lib/", "src/", "api/"],
+    "exclude": ["test/", "node_modules/"]
+  },
+  "output": {
+    "format": "openapi",
+    "file": "docs/froggy_docs.json"
+  }
+}
+```
+
+See: [`.froggyrc.example`](.froggyrc.example)
+
+---
+
+## 🌐 Supported Languages
+
+| Language | Extensions | Comment |
+|----------|------------|----------|
+| JavaScript/TypeScript | .js, .ts, .jsx, .tsx | `//` |
+| Python | .py | `#` |
+| Ruby | .rb | `#` |
+| Go | .go | `//` |
+| Rust | .rs | `//` |
+| Dart | .dart | `//` |
+| Java/Kotlin | .java, .kt | `//` |
+| PHP | .php | `//` |
+| C# | .cs | `//` |
+| C/C++ | .c, .cpp, .h | `//` |
+
+---
+
+## 📦 Installation Options
+
+### npm
+```bash
+npm install -g froggy-docs
+```
+
+### pip
+```bash
+pip install froggy-docs
+```
+
+### Docker
+```bash
+docker run -p 8080:8080 froggy-docs
+```
+
+### Standalone Binary
+Download from [Releases](https://github.com/yourusername/froggy-docs/releases)
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create your branch (`git checkout -b feature/amazing`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- [Shelf](https://pub.dev/packages/shelf) - HTTP server
+- [Watcher](https://pub.dev/packages/watcher) - File watching
+- [Jaspr](https://pub.dev/packages/jaspr) - Web framework

package/analysis_options.yaml

@@ -0,0 +1,30 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+# Uncomment the following section to specify additional rules.
+
+# linter:
+#   rules:
+#     - camel_case_types
+
+# analyzer:
+#   exclude:
+#     - path/to/excluded/files/**
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options

package/bin/froggy_docs.dart

@@ -0,0 +1,38 @@
+import 'dart:io';
+import 'dart:async';
+import 'package:args/args.dart';
+import 'package:froggy_docs/src/watcher_engine.dart';
+import 'package:froggy_docs/src/web_server.dart';
+
+void main(List<String> arguments) async {
+  final parser = ArgParser();
+  parser.addCommand('watch');
+  parser.addCommand('serve');
+  parser.addOption(
+    'port',
+    abbr: 'p',
+    help: 'Port for server',
+    defaultsTo: '8080',
+  );
+
+  try {
+    final results = parser.parse(arguments);
+
+    if (results.command?.name == 'watch') {
+      print('🐸 FroggyDocs is watching your API project...');
+      final watcher = WatcherEngine();
+      watcher.startWatching(Directory.current.path);
+    } else if (results.command?.name == 'serve') {
+      final port = int.parse(results['port'] as String);
+      print('🐸 Starting FroggyDocs server with live reload...');
+
+      // Start server and watcher
+      await startServer(port: port);
+      final watcher = WatcherEngine();
+      watcher.startWatching(Directory.current.path);
+    }
+  } catch (e) {
+    print('Error: ${e.toString()}');
+    exit(1);
+  }
+}

package/docs/annotations.md

@@ -0,0 +1,174 @@
+# 📝 FroggyDocs Annotations Guide
+
+Add annotations directly in your API code files. FroggyDocs parses these to generate OpenAPI documentation.
+
+---
+
+## Basic Annotations
+
+### @api - Define Endpoint (Required)
+```javascript
+// @api GET /users
+// @api POST /api/users
+// @api PUT /api/users/:id
+// @api DELETE /api/users/:id
+// @api PATCH /api/users/:id
+```
+
+**Format:** `@api <METHOD> <PATH>`
+
+**Supported Methods:**
+- `GET`
+- `POST`
+- `PUT`
+- `PATCH`
+- `DELETE`
+- `HEAD`
+- `OPTIONS`
+
+---
+
+### @desc - Description
+```javascript
+// @desc Get all users from the database
+```
+
+---
+
+### @tag - Category/Group
+```javascript
+// @tag Users
+// @tag Auth
+// @tag Admin
+```
+Multiple tags are supported:
+```javascript
+// @tag Users
+// @tag Auth
+```
+
+---
+
+## Request Body
+
+### @body - Field Definition
+```javascript
+// @body name string User's full name
+// @body email string User's email address
+// @body age number User's age
+// @body isActive boolean Account status
+```
+
+**Format:** `@body <field_name> <type> <description>`
+
+**Supported Types:**
+- `string`
+- `number`
+- `boolean`
+- `array`
+- `object`
+
+---
+
+### @body-json - Inline JSON
+```javascript
+// @body-json
+// {
+//   "company": "Acme Inc",
+//   "employees": 50,
+//   "active": true
+// }
+```
+
+---
+
+### @body-file - From JSON File
+```javascript
+// @body-file ./schemas/user.json
+```
+
+---
+
+## Authentication
+
+### @auth - Requires Authentication
+```javascript
+// @auth
+```
+Adds security requirement to the endpoint.
+
+---
+
+## Examples
+
+### Complete Example (JavaScript/Node.js)
+```javascript
+// @api POST /api/users
+// @tag Users
+// @tag Auth
+// @desc Create a new user account
+// @body name string User's full name
+// @body email string User's email address
+// @body password string User's password
+// @auth
+app.post('/api/users', async (req, res) => {
+  // Your API logic here
+});
+```
+
+### Python Example
+```python
+# @api GET /users
+# @tag Users
+# @desc Get all users
+def get_users():
+    # Your API logic here
+    pass
+```
+
+### Go Example
+```go
+// @api GET /users
+// @tag Users
+// @desc Get all users
+func GetUsers(w http.ResponseWriter, r *http.Request) {
+    // Your API logic here
+}
+```
+
+### Dart/Flutter Example
+```dart
+// @api GET /users
+// @tag Users
+// @desc Get all users
+Future<List<User>> getUsers() async {
+  // Your API logic here
+}
+```
+
+---
+
+## Language Support
+
+| Language | Comment Style | Extensions |
+|----------|--------------|-------------|
+| JavaScript/TypeScript | `//` | `.js`, `.ts`, `.jsx`, `.tsx` |
+| Dart | `//` | `.dart` |
+| Python | `#` | `.py` |
+| Ruby | `#` | `.rb` |
+| Go | `//` | `.go` |
+| Rust | `//` | `.rs` |
+| Java/Kotlin | `//` | `.java`, `.kt` |
+| PHP | `//` | `.php` |
+| C# | `//` | `.cs` |
+| C/C++ | `//` | `.c`, `.cpp`, `.h` |
+
+---
+
+## Output
+
+FroggyDocs generates [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.0) specification that can be:
+- Viewed in the built-in web UI
+- Imported into Swagger UI
+- Used with other OpenAPI tools
+- Exported as JSON or YAML

package/frontend/README.md

@@ -0,0 +1,15 @@
+# frontend
+
+A new Jaspr project
+
+## Running the project
+
+Run your project using `jaspr serve`.
+
+The development server will be available on `http://localhost:8080`.
+
+## Building the project
+
+Build your project using `jaspr build`.
+
+The output will be located inside the `build/jaspr/` directory.

package/frontend/analysis_options.yaml

@@ -0,0 +1,46 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+analyzer:
+#   exclude:
+#     - path/to/excluded/files/**
+
+# Jaspr has a custom analyzer plugin 'jaspr_lints', which is enabled here.
+#
+# You can toggle Jaspr specific lint rules in the 'diagnostics' section below.
+plugins:
+  jaspr_lints:
+    version: ^0.7.0
+    diagnostics:
+      prefer_html_components: true
+      sort_children_last: true
+      styles_ordering: true
+
+# Uncomment the following section to enable or disable additional rules.
+
+# linter:
+#   rules:
+#     camel_case_types: true
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+formatter:
+  # Change this to your preferred line length.
+  page_width: 120
+  trailing_commas: preserve
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options