binja 0.9.0 → 0.9.2

package/README.md

@@ -5,18 +5,25 @@
 </p>
 
 <p align="center">
+  <a href="https://egeominotti.github.io/binja/"><strong>📚 Documentation</strong></a> •
   <a href="#installation">Installation</a> •
   <a href="#quick-start">Quick Start</a> •
-  <a href="#features">Features</a> •
-  <a href="#benchmarks">Benchmarks</a> •
-  <a href="#filters">Filters</a>
+  <a href="#framework-adapters">Hono/Elysia</a> •
+  <a href="#multi-engine-support">Multi-Engine</a> •
+  <a href="#filters-84-built-in">Filters</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/binja"><img src="https://img.shields.io/npm/v/binja?label=npm&color=10b981" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/binja"><img src="https://img.shields.io/npm/dm/binja?color=10b981" alt="npm downloads"></a>
+  <a href="https://github.com/egeominotti/binja/actions"><img src="https://github.com/egeominotti/binja/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/egeominotti/binja/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg" alt="BSD-3-Clause License"></a>
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/bun-%23000000.svg?style=for-the-badge&logo=bun&logoColor=white" alt="Bun" />
   <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
   <img src="https://img.shields.io/badge/Django-092E20?style=for-the-badge&logo=django&logoColor=white" alt="Django Compatible" />
-  <img src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg?style=for-the-badge" alt="BSD-3-Clause License" />
 </p>
 
 ---
@@ -27,7 +34,8 @@
 |---------|-----------|------------------|
 | **Runtime Performance** | ✅ 2-4x faster | ❌ |
 | **AOT Compilation** | ✅ 160x faster | ❌ |
-| **Multi-Engine** | ✅ Jinja2, Handlebars, Liquid | ❌ |
+| **Multi-Engine** | ✅ Jinja2, Handlebars, Liquid, Twig | ❌ |
+| **Framework Adapters** | ✅ Hono, Elysia | ❌ |
 | Django DTL Compatible | ✅ 100% | ❌ Partial |
 | Jinja2 Compatible | ✅ Full | ⚠️ Limited |
 | Template Inheritance | ✅ | ⚠️ |
@@ -430,6 +438,7 @@ Binja supports multiple template engines through a unified API. All engines pars
 | **Jinja2/DTL** | `{{ var }}` `{% if %}` | Default, Python/Django compatibility |
 | **Handlebars** | `{{var}}` `{{#if}}` | JavaScript ecosystem, Ember.js |
 | **Liquid** | `{{ var }}` `{% if %}` | Shopify, Jekyll, static sites |
+| **Twig** | `{{ var }}` `{% if %}` | PHP/Symfony, Drupal, Craft CMS |
 
 ### Usage
 
@@ -437,6 +446,7 @@ Binja supports multiple template engines through a unified API. All engines pars
 // Direct engine imports
 import * as handlebars from 'binja/engines/handlebars'
 import * as liquid from 'binja/engines/liquid'
+import * as twig from 'binja/engines/twig'
 
 // Handlebars
 await handlebars.render('Hello {{name}}!', { name: 'World' })
@@ -447,6 +457,11 @@ await handlebars.render('{{{html}}}', { html: '<b>unescaped</b>' })
 await liquid.render('Hello {{ name }}!', { name: 'World' })
 await liquid.render('{% for item in items %}{{ item }}{% endfor %}', { items: ['a', 'b'] })
 await liquid.render('{% assign x = "value" %}{{ x }}', {})
+
+// Twig (Symfony)
+await twig.render('Hello {{ name }}!', { name: 'World' })
+await twig.render('{% for item in items %}{{ item }}{% endfor %}', { items: ['a', 'b'] })
+await twig.render('{{ name|upper }}', { name: 'world' })
 ```
 
 ### MultiEngine API
@@ -459,26 +474,117 @@ const engine = new MultiEngine()
 // Render with any engine
 await engine.render('Hello {{name}}!', { name: 'World' }, 'handlebars')
 await engine.render('Hello {{ name }}!', { name: 'World' }, 'liquid')
+await engine.render('Hello {{ name }}!', { name: 'World' }, 'twig')
 await engine.render('Hello {{ name }}!', { name: 'World' }, 'jinja2')
 
 // Auto-detect from file extension
 import { detectEngine } from 'binja/engines'
-const eng = detectEngine('template.hbs')  // Returns Handlebars engine
-const eng2 = detectEngine('page.liquid')  // Returns Liquid engine
+const eng = detectEngine('template.hbs')     // Returns Handlebars engine
+const eng2 = detectEngine('page.liquid')     // Returns Liquid engine
+const eng3 = detectEngine('page.twig')       // Returns Twig engine
 ```
 
 ### Engine Feature Matrix
 
-| Feature | Jinja2 | Handlebars | Liquid |
-|---------|--------|------------|--------|
-| Variables | `{{ x }}` | `{{x}}` | `{{ x }}` |
-| Conditionals | `{% if %}` | `{{#if}}` | `{% if %}` |
-| Loops | `{% for %}` | `{{#each}}` | `{% for %}` |
-| Filters | `{{ x\|filter }}` | `{{ x }}` | `{{ x \| filter }}` |
-| Raw output | `{% raw %}` | - | `{% raw %}` |
-| Comments | `{# #}` | `{{! }}` | `{% comment %}` |
-| Assignment | `{% set %}` | - | `{% assign %}` |
-| Unescaped | `{{ x\|safe }}` | `{{{x}}}` | - |
+| Feature | Jinja2 | Handlebars | Liquid | Twig |
+|---------|--------|------------|--------|------|
+| Variables | `{{ x }}` | `{{x}}` | `{{ x }}` | `{{ x }}` |
+| Conditionals | `{% if %}` | `{{#if}}` | `{% if %}` | `{% if %}` |
+| Loops | `{% for %}` | `{{#each}}` | `{% for %}` | `{% for %}` |
+| Filters | `{{ x\|filter }}` | `{{ x }}` | `{{ x \| filter }}` | `{{ x\|filter }}` |
+| Raw output | `{% raw %}` | - | `{% raw %}` | `{% raw %}` |
+| Comments | `{# #}` | `{{! }}` | `{% comment %}` | `{# #}` |
+| Assignment | `{% set %}` | - | `{% assign %}` | `{% set %}` |
+| Unescaped | `{{ x\|safe }}` | `{{{x}}}` | - | `{{ x\|raw }}` |
+
+---
+
+## Framework Adapters
+
+Binja provides first-class integration with Bun's most popular web frameworks.
+
+### Hono
+
+```typescript
+import { Hono } from 'hono'
+import { binja } from 'binja/hono'
+
+const app = new Hono()
+
+// Add binja middleware
+app.use(binja({
+  root: './views',           // Template directory
+  extension: '.html',        // Default extension
+  engine: 'jinja2',          // jinja2 | handlebars | liquid | twig
+  cache: true,               // Cache compiled templates
+  globals: { siteName: 'My App' },  // Global context
+  layout: 'layouts/base',    // Optional layout template
+}))
+
+// Render templates with c.render()
+app.get('/', (c) => c.render('index', { title: 'Home' }))
+app.get('/users/:id', async (c) => {
+  const user = await getUser(c.req.param('id'))
+  return c.render('users/profile', { user })
+})
+
+export default app
+```
+
+### Elysia
+
+```typescript
+import { Elysia } from 'elysia'
+import { binja } from 'binja/elysia'
+
+const app = new Elysia()
+  // Add binja plugin
+  .use(binja({
+    root: './views',
+    extension: '.html',
+    engine: 'jinja2',
+    cache: true,
+    globals: { siteName: 'My App' },
+    layout: 'layouts/base',
+  }))
+  // Render templates with render()
+  .get('/', ({ render }) => render('index', { title: 'Home' }))
+  .get('/users/:id', async ({ render, params }) => {
+    const user = await getUser(params.id)
+    return render('users/profile', { user })
+  })
+  .listen(3000)
+
+console.log('Server running at http://localhost:3000')
+```
+
+### Adapter Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `root` | `string` | `./views` | Template directory |
+| `extension` | `string` | `.html` | Default file extension |
+| `engine` | `string` | `jinja2` | Template engine (`jinja2`, `handlebars`, `liquid`, `twig`) |
+| `cache` | `boolean` | `true` (prod) | Cache compiled templates |
+| `debug` | `boolean` | `false` | Show error details |
+| `globals` | `object` | `{}` | Global context variables |
+| `layout` | `string` | - | Layout template path |
+| `contentVar` | `string` | `content` | Content variable name in layout |
+
+### Cache Management
+
+```typescript
+import { clearCache, getCacheStats } from 'binja/hono'
+// or
+import { clearCache, getCacheStats } from 'binja/elysia'
+
+// Clear all cached templates
+clearCache()
+
+// Get cache statistics
+const stats = getCacheStats()
+console.log(stats) // { size: 10, keys: ['jinja2:./views/index.html', ...] }
+```
 
 ---
 
@@ -609,7 +715,7 @@ debugOptions: {
 
 ## CLI Tool
 
-Binja includes a CLI for template pre-compilation:
+Binja includes a CLI for template pre-compilation and linting:
 
 ```bash
 # Compile all templates to JavaScript
@@ -620,6 +726,15 @@ binja check ./templates
 
 # Watch mode for development
 binja watch ./templates -o ./dist
+
+# Lint templates (syntax check)
+binja lint ./templates
+
+# Lint with AI analysis (requires API key)
+binja lint ./templates --ai
+
+# Lint with specific AI provider
+binja lint ./templates --ai=ollama
 ```
 
 ### Pre-compiled Templates
@@ -633,6 +748,104 @@ const html = render({ title: 'Home', items: [...] })
 
 ---
 
+## AI-Powered Linting (Optional)
+
+Binja includes an optional AI-powered linting module that detects security issues, performance problems, accessibility concerns, and best practice violations.
+
+### Installation
+
+The AI module is opt-in. Install the SDK for your preferred provider:
+
+```bash
+# For Claude (Anthropic)
+bun add @anthropic-ai/sdk
+
+# For OpenAI
+bun add openai
+
+# For Ollama (local) - no package needed
+# For Groq - no package needed
+```
+
+### Configuration
+
+Set the API key for your provider:
+
+```bash
+# Anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+
+# Groq (free tier available)
+export GROQ_API_KEY=gsk_...
+
+# Ollama - no key needed, just run: ollama serve
+```
+
+### Usage
+
+#### CLI
+
+```bash
+# Lint with AI (auto-detect provider)
+binja lint ./templates --ai
+
+# Use specific provider
+binja lint ./templates --ai=anthropic
+binja lint ./templates --ai=openai
+binja lint ./templates --ai=ollama
+binja lint ./templates --ai=groq
+
+# JSON output for CI/CD
+binja lint ./templates --ai --format=json
+```
+
+#### Programmatic
+
+```typescript
+import { lint } from 'binja/ai'
+
+// Auto-detect provider from environment
+const result = await lint(template)
+
+// Specify provider and API key directly
+const result = await lint(template, {
+  provider: 'anthropic',
+  apiKey: 'sk-ant-...',
+  model: 'claude-sonnet-4-20250514'
+})
+
+// Check results
+console.log(result.errors)      // Syntax errors
+console.log(result.warnings)    // Security, performance issues
+console.log(result.suggestions) // Best practice recommendations
+console.log(result.provider)    // Which AI was used
+```
+
+### What It Detects
+
+| Category | Examples |
+|----------|----------|
+| **Security** | XSS vulnerabilities, `\|safe` on user input, sensitive data exposure |
+| **Performance** | Heavy filters in loops, repeated calculations |
+| **Accessibility** | Missing alt text, forms without labels |
+| **Best Practices** | `{% for %}` without `{% empty %}`, deep nesting |
+
+### Provider Comparison
+
+| Provider | API Key | Speed | Cost |
+|----------|---------|-------|------|
+| **Anthropic** | `ANTHROPIC_API_KEY` | Fast | Paid |
+| **OpenAI** | `OPENAI_API_KEY` | Fast | Paid |
+| **Groq** | `GROQ_API_KEY` | Very Fast | Free tier |
+| **Ollama** | None (local) | Varies | Free |
+
+Auto-detect priority: Anthropic → OpenAI → Groq → Ollama
+
+---
+
 ## Raw/Verbatim Tag
 
 Output template syntax without processing: