@dogsbay/minja 0.2.0-beta.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,623 @@
+# minja
+
+**Minimal, secure Jinja2/Nunjucks subset for documentation preprocessing**
+
+Minja is a template engine designed specifically for documentation and content preprocessing, using standard Jinja2/Nunjucks syntax with **zero arbitrary code execution risk**.
+
+## Features
+
+- **Security First**: No `eval()`, no `new Function()`, no arbitrary code execution
+- **Standard Jinja2 Syntax**: Fully compatible with Jinja2/Nunjucks conditionals
+- **Variable Substitution**: Simple `{{ variable }}` syntax
+- **Conditionals**: `{% if %}`, `{% elif %}`, `{% else %}` with safe expression evaluation
+- **Switch Statements**: `{% switch %}` / `{% case %}` for multiple conditions
+- **Nested Includes**: Recursive `{% include "file.md" %}` support
+- **Leveloffset**: `{% leveloffset +1 %}` for shifting heading levels in included content
+- **Variable Scoping**: Global and local variables with dot notation
+- **Modern**: TypeScript, ES modules, works in browsers and Node.js
+- **Small**: ~10KB minified + gzipped
+- **Zero Dependencies**: No runtime dependencies
+
+## Installation
+
+```bash
+npm install minja
+```
+
+Or install globally to use the CLI:
+
+```bash
+npm install -g minja
+```
+
+## Quick Start
+
+```typescript
+import { render } from 'minja'
+
+const template = `
+{% set product = "MyApp" %}
+{% set version = "1.0" %}
+
+# {{ product }} Documentation
+
+Version: {{ version }}
+
+{% if version >= "1.0" %}
+This is a stable release.
+{% endif %}
+
+{% include "common/footer.md" %}
+`
+
+const output = await render(template, {
+  context: {
+    author: 'John Doe'
+  }
+})
+
+console.log(output)
+```
+
+## CLI Usage
+
+Minja includes a command-line interface for rendering templates from files or stdin.
+
+### Basic Usage
+
+```bash
+# Render a template file
+minja template.md
+
+# Render with context from JSON file
+minja template.md --context vars.json
+
+# Render with context from YAML file
+minja template.md --context vars.yaml
+
+# Render with inline variables
+minja template.md --vars '{"title":"My Doc","version":"1.0"}'
+
+# Save output to file
+minja template.md --context vars.json --output result.html
+
+# Read from stdin
+cat template.md | minja --vars '{"name":"World"}'
+echo "# {{ title }}" | minja --vars '{"title":"Test"}'
+```
+
+### CLI Options
+
+```
+Usage: minja [options] [template]
+
+Arguments:
+  template                  Template file to render (or read from stdin)
+
+Options:
+  -V, --version             output the version number
+  -c, --context <file>      Context file (JSON or YAML)
+  -o, --output <file>       Output file (default: stdout)
+  -d, --max-depth <number>  Maximum include depth (default: 10)
+  -t, --timeout <ms>        Rendering timeout in milliseconds (default: 5000)
+  -v, --vars <json>         Inline context variables as JSON
+  -r, --include-root <dir>  Refuse {% include %} targets that resolve
+                            (after symlinks) outside this directory
+  -h, --help                display help for command
+```
+
+### Examples
+
+**Simple template rendering:**
+```bash
+minja hello.md --vars '{"name":"World"}'
+```
+
+**With context file:**
+```bash
+# vars.json
+{
+  "product": "MyApp",
+  "version": "2.0"
+}
+
+# Render
+minja README.md --context vars.json
+```
+
+**Using includes:**
+```bash
+# document.md includes common/vars.md
+minja document.md --output docs/index.html
+```
+
+**Untrusted input — contain includes to a directory:**
+```bash
+# Any {% include %} resolving (after symlink resolution) outside docs/
+# is REFUSED and the render fails — without this, an include like
+# "../secrets.txt" or "/etc/hostname" splices any readable file into
+# the output. `..` and absolute paths that stay inside the root are fine.
+minja docs/page.md --include-root docs/
+```
+
+Programmatic equivalent:
+```ts
+import { render, FileSystemLoader } from '@dogsbay/minja'
+const out = await render(template, {
+  basePath: 'docs/',
+  loader: new FileSystemLoader('docs/', { root: 'docs/' }),
+})
+```
+
+**Pipeline usage:**
+```bash
+# Generate docs from multiple sources
+cat header.md content.md footer.md | minja --context config.yaml > output.html
+```
+
+## Syntax
+
+### Variable Substitution
+
+```
+{{ variable }}
+{{ object.property }}
+{{ nested.property.value }}
+```
+
+### Variable Definition
+
+```
+{% set variable = "value" %}
+{% set count = 42 %}
+{% set enabled = true %}
+```
+
+### Conditionals
+
+Basic if statement:
+```
+{% if condition %}
+  Content when true
+{% endif %}
+```
+
+If-else statement:
+```
+{% if condition %}
+  Content when true
+{% else %}
+  Content when false
+{% endif %}
+```
+
+If-elif-else statement:
+```
+{% if platform == "aws" %}
+  Amazon Web Services
+{% elif platform == "azure" %}
+  Microsoft Azure
+{% elif platform == "gcp" %}
+  Google Cloud Platform
+{% else %}
+  Unknown platform
+{% endif %}
+```
+
+### Ifdef/Ifndef (AsciiDoc-style)
+
+```
+{% ifdef variable %}
+  Content when variable is defined
+{% endifdef %}
+
+{% ifndef variable %}
+  Content when variable is not defined
+{% endifndef %}
+```
+
+### Ifeval (Conditional Expressions)
+
+```
+{% ifeval [version >= "1.0"] %}
+  Stable release content
+{% endifeval %}
+
+{% ifeval [platform == "linux"] %}
+  Linux-specific content
+{% endifeval %}
+```
+
+### Switch Statements
+
+Switch-case for multiple conditions:
+```
+{% switch platform %}
+{% case "aws" %}
+  Amazon Web Services (AWS)
+{% case "azure" %}
+  Microsoft Azure
+{% case "gcp" %}
+  Google Cloud Platform (GCP)
+{% endswitch %}
+```
+
+Switch statements support:
+- String and numeric case values
+- Expression-based switch values
+- Multiple case blocks
+- Falls through on first match only (no default case)
+
+### Leveloffset (Heading Level Control)
+
+Shift markdown heading levels in included content:
+
+```
+{% leveloffset +1 %}
+{% include "chapter.md" %}
+{% endleveloffset %}
+```
+
+**Offset types:**
+- **Absolute**: `{% leveloffset 2 %}` - Sets offset to exact value
+- **Relative**: `{% leveloffset +1 %}` or `{% leveloffset -1 %}` - Adds/subtracts from current
+- **Reset**: `{% leveloffset 0 %}` - No offset
+
+**Example:**
+
+`chapter.md`:
+```markdown
+# Chapter Title
+## Section
+```
+
+With `{% leveloffset +1 %}`:
+```markdown
+## Chapter Title
+### Section
+```
+
+This is perfect for modular documentation where you include the same content at different hierarchical levels. Inspired by AsciiDoc's `leveloffset` attribute.
+
+See [Leveloffset documentation](docs/syntax-reference.md#leveloffset-heading-level-control) for detailed usage and examples.
+
+### Includes
+
+```
+{% include "path/to/file.md" %}
+{% include "common/header.md" %}
+```
+
+Includes support:
+- Relative paths
+- Nested includes (with depth limit)
+- URL-based loading (in browsers)
+- Filesystem loading (in Node.js)
+
+### Comments
+
+```
+{# This is a comment and won't appear in output #}
+```
+
+Comments on their own line are automatically stripped along with surrounding whitespace.
+
+### Whitespace Control
+
+Minja supports Nunjucks/Jinja2 whitespace control syntax to manage spacing and newlines in your output.
+
+#### Basic Syntax
+
+- `{%-` - Left strip: removes whitespace before the tag
+- `-%}` - Right strip: removes whitespace after the tag
+- `{%- -%}` - Both: removes whitespace on both sides
+
+#### Examples
+
+**Without whitespace control:**
+```markdown
+{% set product = "MyApp" %}
+{% set version = "1.0" %}
+# {{ product }}
+```
+
+Output (note the blank lines from set statements):
+```
+
+
+# MyApp
+```
+
+**With whitespace control:**
+```markdown
+{%- set product = "MyApp" -%}
+{%- set version = "1.0" -%}
+# {{ product }}
+```
+
+Output (clean, no blank lines):
+```
+# MyApp
+```
+
+**Mixed control:**
+```markdown
+Line 1
+{%- set var = "value" %}
+Line 2
+```
+
+Output (left strip removes newline before set):
+```
+Line 1
+Line 2
+```
+
+#### Best Practices
+
+For attribute files with many set statements, use `{%- set -%}` to avoid blank lines:
+
+`common-attributes.md`:
+```markdown
+{%- set product_name = "MyProduct" -%}
+{%- set product_version = "1.0" -%}
+{%- set company = "ACME Corp" -%}
+```
+
+This prevents each set statement from adding blank lines to your output.
+
+## API
+
+### `render(template, options)`
+
+Render a template string.
+
+```typescript
+async function render(
+  template: string,
+  options?: RenderOptions
+): Promise<string>
+```
+
+**Options:**
+
+- `loader?: Loader` - File loader for includes (default: `FetchLoader`)
+- `context?: Record<string, unknown>` - Initial variables
+- `maxIncludeDepth?: number` - Maximum include recursion depth (default: 10)
+- `timeout?: number` - Rendering timeout in ms (default: 5000)
+
+**Example:**
+
+```typescript
+import { render, FileSystemLoader } from 'minja'
+
+const output = await render(template, {
+  loader: new FileSystemLoader('/path/to/docs'),
+  context: {
+    product: 'MyApp',
+    version: '2.0'
+  },
+  maxIncludeDepth: 5,
+  timeout: 10000
+})
+```
+
+### Loaders
+
+#### `FetchLoader`
+
+For browsers and service workers (uses Fetch API).
+
+```typescript
+import { render, FetchLoader } from 'minja'
+
+const output = await render(template, {
+  loader: new FetchLoader()
+})
+```
+
+#### `FileSystemLoader`
+
+For Node.js (uses `fs.readFile`).
+
+```typescript
+import { render, FileSystemLoader } from 'minja'
+
+const loader = new FileSystemLoader('/base/path')
+const output = await render(template, { loader })
+```
+
+#### `MemoryLoader`
+
+For testing (stores files in memory).
+
+```typescript
+import { render, MemoryLoader } from 'minja'
+
+const loader = new MemoryLoader({
+  'header.md': '# {{ title }}',
+  'footer.md': '© 2026'
+})
+
+const output = await render('{% include "header.md" %}', { loader })
+```
+
+## Security Model
+
+Minja is designed to be **secure by default**:
+
+### What's Allowed
+
+- Variable substitution
+- Safe comparisons (`==`, `!=`, `<`, `>`, `<=`, `>=`)
+- Logical operators (`and`, `or`, `not`)
+- Simple literals (strings, numbers, booleans, null)
+- Dot notation for object properties
+
+### What's Blocked
+
+- ❌ Arbitrary code execution
+- ❌ Function calls (except whitelisted built-ins)
+- ❌ Access to `eval`, `Function`, `require`, `import`
+- ❌ Access to `window`, `process`, `globalThis`
+- ❌ Prototype pollution
+- ❌ Property assignment beyond template variables
+
+### Resource Limits
+
+- Maximum include depth (default: 10)
+- Rendering timeout (default: 5000ms)
+- Expression complexity limits
+
+## Use Cases
+
+Minja is perfect for:
+
+- **Documentation preprocessing**: AsciiDoc-style attribute substitution
+- **Static site generation**: Conditional content based on variables
+- **Multi-variant docs**: Platform-specific or version-specific content
+- **Email templates**: Safe user-data substitution
+- **Configuration files**: Template-driven config generation
+
+## Comparison with Nunjucks/Jinja2
+
+| Feature | minja | Nunjucks |
+|---------|-------|----------|
+| Variable substitution | ✅ | ✅ |
+| Conditionals (if/elif/else) | ✅ | ✅ |
+| Switch statements | ✅ | ❌ |
+| Includes | ✅ | ✅ |
+| Security | ✅ No code execution | ❌ Arbitrary code |
+| AsciiDoc-style | ✅ ifdef/ifndef/ifeval | ❌ |
+| Loops | ❌ | ✅ |
+| Filters | ❌ | ✅ |
+| Macros | ❌ | ✅ |
+| Extends/Blocks | ❌ | ✅ |
+| Bundle size | ~10KB | ~50KB+ |
+
+## Examples
+
+### Platform-Specific Documentation
+
+Using ifeval:
+```markdown
+{% set platform = "linux" %}
+
+# Installation Guide
+
+{% ifeval [platform == "linux"] %}
+Install using your package manager:
+```bash
+sudo apt install myapp
+```
+{% endifeval %}
+
+{% ifeval [platform == "macos"] %}
+Install using Homebrew:
+```bash
+brew install myapp
+```
+{% endifeval %}
+```
+
+Using switch statements:
+```markdown
+{% set platform = "linux" %}
+
+# Installation Guide
+
+{% switch platform %}
+{% case "linux" %}
+Install using your package manager:
+```bash
+sudo apt install myapp
+```
+{% case "macos" %}
+Install using Homebrew:
+```bash
+brew install myapp
+```
+{% case "windows" %}
+Download the installer from our website.
+{% endswitch %}
+```
+
+### Version-Specific Content
+
+```markdown
+{% set version = "2.0" %}
+
+# Features
+
+{% ifeval [version >= "2.0"] %}
+## New in 2.0
+- Feature A
+- Feature B
+{% endifeval %}
+
+{% ifeval [version >= "1.0"] %}
+## Available since 1.0
+- Feature X
+- Feature Y
+{% endifeval %}
+```
+
+### Common Attributes Pattern (AsciiDoc-style)
+
+`common-attributes.md`:
+```
+{%- set product_name = "MyProduct" -%}
+{%- set product_version = "1.0" -%}
+{%- set company = "ACME Corp" -%}
+```
+
+`document.md`:
+```
+{% include "common-attributes.md" %}
+
+# {{ product_name }} Guide
+
+Version {{ product_version }}
+
+Welcome to {{ product_name }} by {{ company }}.
+```
+
+**Note:** Use `{%- set -%}` in attribute files to prevent blank lines in the output.
+
+## Documentation
+
+For complete documentation, see the [docs/](docs/) directory:
+
+- **[Getting Started](docs/getting-started.md)** - Installation and your first template
+- **[Syntax Reference](docs/syntax-reference.md)** - Complete syntax documentation
+- **[AsciiDoc Migration](docs/asciidoc-migration.md)** - Converting from AsciiDoc to Minja
+- **[CLI Usage](docs/cli-usage.md)** - Command-line interface guide
+- **[Examples](docs/examples.md)** - Common patterns and use cases
+- **[API Reference](docs/api-reference.md)** - Programmatic API documentation
+- **[FAQ](docs/faq.md)** - Frequently asked questions
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Test with coverage
+npm run test:coverage
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+## License
+
+MIT