lion

Author: Copilot

.gitignore

@@ -27,3 +27,4 @@ linters/uselesswrapper/uselesswrapper
 
 # Idk
 actionlint
+bin/

README.md

@@ -22,6 +22,7 @@ This repository contains multiple independent projects.
 | [jj-run-py](jj-run-py/) | deprecated | Old version of jj-run written in Python. |
 | [tk-vscode](tk-vscode/) | alpha | VS Code extension that lists tk tasks by running `tk ls --json`. |
 | [aihook](aihook/) | alpha | Claude Code hook validator that enforces shell scripting best practices. |
+| [lion](lion/) | alpha | Documentation extraction tool that generates markdown from special comments in Go code. |
 
 ## Libraries
 

lion/.gitignore

@@ -0,0 +1 @@
+lion

lion/AGENTS.md

@@ -0,0 +1,70 @@
+# Agent Guidelines for lion
+
+## Building and Testing
+
+```bash
+# Build from repository root
+go build ./lion
+
+# Run tests
+go test ./lion/...
+
+# Run the tool
+go run ./lion generate
+go run ./lion topics
+
+# Format code
+goimports -w lion/
+```
+
+## Project Structure
+
+```
+lion/
+├── main.go                    # CLI entry point
+├── internal/
+│   ├── extractor/            # AST parsing and comment extraction
+│   │   └── extractor.go
+│   └── generator/            # Markdown file generation
+│       └── generator.go
+├── README.md
+├── AGENTS.md
+└── go.mod
+```
+
+## Comment Format
+
+The tool looks for comments starting with `//lion:topic-name`:
+
+```go
+//lion:topic-name Optional documentation content
+func SomeFunction() {
+    // ...
+}
+```
+
+## Implementation Notes
+
+- Uses Go's `go/ast` package for parsing
+- Extracts comments attached to functions, types, constants, and variables
+- Skips test files (`*_test.go`)
+- Generates one markdown file per topic
+- Sorts entries by file and line number for consistency
+- Includes source references in generated markdown
+
+## Testing Approach
+
+Tests should cover:
+- Comment parsing (various formats and edge cases)
+- AST traversal (different Go declarations)
+- Markdown generation (formatting and structure)
+- File I/O operations
+
+## Future Enhancements
+
+Potential features (not yet implemented):
+- Multi-line comment support
+- Custom templates for generated markdown
+- Cross-references between topics
+- Filtering by package or file patterns
+- HTML output format

lion/README.md

@@ -0,0 +1,160 @@
+# lion
+
+Documentation extraction tool for Go code that generates markdown files from special comments.
+
+## Overview
+
+lion scans Go source code for special `//lion:topic-name` comments and generates organized markdown documentation. This allows you to build a book-like documentation structure by adding comments throughout your codebase that contribute to different chapters/topics.
+
+## Installation
+
+```bash
+go install github.com/neongreen/mono/lion@latest
+```
+
+## Usage
+
+### Add Documentation Comments
+
+Add `//lion:topic-name` comments to your Go code:
+
+```go
+//lion:architecture This is the main entry point for the application.
+//lion:architecture It handles initialization and routing.
+func main() {
+    // ...
+}
+
+//lion:api The Config struct holds application configuration.
+//lion:api Fields can be loaded from environment variables or config files.
+type Config struct {
+    Port int
+    Debug bool
+}
+```
+
+### Generate Documentation
+
+```bash
+# Generate docs from current directory to ./docs
+lion generate
+
+# Specify input directory and output directory
+lion generate ./myproject --output ./documentation
+
+# List all topics found in code
+lion topics
+```
+
+### Output
+
+The tool generates:
+- One markdown file per topic (e.g., `architecture.md`, `api.md`)
+- An `index.md` file listing all topics
+- Each entry includes source file reference for traceability
+
+## Comment Format
+
+lion supports three comment formats:
+
+### 1. Single-line format (marker first)
+
+```
+//lion:topic-name Optional content describing this code element
+```
+
+- **topic-name**: Hyphen-separated identifier (becomes filename)
+- **Content**: Optional markdown-formatted text
+- Multiple consecutive `//lion:topic` lines are combined into one entry
+
+### 2. Block comment format
+
+```go
+/*lion:topic-name
+Multi-line content can go here
+without repeating the topic name.
+This makes documentation cleaner.
+*/
+```
+
+- **topic-name**: Specified once at the beginning
+- **Content**: All subsequent lines in the block comment
+- Cleaner for longer documentation blocks
+
+All formats can be attached to functions, types, constants, variables, and package declarations.
+
+## Example
+
+Marker-first format (recommended):
+
+```go
+//lion:getting-started
+//
+// lion is a documentation extraction tool.
+// Add lion comments to generate markdown docs.
+// This is the cleanest syntax for multi-line docs.
+package main
+
+//lion:architecture
+//
+// The main function initializes the app.
+// It handles setup and configuration.
+func main() {
+    // ...
+}
+```
+
+Single-line format:
+
+```go
+//lion:getting-started lion is a documentation extraction tool.
+//lion:getting-started Add lion comments to generate markdown docs.
+package main
+
+//lion:architecture The main function initializes the app.
+func main() {
+    // ...
+}
+```
+
+Block comment format:
+
+```go
+/*lion:getting-started
+lion is a documentation extraction tool.
+Add lion comments to generate markdown docs.
+No need to repeat the topic on each line.
+*/
+package main
+
+/*lion:architecture
+The main function initializes the app.
+It handles setup and configuration.
+*/
+func main() {
+    // ...
+}
+```
+
+Running `lion generate` creates:
+- `docs/getting-started.md`
+- `docs/architecture.md`
+- `docs/index.md`
+
+## Status
+
+**Alpha** - Core functionality works. Comment format and CLI may change.
+
+## Self-Documentation
+
+lion uses itself to generate its own documentation! The `docs/` directory contains markdown files extracted from lion comments in the source code.
+
+To regenerate the documentation:
+```bash
+./regenerate-docs.sh
+```
+
+Or manually:
+```bash
+go run . generate . --output ./docs
+```

lion/docs/errors-and-validation.md

@@ -0,0 +1,13 @@
+# Errors And Validation
+
+## Error handling
+
+Validation and error handling:
+- Invalid or empty topics are ignored silently (no explicit validation yet).
+- Conflicting topic/section titles within the same comment group fail extraction with file:line.
+- Comments that do not attach to package/func/type/const/var doc groups are skipped.
+- CLI exits non-zero only when extraction fails (parse/metadata error) or generation fails (write error).
+- Bad markers inside otherwise valid files do not stop extraction; they are just skipped.
+
+*Source: `lion/internal/extractor/extractor.go:292`*
+

lion/docs/file-title.md

@@ -0,0 +1,14 @@
+# File Title
+
+## Titles and headings
+
+The generated file title comes from the topic display title:
+- Default: Title Case of the topic slug (e.g., "getting-started" -> "Getting Started").
+- Override: set title="Custom Title" on any lion marker for that topic; conflicts fail generation.
+Entry headings:
+- Default: the attached entity name (package <name>, function name, first const/var in the block).
+- Override per entry: section="Custom Section"; section="" suppresses the heading entirely (will emit a warning).
+- Conflicting section titles within the same comment group fail extraction.
+
+*Source: `lion/internal/generator/generator.go:23`*
+

lion/docs/how-to-run-generation.md

@@ -0,0 +1,18 @@
+# How To Run Generation
+
+## Run generation
+
+To run generation:
+
+1. Navigate to your project directory
+
+2. Run: lion generate
+
+3. Check ./docs for generated markdown files
+
+You can specify a different directory and output location:
+
+lion generate ./myproject --output ./documentation
+
+*Source: `lion/main.go:23`*
+

lion/docs/implementation.md

@@ -0,0 +1,18 @@
+# Implementation
+
+## Extraction pipeline
+
+Extraction pipeline:
+
+- Walks all .go files under the directory, skipping *_test.go.
+
+- Parses with comments and pulls lion markers from package doc, func doc, and type/const/var
+
+doc comments (first name in a const/var block is used as the entity).
+
+- Supports single-line markers and block comment markers (marker at top of the doc block).
+
+- Aggregates snippets per topic across files; generator writes one file per topic.
+
+*Source: `lion/internal/extractor/extractor.go:26`*
+

lion/docs/index.md

@@ -0,0 +1,13 @@
+# Documentation Index
+
+This documentation was generated from lion comments in the source code.
+
+## Topics
+
+- [Errors And Validation](errors-and-validation.md)
+- [File Title](file-title.md)
+- [How To Run Generation](how-to-run-generation.md)
+- [Implementation](implementation.md)
+- [Output Behavior](output-behavior.md)
+- [Snippet Order](snippet-order.md)
+- [Supported Syntax](supported-syntax.md)