[wip] feat: proposal analyzer skeleton

engine/cld/mcms/analyzer/internal/ENHANCEMENT_SUMMARY.md

@@ -0,0 +1,286 @@
+# Renderer Enhancement Summary
+
+## Overview
+
+The renderer implementation has been successfully enhanced with the following major improvements:
+
+## 1. File-Based Templates
+
+Templates are now organized in format-specific directories and embedded in the binary:
+
+```
+internal/templates/
+  ├── text/
+  │   ├── proposal.tmpl
+  │   ├── batchOperation.tmpl
+  │   ├── call.tmpl
+  │   └── parameter.tmpl
+  └── html/
+      ├── proposal.tmpl
+      ├── batchOperation.tmpl
+      ├── call.tmpl
+      └── parameter.tmpl
+```
+
+### Features:
+- **Embedded templates** using Go's `embed` package for easy distribution
+- **External template loading** from filesystem directories for customization
+- **Format-specific templates** optimized for each output type
+
+## 2. Multiple Format Support
+
+The renderer now supports multiple output formats:
+
+### Formats Implemented:
+- **Text (FormatText)**: Plain text with ASCII art and Unicode symbols
+- **HTML (FormatHTML)**: Rich HTML with CSS styling and semantic markup
+
+### Format-Specific Features:
+
+#### Text Format
+- ASCII art borders and dividers
+- Unicode symbols for severity (✗, ⚠, ℹ, ⚙) and risk (🔴, 🟡, 🟢)
+- Emoji support for custom decorations
+- Compact, readable layout for CLI output
+
+#### HTML Format
+- Complete HTML document with embedded CSS
+- Color-coded severity and risk levels
+- Responsive layout with proper semantic HTML
+- CSS classes for easy styling customization
+- Icon/emoji support integrated into the design
+
+### Usage:
+
+```go
+// Text format (default)
+renderer, _ := internal.NewRenderer()
+
+// HTML format
+htmlRenderer, _ := internal.NewRendererWithFormat(internal.FormatHTML)
+
+// Render to file
+htmlRenderer.RenderToFile("proposal.html", analyzedProposal)
+```
+
+## 3. Annotation-Driven Rendering
+
+**Key Change**: Annotations now control rendering behavior instead of being displayed as separate entities.
+
+### Rendering Annotations
+
+#### `render.important`
+Marks entities as important with visual highlighting:
+- **Text**: Adds ⭐ symbol
+- **HTML**: Wraps in `<span class="important">` with background color
+
+```go
+param.AddAnnotations(internal.ImportantAnnotation(true))
+```
+
+#### `render.emoji`
+Adds emoji decoration to entities:
+```go
+param.AddAnnotations(internal.EmojiAnnotation("💰"))
+// Output: 💰 amount (uint256): 1000
+```
+
+#### `render.formatter`
+Applies custom value formatting:
+
+**Ethereum Address Formatter**:
+```go
+param.AddAnnotations(internal.FormatterAnnotation("ethereum.address"))
+// Input:  "1234567890abcdef..."
+// Output: "0x1234567890abcdef..."
+```
+
+**Ethereum Uint256 Formatter**:
+```go
+param.AddAnnotations(internal.FormatterAnnotation("ethereum.uint256"))
+// Input:  "1000000000"
+// Output: "1,000,000,000"
+```
+
+**Hex Formatter**:
+```go
+param.AddAnnotations(internal.FormatterAnnotation("hex"))
+// Formats values as 0x... hex strings
+```
+
+**Truncate Formatter**:
+```go
+param.AddAnnotations(internal.FormatterAnnotation("truncate:20"))
+// Truncates strings to 20 characters with "..." suffix
+```
+
+#### `render.style`
+Provides styling hints (HTML format):
+```go
+call.AddAnnotations(internal.StyleAnnotation("danger"))
+```
+
+#### `render.template`
+Specifies custom template to use:
+```go
+call.AddAnnotations(internal.TemplateAnnotation("customCall"))
+```
+
+#### `render.hide`
+Hides entities from output:
+```go
+param.AddAnnotations(internal.HideAnnotation(true))
+```
+
+#### `render.tooltip`
+Adds tooltip text (HTML format):
+```go
+param.AddAnnotations(internal.TooltipAnnotation("This parameter controls..."))
+```
+
+### Built-in Analysis Annotations
+
+#### `cld.severity`
+Displays severity with symbols:
+- `error`: ✗ (red in HTML)
+- `warning`: ⚠ (orange in HTML)
+- `info`: ℹ (blue in HTML)
+- `debug`: ⚙ (gray in HTML)
+
+```go
+call.AddAnnotations(internal.SeverityAnnotation("warning"))
+```
+
+#### `cld.risk`
+Displays risk with colored symbols:
+- `high`: 🔴
+- `medium`: 🟡
+- `low`: 🟢
+
+```go
+batchOp.AddAnnotations(internal.RiskAnnotation("high"))
+```
+
+## New Template Functions
+
+Templates have access to annotation-aware functions:
+
+### Annotation Functions
+- `getAnnotation .Entity "name"` - Retrieves annotation object
+- `getAnnotationValue .Entity "name"` - Gets annotation value directly
+- `hasAnnotation .Entity "name"` - Checks if annotation exists
+- `hasAnnotations .Entity` - Checks if entity has any annotations
+
+### Formatting Functions
+- `formatValue .Param "formatter"` - Applies custom formatter
+- `severitySymbol "level"` - Returns severity symbol
+- `riskSymbol "level"` - Returns risk symbol
+
+### String Functions
+- `indent spaces text` - Indents text
+- `upper`, `lower`, `title` - Case conversions
+- `trimRight text` - Trim whitespace
+- `join sep items` - Join strings
+- `repeat count text` - Repeat text
+
+## Template Examples
+
+### Text Template with Annotations
+
+```go
+{{define "call"}}
+┌─ CALL: {{.Name}}{{if getAnnotation . "render.important"}} ⭐{{end}}
+{{- $severity := getAnnotationValue . "cld.severity"}}
+{{- if $severity}}
+│ Severity: {{severitySymbol $severity}} {{$severity}}
+{{- end}}
+└─────────────────────────
+{{end}}
+```
+
+### HTML Template with Annotations
+
+```html
+{{define "parameter"}}
+{{- $important := getAnnotation . "render.important"}}
+{{- $emoji := getAnnotationValue . "render.emoji"}}
+{{- $formatter := getAnnotationValue . "render.formatter"}}
+{{- if $important}}<span class="important">{{end}}
+{{- if $emoji}}{{$emoji}} {{end}}
+<strong>{{.Name}}</strong> ({{.Type}}): 
+<code>{{if $formatter}}{{formatValue . $formatter}}{{else}}{{.Value}}{{end}}</code>
+{{- if $important}}</span>{{end}}
+{{end}}
+```
+
+## Files Created/Modified
+
+### New Files:
+- `templates/text/*.tmpl` - Text format templates
+- `templates/html/*.tmpl` - HTML format templates
+- `render_annotations.go` - Rendering annotation constants and helpers
+- `test_mocks.go` - Shared test mocks
+- `renderer_enhanced_test.go` - Tests for new functionality
+- `RENDERER_ENHANCED.md` - Comprehensive documentation
+
+### Modified Files:
+- `renderer.go` - Enhanced with multi-format support, file-based templates, and annotation functions
+- `templates.go` - Marked as deprecated
+- `renderer_test.go` - Updated for new API, skipped deprecated tests
+- `example_renderer_test.go` - Updated with new examples
+
+## API Changes
+
+### Backward Compatible:
+```go
+// Still works - defaults to text format
+renderer, _ := internal.NewRenderer()
+```
+
+### New APIs:
+```go
+// Create with specific format
+renderer, _ := internal.NewRendererWithFormat(internal.FormatHTML)
+
+// Load from custom directory
+renderer, _ := internal.NewRendererFromDirectory(internal.FormatText, "/path/to/templates")
+
+// Use in-memory templates with format
+renderer, _ := internal.NewRendererWithTemplates(internal.FormatText, templates)
+
+// Render to file
+renderer.RenderToFile("output.html", proposal)
+
+// Get renderer format
+fmt.Println(renderer.Format()) // "html" or "text"
+```
+
+## Testing
+
+All tests pass successfully:
+- Text format rendering
+- HTML format rendering
+- Annotation-driven rendering
+- Custom formatters (Ethereum address, uint256, hex, truncate)
+- Template functions (getAnnotation, hasAnnotation, etc.)
+- Custom template support
+
+## Benefits
+
+1. **Flexibility**: Easy to add new formats by creating templates
+2. **Customization**: Templates can be overridden without code changes
+3. **Separation of Concerns**: Annotations encode analysis results, renderer interprets them
+4. **Better UX**: Format-specific rendering optimizes for different use cases
+5. **Maintainability**: Template-based rendering is easier to modify than code
+6. **Extensibility**: New annotations and formatters can be added without breaking changes
+
+## Future Enhancement Opportunities
+
+1. **Markdown format** - For documentation generation
+2. **JSON format** - For machine-readable output
+3. **Additional formatters** - Date/time, currency, percentages, etc.
+4. **Template inheritance** - Share common elements across formats
+5. **Syntax highlighting** - For code snippets in HTML
+6. **Interactive HTML** - Collapsible sections, search, filtering
+7. **PDF generation** - Using HTML as intermediate format
+8. **Excel export** - For tabular data analysis