feat: add directory SQL formatting command

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.7
+
+- Consolidated developer documentation into `docs/DEVELOPMENT.md` and `docs/SQL_IMPLEMENTATION.md`.
+- Added **SQLovely: Format SQL Files in Directory** to recursively format `.sql` files in a selected directory.
+- Directory formatting runs without SQLovely Extras by default for safer batch formatting.
+- Documented directory SQL formatting command usage.
+
 ## 0.1.6
 
 - Changed generated metadata headers to the compact pre-`BEGIN` `-- METADATA` layout.

CONTRIBUTING.md

@@ -1,6 +1,10 @@
 # Contributing
 
-Use the standard validation commands before opening a pull request:
+Thank you for considering a contribution to SQLovely.
+
+## Before opening a pull request
+
+Run the standard validation commands:
 
 ```bash
 npm ci
@@ -9,4 +13,16 @@ npm test
 npm run package:vsix
 ```
 
-Keep formatter behavior conservative and add regression tests for every behavior change.
+## Guidelines
+
+- Keep formatter behavior conservative.
+- Add regression tests for behavior changes.
+- Keep `README.md` user-facing.
+- Put maintainer/developer details in `docs/`.
+- Update `CHANGELOG.md` for user-visible changes.
+
+For development setup and implementation notes, see:
+
+- `docs/DEVELOPMENT.md`
+- `docs/SQL_IMPLEMENTATION.md`
+- `PACKAGING.md`

README.md

@@ -1,25 +1,23 @@
 # SQLovely
 
-SQLovely is a VS Code extension for `.sql` files. It provides SQL highlighting, conservative formatting, metadata-header extras, diagnostics and quick fixes.
+SQLovely adds practical SQL language support for `.sql` files in VS Code.
 
-Watcom SQL is the default dialect. MSSQL support is available as a small secondary dialect surface, not as a complete T-SQL implementation.
+It is focused on Watcom SQL by default and also includes a small MSSQL-oriented dialect surface for projects that need basic SQL Server-style support.
 
-## Install locally
+## Features
 
-Build the package:
+- SQL syntax highlighting for regular `.sql` files
+- Conservative SQL formatting
+- Optional metadata-header extras for procedures, functions and triggers
+- Diagnostics and quick fixes for supported SQLovely rules
+- Watcom SQL as the default dialect
+- Basic MSSQL support for common T-SQL-style files
 
-```bash
-npm install
-npm run package:vsix
-```
-
-Install the resulting VSIX:
+## Quick start
 
-```bash
-code --install-extension out/sqlovely-*.vsix
-```
+Open a `.sql` file and run commands from the VS Code Command Palette.
 
-## Recommended workspace settings
+Recommended workspace setting:
 
 ```json
 {
@@ -30,7 +28,7 @@ code --install-extension out/sqlovely-*.vsix
 }
 ```
 
-To let VS Code format SQL files automatically on save, enable format-on-save for the SQL language:
+To format SQL files automatically when saving:
 
 ```json
 {
@@ -41,97 +39,44 @@ To let VS Code format SQL files automatically on save, enable format-on-save for
 }
 ```
 
-SQLovely Extras are applied during SQLovely formatting by default. This lets **Format Document** and VS Code format-on-save also keep supported metadata headers up to date. Disable it if formatting should only touch whitespace, indentation and keyword casing:
-
-```json
-{
-  "sqlovely.extras.applyWithFormatting": true
-}
-```
-
-Extras can also run as a separate save participant. This is disabled by default because it can update files even when formatting is not requested:
-
-```json
-{
-  "sqlovely.extras.applyOnSave": false
-}
-```
-
 ## Commands
 
 - **SQLovely: Show Active Dialect**
 - **SQLovely: Switch Dialect**
 - **SQLovely: Format Current SQL File**
+- **SQLovely: Format SQL Files in Directory**
 - **SQLovely: Insert or Update Metadata Header**
 - **SQLovely: Apply SQLovely Extras**
 
-## Dialects
-
-The active dialect is configured with:
-
-```json
-{
-  "sqlovely.dialect": "watcom"
-}
-```
+## Formatting
 
-Supported values:
+SQLovely formats conservatively. It keeps SQL structure intact and focuses on readable, predictable cleanup:
 
-- `watcom`: default dialect
-- `mssql`: small secondary dialect surface
-
-The TextMate grammar is a broad SQLovely grammar for `.sql` files. Dialect-specific behavior lives in the formatter, object detection, SQLovely Extras, diagnostics and quick fixes.
-
-## Syntax highlighting
-
-The grammar covers the SQL structures SQLovely needs for regular SQL work:
-
-- `--`, `//` and `/* ... */` comments
-- single-quoted strings with doubled apostrophe escaping
-- binary/hex literals
-- bracketed, double-quoted and backtick identifiers
-- host variables, local variables, system variables and positional parameters
-- numeric literals
-- common SQL, Watcom SQL and SQL Server data types
-- common built-in scalar, aggregate, date/time, XML and window functions
-- DDL, DML, transaction and control-flow keywords
-- procedure, function and trigger declarations
-- common schema-object declarations
-- `GO` batch separators for MSSQL-oriented files
+- keyword and function casing
+- basic block indentation
+- trailing whitespace removal
+- limiting consecutive blank lines
+- final newline handling
 
-The grammar is designed for highlighting. It is not a full SQL parser.
+The formatter does not rewrite queries, split statements, align joins or migrate SQL between dialects.
 
-See `docs/SYNTAX_GRAMMAR.md` and `docs/SQL_COVERAGE.md` for the detailed coverage matrix.
+### Format one file
 
-## Formatter
+Use **SQLovely: Format Current SQL File** or VS Code's built-in **Format Document** command.
 
-The formatter is conservative and line-oriented. Its defaults follow a compact SQL style: upper-case keywords/functions, spaces for indentation, 2-space indentation, trimmed trailing whitespace and a final newline. It supports:
+### Format a directory
 
-- keyword/function casing
-- basic Watcom block indentation
-- simple `BEGIN` / `END`, `IF` / `ELSE` / `ENDIF`, `CASE` and MSSQL `TRY` / `CATCH` indentation
-- trailing whitespace removal
-- limiting consecutive blank lines
-- optional final newline enforcement
+Use **SQLovely: Format SQL Files in Directory** to format every `.sql` file inside a selected folder.
 
-It does not rewrite query structure, split statements, align JOINs or convert between dialects.
+The command opens a folder picker, searches recursively for `.sql` files, asks for confirmation and then formats each file. It skips common local/build folders such as `.git`, `node_modules`, `out` and `dist`.
 
-Formatter settings:
-
-```json
-{
-  "sqlovely.format.enabled": true,
-  "sqlovely.format.keywordCase": "upper",
-  "sqlovely.format.indentSize": 2,
-  "sqlovely.format.insertSpaces": true,
-  "sqlovely.format.maxConsecutiveBlankLines": 1,
-  "sqlovely.format.ensureFinalNewline": true
-}
-```
+Directory formatting intentionally applies formatting only. SQLovely Extras are not applied during this command.
 
 ## SQLovely Extras
 
-SQLovely Extras are optional features that can update SQL files beyond pure formatting. The current extra inserts or updates a metadata header for procedures, functions and triggers.
+SQLovely Extras are optional file-updating features beyond pure formatting.
+
+The current extra inserts or updates a metadata header for procedures, functions and triggers:
 
 ```sql
 CREATE PROCEDURE dbo.my_proc()
@@ -152,52 +97,70 @@ BEGIN
 END;
 ```
 
-The header is inserted directly before the first `BEGIN` line of the detected procedure, function or trigger. Existing older SQLovely headers are moved to this layout when they are updated.
+The header is inserted directly before the first `BEGIN` line of the detected object. Repeated runs update the existing SQLovely block instead of duplicating it.
 
-Repeated runs update the existing SQLovely block instead of duplicating it. Object detection ignores declarations inside comments and single-quoted strings.
+Extras are applied during normal SQLovely formatting by default:
 
-Extra settings:
+```json
+{
+  "sqlovely.extras.applyWithFormatting": true
+}
+```
+
+Disable this if formatting should only touch whitespace, indentation and keyword casing:
 
 ```json
 {
-  "sqlovely.extras.enabled": true,
-  "sqlovely.extras.applyWithFormatting": true,
-  "sqlovely.extras.applyOnSave": false,
-  "sqlovely.extras.metadataHeader.enabled": true
+  "sqlovely.extras.applyWithFormatting": false
 }
 ```
 
-## Diagnostics and quick fixes
+Extras can also run as a separate save participant. This is disabled by default:
 
-SQLovely warns when a supported procedure, function or trigger has no SQLovely metadata header. The quick fix inserts the same idempotent header used by the command.
+```json
+{
+  "sqlovely.extras.applyOnSave": false
+}
+```
+
+## Dialects
 
-Diagnostics do not change files by themselves. In addition to missing metadata headers, SQLovely can show informational diagnostics for lines longer than the configured style limit.
+The active dialect is configured with:
 
 ```json
 {
-  "sqlovely.diagnostics.maxLineLength.enabled": true,
-  "sqlovely.diagnostics.maxLineLength.limit": 120
+  "sqlovely.dialect": "watcom"
 }
 ```
 
-## Documentation
+Supported values:
 
-- `docs/GETTING_STARTED.md`
-- `docs/WORKSPACE_SETTINGS.md`
-- `docs/SYNTAX_GRAMMAR.md`
-- `docs/SQL_COVERAGE.md`
-- `PACKAGING.md`
+- `watcom`: default dialect
+- `mssql`: small secondary dialect surface
+
+The syntax grammar is intentionally broad. Dialect-specific behavior is handled by formatting, object detection, extras, diagnostics and quick fixes.
+
+## Diagnostics
 
-## Development
+SQLovely can show diagnostics for supported rules, such as:
 
-```bash
-npm install
-npm run check
-npm test
-npm run package:vsix
+- missing metadata headers for procedures, functions and triggers
+- SQL lines longer than the configured line-length limit
+
+Diagnostics do not modify files by themselves. Quick fixes can apply supported changes when selected.
+
+```json
+{
+  "sqlovely.diagnostics.enabled": true,
+  "sqlovely.diagnostics.maxLineLength.limit": 120
+}
 ```
 
-Run in an Extension Development Host with `F5` from VS Code.
+## Documentation
+
+- `docs/DEVELOPMENT.md`
+- `docs/SQL_IMPLEMENTATION.md`
+- `PACKAGING.md`
 
 ## Current limits
 

docs/DEVELOPMENT.md

@@ -0,0 +1,93 @@
+# Development
+
+This document contains the development workflow for SQLovely.
+
+For user-facing extension usage, see `README.md`.
+For release packaging, see `PACKAGING.md`.
+
+## Setup
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+For a clean install from the lockfile:
+
+```bash
+npm ci
+```
+
+## Validate
+
+Run TypeScript checks:
+
+```bash
+npm run check
+```
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Build a VSIX package:
+
+```bash
+npm run package:vsix
+```
+
+The generated package is written to `out/`.
+
+## Extension Development Host
+
+Open the repository in VS Code and press `F5` to start an Extension Development Host.
+
+Useful smoke tests:
+
+- open a `.sql` file
+- run **SQLovely: Show Active Dialect**
+- run **SQLovely: Format Current SQL File**
+- run **SQLovely: Format SQL Files in Directory**
+- run **SQLovely: Insert or Update Metadata Header**
+- verify diagnostics and quick fixes
+
+## Settings during development
+
+A practical development workspace setup is:
+
+```json
+{
+  "sqlovely.dialect": "watcom",
+  "sqlovely.format.enabled": true,
+  "sqlovely.format.keywordCase": "upper",
+  "sqlovely.format.indentSize": 2,
+  "sqlovely.format.insertSpaces": true,
+  "sqlovely.extras.applyWithFormatting": true,
+  "sqlovely.extras.applyOnSave": false,
+  "[sql]": {
+    "editor.defaultFormatter": "tim-mayer.sqlovely"
+  }
+}
+```
+
+For MSSQL-oriented smoke tests:
+
+```json
+{
+  "sqlovely.dialect": "mssql",
+  "sqlovely.extras.applyWithFormatting": true,
+  "sqlovely.extras.applyOnSave": false,
+  "[sql]": {
+    "editor.defaultFormatter": "tim-mayer.sqlovely"
+  }
+}
+```
+
+## Directory formatting behavior
+
+**SQLovely: Format SQL Files in Directory** uses the normal `sqlovely.format.*` settings.
+
+It intentionally does not apply SQLovely Extras. Keep this behavior conservative because the command can touch many files at once.