envschema-dsl 0.1.0__tar.gz

envschema_dsl-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: envschema-dsl
+Version: 0.1.0
+Summary: DSL for typed .env files — schema, validation, codegen
+Keywords: env,dotenv,schema,validation,codegen,typescript,pydantic,zod
+Author: nike4192
+Author-email: nike4192 <nike4192@outlook.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: lark>=1.2
+Requires-Dist: click>=8.0
+Requires-Dist: pygls>=2.1.1
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/envschema/envschema
+Project-URL: Repository, https://github.com/envschema/envschema
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# envschema
+
+DSL for typed `.env` files — schema, validation, codegen.
+
+## Install
+
+```bash
+pip install envschema
+# or
+uv add envschema
+```
+
+## Quick Start
+
+Create a `.env.schema` file:
+
+```python
+# Database
+DB_HOST str @required
+DB_PORT port = 5432
+DB_PASSWORD str @secret @required
+DB_NAME str = "myapp"
+
+# App
+NODE_ENV enum("development", "production", "test") = "development"
+PORT int = 3000 : 0 < x < 65535
+DEBUG bool = false
+CORS_ORIGIN str[] = "http://localhost:3000"
+API_KEY str @required : len(x) >= 32
+```
+
+Validate your `.env` file:
+
+```bash
+envschema validate .env.schema --env .env
+```
+
+```
+  ✓ DB_HOST = db.example.com
+  ✓ DB_PORT = 5432
+  ✓ DB_PASSWORD = ***
+  ✓ NODE_ENV = development
+  ✓ PORT = 3000
+  ✗ API_KEY — validation failed: len(x) >= 32 (x='short')
+  ⚠ UNKNOWN_VAR — not defined in schema
+
+Result: 5 OK, 1 errors, 1 warnings
+```
+
+Generate code:
+
+```bash
+envschema generate .env.schema -t ts          # TypeScript interface
+envschema generate .env.schema -t zod         # Zod v4 schema
+envschema generate .env.schema -t pydantic    # Pydantic BaseSettings
+envschema generate .env.schema -t dataclasses # Python dataclass (no deps)
+envschema generate .env.schema -t env-example # .env.example
+```
+
+## Features
+
+### Types
+
+```python
+HOST str = "localhost"            # string
+PORT int = 3000                   # integer
+RATIO float = 0.5                 # float
+DEBUG bool = false                # boolean
+API_PORT port = 8080              # port (int 1-65535)
+BASE_URL url                      # URL (any scheme://)
+ADMIN_EMAIL email                 # email
+DATA_DIR path = "/var/data"       # filesystem path
+NODE_ENV enum("dev", "prod")      # enum
+HOSTS str[]                       # array (comma-separated)
+```
+
+Type inference from defaults — `PORT = 3000` is inferred as `int`.
+
+### Decorators
+
+```python
+DB_HOST str @required                      # must be set
+DB_PASSWORD str @secret @required          # hidden in output
+LOG_LEVEL str @description("Logging level") # description
+```
+
+### Inline Validation
+
+Python expressions with `x` as the value:
+
+```python
+PORT int = 3000 : 0 < x < 65535
+API_KEY str @required : len(x) >= 32
+RATE_LIMIT int = 100 : 0 < x < 10000
+```
+
+### Block Syntax
+
+For complex variables:
+
+```python
+DATABASE_URL {
+    type = url
+    description = "PostgreSQL connection string"
+    @secret
+    @required
+    validate = "x.startswith('postgres://')"
+}
+```
+
+### Type Aliases
+
+```python
+type LogLevel = enum("error", "warn", "info", "debug")
+type ExtendedEnv = NodeEnv + enum("local")
+
+LOG_LEVEL LogLevel = "warn"
+```
+
+### Presets
+
+```python
+#include <node.js>       # built-in preset (NODE_ENV, PORT, HOST)
+#include <vite>          # VITE_* variables
+#include "shared.schema" # local file
+
+APP_NAME str = "myapp"
+```
+
+```bash
+envschema presets list             # list available presets
+envschema presets load directus    # download from registry
+```
+
+### Wildcard Expansion
+
+```python
+AUTH_PROVIDERS str[] = "google,github"
+
+AUTH_{AUTH_PROVIDERS}_DRIVER str @required
+AUTH_{AUTH_PROVIDERS}_CLIENT_ID str @secret @required
+AUTH_{AUTH_PROVIDERS}_CLIENT_SECRET str @secret @required
+```
+
+Expands to `AUTH_GOOGLE_DRIVER`, `AUTH_GITHUB_DRIVER`, etc.
+Default filter: `upper`. Custom: `{AUTH_PROVIDERS|lower}`.
+
+## CLI
+
+```bash
+envschema parse <file>              # parse and display AST
+envschema parse <file> --json       # output as JSON
+envschema validate <schema> --env <env>  # validate .env against schema
+envschema generate <schema> -t <target>  # generate code
+envschema generators list           # list available targets
+envschema presets list              # list presets
+envschema presets load <name>       # download preset
+envschema lsp                       # start LSP server (stdio)
+```
+
+## VS Code Extension
+
+```bash
+cd editors/vscode/envschema
+npx @vscode/vsce package --allow-missing-repository
+cursor --install-extension envschema-0.1.0.vsix
+```
+
+Provides syntax highlighting for `.env.schema` files.
+
+## License
+
+MIT

envschema_dsl-0.1.0/README.md

@@ -0,0 +1,173 @@
+# envschema
+
+DSL for typed `.env` files — schema, validation, codegen.
+
+## Install
+
+```bash
+pip install envschema
+# or
+uv add envschema
+```
+
+## Quick Start
+
+Create a `.env.schema` file:
+
+```python
+# Database
+DB_HOST str @required
+DB_PORT port = 5432
+DB_PASSWORD str @secret @required
+DB_NAME str = "myapp"
+
+# App
+NODE_ENV enum("development", "production", "test") = "development"
+PORT int = 3000 : 0 < x < 65535
+DEBUG bool = false
+CORS_ORIGIN str[] = "http://localhost:3000"
+API_KEY str @required : len(x) >= 32
+```
+
+Validate your `.env` file:
+
+```bash
+envschema validate .env.schema --env .env
+```
+
+```
+  ✓ DB_HOST = db.example.com
+  ✓ DB_PORT = 5432
+  ✓ DB_PASSWORD = ***
+  ✓ NODE_ENV = development
+  ✓ PORT = 3000
+  ✗ API_KEY — validation failed: len(x) >= 32 (x='short')
+  ⚠ UNKNOWN_VAR — not defined in schema
+
+Result: 5 OK, 1 errors, 1 warnings
+```
+
+Generate code:
+
+```bash
+envschema generate .env.schema -t ts          # TypeScript interface
+envschema generate .env.schema -t zod         # Zod v4 schema
+envschema generate .env.schema -t pydantic    # Pydantic BaseSettings
+envschema generate .env.schema -t dataclasses # Python dataclass (no deps)
+envschema generate .env.schema -t env-example # .env.example
+```
+
+## Features
+
+### Types
+
+```python
+HOST str = "localhost"            # string
+PORT int = 3000                   # integer
+RATIO float = 0.5                 # float
+DEBUG bool = false                # boolean
+API_PORT port = 8080              # port (int 1-65535)
+BASE_URL url                      # URL (any scheme://)
+ADMIN_EMAIL email                 # email
+DATA_DIR path = "/var/data"       # filesystem path
+NODE_ENV enum("dev", "prod")      # enum
+HOSTS str[]                       # array (comma-separated)
+```
+
+Type inference from defaults — `PORT = 3000` is inferred as `int`.
+
+### Decorators
+
+```python
+DB_HOST str @required                      # must be set
+DB_PASSWORD str @secret @required          # hidden in output
+LOG_LEVEL str @description("Logging level") # description
+```
+
+### Inline Validation
+
+Python expressions with `x` as the value:
+
+```python
+PORT int = 3000 : 0 < x < 65535
+API_KEY str @required : len(x) >= 32
+RATE_LIMIT int = 100 : 0 < x < 10000
+```
+
+### Block Syntax
+
+For complex variables:
+
+```python
+DATABASE_URL {
+    type = url
+    description = "PostgreSQL connection string"
+    @secret
+    @required
+    validate = "x.startswith('postgres://')"
+}
+```
+
+### Type Aliases
+
+```python
+type LogLevel = enum("error", "warn", "info", "debug")
+type ExtendedEnv = NodeEnv + enum("local")
+
+LOG_LEVEL LogLevel = "warn"
+```
+
+### Presets
+
+```python
+#include <node.js>       # built-in preset (NODE_ENV, PORT, HOST)
+#include <vite>          # VITE_* variables
+#include "shared.schema" # local file
+
+APP_NAME str = "myapp"
+```
+
+```bash
+envschema presets list             # list available presets
+envschema presets load directus    # download from registry
+```
+
+### Wildcard Expansion
+
+```python
+AUTH_PROVIDERS str[] = "google,github"
+
+AUTH_{AUTH_PROVIDERS}_DRIVER str @required
+AUTH_{AUTH_PROVIDERS}_CLIENT_ID str @secret @required
+AUTH_{AUTH_PROVIDERS}_CLIENT_SECRET str @secret @required
+```
+
+Expands to `AUTH_GOOGLE_DRIVER`, `AUTH_GITHUB_DRIVER`, etc.
+Default filter: `upper`. Custom: `{AUTH_PROVIDERS|lower}`.
+
+## CLI
+
+```bash
+envschema parse <file>              # parse and display AST
+envschema parse <file> --json       # output as JSON
+envschema validate <schema> --env <env>  # validate .env against schema
+envschema generate <schema> -t <target>  # generate code
+envschema generators list           # list available targets
+envschema presets list              # list presets
+envschema presets load <name>       # download preset
+envschema lsp                       # start LSP server (stdio)
+```
+
+## VS Code Extension
+
+```bash
+cd editors/vscode/envschema
+npx @vscode/vsce package --allow-missing-repository
+cursor --install-extension envschema-0.1.0.vsix
+```
+
+Provides syntax highlighting for `.env.schema` files.
+
+## License
+
+MIT

envschema_dsl-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "envschema-dsl"
+version = "0.1.0"
+description = "DSL for typed .env files — schema, validation, codegen"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "nike4192", email = "nike4192@outlook.com" }
+]
+requires-python = ">=3.12"
+keywords = ["env", "dotenv", "schema", "validation", "codegen", "typescript", "pydantic", "zod"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "lark>=1.2",
+    "click>=8.0",
+    "pygls>=2.1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/envschema/envschema"
+Repository = "https://github.com/envschema/envschema"
+
+[project.scripts]
+envschema = "envschema.cli:cli"
+
+[tool.uv.build-backend]
+module-name = "envschema"
+# PyPI name: envschema-dsl (envschema was taken)
+# Import: from envschema import ...
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"

envschema_dsl-0.1.0/src/envschema/__init__.py

@@ -0,0 +1,23 @@
+"""EnvSchema — DSL for typed .env files."""
+
+from .ast import (
+    ArrayType, Comment, Decorator, EnumType, Expansion, Include,
+    Schema, SimpleType, TypeAlias, TypeRef, UnionType, Variable,
+)
+from .parser import parse, parse_file
+
+__all__ = [
+    "ArrayType",
+    "Comment",
+    "Decorator",
+    "EnumType",
+    "Include",
+    "Schema",
+    "SimpleType",
+    "TypeAlias",
+    "TypeRef",
+    "UnionType",
+    "Variable",
+    "parse",
+    "parse_file",
+]

envschema_dsl-0.1.0/src/envschema/ast.py

@@ -0,0 +1,108 @@
+"""AST node definitions for EnvSchema DSL."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class SimpleType(Enum):
+    STR = "str"
+    INT = "int"
+    FLOAT = "float"
+    BOOL = "bool"
+    PORT = "port"
+    URL = "url"
+    EMAIL = "email"
+    PATH = "path"
+
+
+@dataclass
+class EnumType:
+    values: list[str]
+
+
+@dataclass
+class TypeRef:
+    """Reference to a named type (from type alias or preset)."""
+    name: str
+
+
+@dataclass
+class UnionType:
+    """Union of types: TypeA + TypeB."""
+    types: list[SimpleType | EnumType | TypeRef]
+
+
+@dataclass
+class ArrayType:
+    element_type: SimpleType | EnumType | TypeRef
+
+
+@dataclass
+class Decorator:
+    name: str
+    arg: str | None = None
+
+
+@dataclass
+class Expansion:
+    """Wildcard expansion marker — {PROVIDERS} or {PROVIDERS|upper}."""
+    source: str  # Variable name to expand from (e.g., "PROVIDERS")
+    filter: str | None = None  # Optional filter (e.g., "upper")
+
+
+@dataclass
+class Include:
+    """#include directive."""
+    target: str  # preset name or file path
+    is_local: bool = False  # True for "path", False for <preset>
+    line: int | None = None
+
+
+@dataclass
+class TypeAlias:
+    """type Name = expr."""
+    name: str
+    value: SimpleType | EnumType | TypeRef | UnionType
+    line: int | None = None
+
+
+@dataclass
+class Variable:
+    name: str
+    type: SimpleType | EnumType | ArrayType | TypeRef | None = None
+    default: str | int | float | bool | None = None
+    decorators: list[Decorator] = field(default_factory=list)
+    validation: str | None = None
+    expansion: Expansion | None = None
+    line: int | None = None
+
+    @property
+    def is_required(self) -> bool:
+        return any(d.name == "required" for d in self.decorators)
+
+    @property
+    def is_secret(self) -> bool:
+        return any(d.name == "secret" for d in self.decorators)
+
+
+@dataclass
+class Comment:
+    text: str
+    line: int | None = None
+
+
+@dataclass
+class Schema:
+    variables: list[Variable] = field(default_factory=list)
+    comments: list[Comment] = field(default_factory=list)
+    includes: list[Include] = field(default_factory=list)
+    type_aliases: list[TypeAlias] = field(default_factory=list)
+
+    def resolve_type(self, name: str) -> SimpleType | EnumType | UnionType | None:
+        """Look up a type alias by name."""
+        for alias in self.type_aliases:
+            if alias.name == name:
+                return alias.value
+        return None