Feat/92 new

docs/schemax/docs/guide/naming-standards.mdx

@@ -0,0 +1,141 @@
+---
+sidebar_position: 17
+title: Naming Standards
+description: Enforce consistent naming conventions for Unity Catalog objects with regex-based rules, built-in templates, and strict mode.
+---
+
+# Naming Standards
+
+SchemaX lets you define and enforce naming conventions for Unity Catalog objects — catalogs, schemas, tables, views, and columns — using regex-based rules stored in `project.json`. Rules are checked when you add or rename objects in the VS Code Designer and during `validate`, `sql`, and `apply`.
+
+## Configuration
+
+Naming standards live under `settings.namingStandards` in `project.json`:
+
+```json
+{
+  "settings": {
+    "namingStandards": {
+      "strictMode": false,
+      "applyToRenames": false,
+      "catalog": { "pattern": "^[a-z][a-z0-9_]*$", "description": "Lowercase snake_case", "enabled": true },
+      "schema":  { "pattern": "^[a-z][a-z0-9_]*$", "description": "Lowercase snake_case", "enabled": true },
+      "table":   { "pattern": "^[a-z][a-z0-9_]*$", "description": "Lowercase snake_case", "enabled": true },
+      "view":    { "pattern": "^[a-z][a-z0-9_]*$", "description": "Lowercase snake_case", "enabled": true },
+      "column":  { "pattern": "^[a-z][a-z0-9_]*$", "description": "Lowercase snake_case", "enabled": true }
+    }
+  }
+}
+```
+
+Each rule has:
+- **`pattern`** — A Python-compatible full-match regex (e.g. `^[a-z][a-z0-9_]*$`).
+- **`enabled`** — `true` to enforce, `false` to disable without removing the rule.
+- **`description`** — Optional human-readable label shown in error messages.
+
+## VS Code Designer
+
+Open **Project Settings** (gear icon in the Designer toolbar) and expand the **Naming Standards** section. From there you can:
+
+- Apply a built-in template (see [Templates](#templates) below).
+- Add, edit, or remove rules per object type.
+- Toggle **Strict Mode** and **Enforce on Renames**.
+
+When you add or rename an object in the Designer:
+- **Add** — A matching rule is checked. In strict mode, a non-compliant name blocks the add. In warn-only mode, the add is allowed with a warning.
+- **Rename** — When **Enforce on Renames** is on, a soft warning modal appears; you can proceed or cancel.
+
+## CLI
+
+### Quick start
+
+```bash
+# Apply the Databricks preset (lowercase snake_case for all types)
+schemax naming load-template databricks
+
+# Turn on strict mode so validate/sql/apply fail on violations
+schemax naming strict on
+
+# Show the current config
+schemax naming show
+```
+
+### Commands
+
+```bash
+# Show naming config (--json for machine-readable output)
+schemax naming show [--json] [workspace]
+
+# Strict mode: on = fail on violations; off = warn only
+schemax naming strict on|off [workspace]
+
+# Enforce on renames: on = soft warning on non-compliant renames
+schemax naming enforce-on-renames on|off [workspace]
+
+# Add/update a rule for an object type
+schemax naming set-rule table '^[a-z][a-z0-9_]*$' --description 'Lowercase snake_case' [workspace]
+
+# Remove a rule for an object type (no validation for that type)
+schemax naming remove-rule table [workspace]
+
+# List built-in preset ids and descriptions (optional --json)
+schemax naming templates
+
+# Apply a built-in preset (databricks | warehouse)
+schemax naming load-template databricks [workspace]
+
+# Set a full config from JSON or stdin (writes project.json locally)
+schemax naming set-config --json '{"strictMode": true, "table": {"pattern": "^[a-z][a-z0-9_]*$", "enabled": true}}' [workspace]
+schemax naming show --json | schemax naming set-config --stdin [workspace]
+
+# Validate a single name against the project's naming rules
+schemax validate --naming --name my_table --type table [workspace]
+```
+
+### Validate integration
+
+`schemax validate` automatically checks all objects in the current state against configured naming rules. With **strict mode off**, violations appear as warnings. With **strict mode on**, violations are reported as errors and the command exits non-zero, blocking `sql` and `apply`.
+
+```bash
+schemax validate                # Full validation including naming
+schemax validate --naming --name BadTable --type table   # Single-name check
+```
+
+## Templates
+
+Two built-in presets are available via `schemax naming load-template` (CLI) or the **Apply Template** button in VS Code:
+
+| Preset | CLI name | Rules |
+|--------|----------|-------|
+| **Databricks Best Practices** | `databricks` | Lowercase snake_case (`^[a-z][a-z0-9_]*$`) for all object types. |
+| **Data Warehouse Patterns** | `warehouse` | Prefixed tables (`^(dim_\|fact_\|stg_\|int_)[a-z0-9_]+$`), lowercase snake_case for all other types. |
+
+Templates replace all existing rules and set `strictMode` and `applyToRenames` to `false`. Adjust those toggles separately after applying a template.
+
+## Strict Mode vs. Warn-Only
+
+| Mode | Add / Rename in Designer | `validate` | `sql` / `apply` |
+|------|--------------------------|-----------|-----------------|
+| **Strict off** | Warning shown; action allowed | Violations in warnings section | Allowed (warnings in output) |
+| **Strict on** | Non-compliant add blocked; rename shows warning | Violations in errors section (exit 1) | Blocked until violations fixed |
+
+## Custom Patterns
+
+Patterns are full-match Python regexes (equivalent to `re.fullmatch`). Examples:
+
+| Convention | Pattern |
+|------------|---------|
+| Lowercase snake_case | `^[a-z][a-z0-9_]*$` |
+| Prefixed DWH tables | `^(dim_\|fact_\|stg_\|int_)[a-z0-9_]+$` |
+| Allow digits at start | `^[a-z0-9][a-z0-9_]*$` |
+| Max 64 characters | `^[a-z][a-z0-9_]{0,63}$` |
+
+When a name fails, SchemaX suggests a sanitised alternative (lowercased, hyphens/spaces replaced with underscores, non-word characters stripped).
+
+## Pipe config between projects
+
+```bash
+# Copy naming config from one workspace to another
+cd /path/to/source && schemax naming show --json | \
+  schemax naming set-config --stdin /path/to/target
+```

docs/schemax/docs/reference/cli.mdx

@@ -13,7 +13,23 @@ Summary of the SchemaX CLI. Run `schemax --help` and `schemax <command> --
 | Command | Description |
 |---------|-------------|
 | `schemax init` | Initialize a new SchemaX project (or use VS Code Designer once). |
-| `schemax validate [workspace]` | Validate `.schemax/` project files and dependency graph. |
+| `schemax validate [workspace]` | Validate `.schemax/` project files and dependency graph. Naming violations are reported as errors (strict mode) or warnings. |
+| `schemax validate --naming --name NAME --type TYPE [workspace]` | Validate a single object name against naming standards. `--type` is one of `catalog`, `schema`, `table`, `view`, `column`. |
+
+## Naming Standards
+
+Manage per-object-type naming rules stored in `project.json` under `settings.namingStandards`. See the [Naming Standards guide](/docs/guide/naming-standards) for full details.
+
+| Command | Description |
+|---------|-------------|
+| `schemax naming show [--json] [workspace]` | Show current naming config (patterns, enabled flags, strict mode, enforce-on-renames). `--json` outputs machine-readable config. |
+| `schemax naming strict on\|off [workspace]` | Toggle strict mode. When **on**: `validate`, `sql`, and `apply` fail on naming violations and non-compliant adds are blocked. When **off**: violations produce warnings only. |
+| `schemax naming enforce-on-renames on\|off [workspace]` | Toggle enforce-on-renames. When **on**: renaming to a non-compliant name shows a soft warning (does not block). |
+| `schemax naming set-rule OBJECT_TYPE PATTERN [--description DESC] [--enabled/--disabled] [workspace]` | Add or update a naming rule for an object type (`catalog`, `schema`, `table`, `view`, `column`). `PATTERN` must be a valid Python regex (e.g. `^[a-z][a-z0-9_]*$`). |
+| `schemax naming remove-rule OBJECT_TYPE [workspace]` | Remove the naming rule for an object type (no validation for that type). |
+| `schemax naming templates [--json]` | List built-in preset ids and short descriptions (same presets as `load-template`). No workspace required. `--json` returns `{ "presets": [ { "id", "description" }, ... ] }`. |
+| `schemax naming load-template PRESET [workspace]` | Apply a built-in preset — `databricks` (lowercase snake_case for all types) or `warehouse` (prefixed tables: `dim_`, `fact_`, `stg_`, `int_`). Replaces all existing rules; toggles are set to off. |
+| `schemax naming set-config [--json CONFIG \| --stdin] [workspace]` | Write the full naming config to `project.json` from a JSON string or stdin (local only; not `schemax apply`). Same shape as `settings.namingStandards` (camelCase). Use `naming show --json` to capture and pipe configs. |
 
 ## SQL and snapshots
 

docs/schemax/docs/reference/release-notes.mdx

@@ -6,6 +6,29 @@ This page summarizes coordinated SchemaX releases across:
 - VS Code extension (`schemax-vscode`)
 - Documentation site (`docs/schemax`)
 
+## 0.2.12 (2026-03-16)
+
+### Highlights
+
+- **Naming Standards** — Define and enforce regex-based naming conventions for catalogs, schemas, tables, views, and columns. Rules are stored in `project.json` under `settings.namingStandards` and checked on add/rename in the Designer, and during `validate`, `sql`, and `apply`.
+- **`schemax naming` command group** — New CLI subcommands: `naming show`, `naming strict on|off`, `naming enforce-on-renames on|off`, `naming set-rule`, `naming remove-rule`, `naming templates` (list preset ids and descriptions), `naming load-template`, and `naming set-config` (accepts JSON or stdin).
+- **`schemax validate --naming`** — Single-name validation: `schemax validate --naming --name my_table --type table` checks one name against the project's configured rules.
+- **Built-in templates** — Two presets available via CLI (`databricks`, `warehouse`) and VS Code (**Apply Template** button): Databricks Best Practices (lowercase snake_case) and Data Warehouse Patterns (prefixed tables).
+- **Strict mode** — When enabled, naming violations fail `validate` (exit 1) and block `sql` and `apply`. When disabled, violations appear as warnings only.
+- **Enforce on renames** — Optional soft-warning modal in the Designer when renaming an object to a non-compliant name.
+- **VS Code Naming Standards Settings panel** — New collapsible section in Project Settings with rule editor, template picker, and toggle controls.
+
+### Package versions
+
+- Python SDK/CLI: `0.2.12`
+- VS Code extension: `0.2.12`
+- Docs site package: `0.2.12`
+
+### Changelogs
+
+- [Python SDK changelog](https://github.com/vb-dbrks/schemax-vscode/blob/main/packages/python-sdk/CHANGELOG.md)
+- [VS Code extension changelog](https://github.com/vb-dbrks/schemax-vscode/blob/main/packages/vscode-extension/CHANGELOG.md)
+
 ## 0.2.11 (2026-03-11)
 
 ### Highlights