@timeax/scaffold 0.0.3 → 0.0.5

package/readme.md

@@ -1,4 +1,4 @@
-# @timeax/scaffold
+# Scaffold – `@timeax/scaffold`
 
 A tiny, opinionated scaffolding tool that keeps your project structure in sync with a **declarative tree** (like `structure.txt`) – Prisma‑style.
 
@@ -8,34 +8,30 @@ A tiny, opinionated scaffolding tool that keeps your project structure in sync w
 * Reverse‑engineer existing projects into `*.txt` structures.
 * Watch for changes and re‑apply automatically.
 
-> **Supported structure files:** `.tss`, `.stx`, `structure.txt`, and any `.txt` files inside `.scaffold/`.
+> **Supported structure files:** `.tss`, `.stx`, `structure.txt` (and any `.txt` inside `.scaffold/`).
 
 ---
 
 ## Features
 
-* **Prisma‑style scaffold directory**: all config and structure lives under `.scaffold/` by default.
+* **Prisma‑style scaffold directory**: all config and structures live under a hidden root, **`.scaffold/`**, by default.
 * **Config‑driven groups**: declare multiple roots (e.g. `app`, `frontend`) with their own structure files.
 * **Plain‑text structure files**: strict, easy‑to‑read tree syntax with indentation and annotations.
 * **Safe apply**:
 
-  * Creates missing files/directories.
-  * Tracks what it created in a cache.
-  * Only auto‑deletes files it previously created.
-  * Interactive delete for “large” files.
+    * Creates missing files/directories.
+    * Tracks what it created in a cache.
+    * Only auto‑deletes files it previously created.
+    * Interactive delete for “large” files.
 * **Hooks**:
 
-  * Regular hooks around file create/delete.
-  * Stub hooks around content generation.
+    * Regular hooks around file create/delete.
+    * Stub hooks around content generation.
 * **Stubs**: programmatic content generators for files (e.g. React pages, controllers, etc.).
 * **Watch mode**: watch `.scaffold/` for changes and re‑run automatically.
-* **Scanner**: generate `structure.txt` (or per‑group `*.txt`) from an existing codebase.
-* **VS Code integration** (via a companion extension):
-
-  * Syntax highlighting for `.tss`, `.stx`, `structure.txt`, and `.scaffold/**/*.txt`.
-  * Inline diagnostics using the same parser as the CLI.
-  * “Go to file” from a structure line.
-  * Simple formatting and sorting commands.
+* **Scanner**: generate `*.tss`/`structure.txt` from an existing codebase.
+* **AST + formatter**: loose/strict parser with diagnostics, plus a smart formatter that can *fix* simple indentation mistakes.
+* **VS Code extension**: syntax highlighting, formatting, diagnostics, folding, hover info, “go to file”, and code actions.
 
 ---
 
@@ -73,7 +69,7 @@ This will create:
 If you want a different directory name:
 
 ```bash
-scaffold init --dir tools/scaffold
+scaffold init --dir tools/.scaffold
 ```
 
 > Use `--force` to overwrite existing config/structure files.
@@ -106,16 +102,13 @@ README.md
 
 **Rules:**
 
-* Indent with **2 spaces per level** (strict by default; configurable).
+* Indent with **2 spaces per level** by default (configurable via `indentStep`).
 * Directories **must** end with `/`.
 * Files **must not** end with `/`.
-* You **cannot indent under a file** (files cannot have children).
-* You can’t “skip” levels (no jumping from depth 0 to depth 2 in one go).
-* Lines starting with `#` or `//` (after indentation) are comments.
-* Inline comments are supported:
-
-  * `index.ts  # comment`
-  * `index.ts  // comment`
+* You **cannot indent under a file** (files cannot have children) – in strict mode this is an error, in loose mode you get a diagnostic.
+* You can’t “skip” levels (no jumping from depth 0 straight to depth 2 in one go).
+* Lines starting with `#` or `//` are treated as comments.
+* Inline comments are supported: `index.ts  # comment`, `index.ts  // comment`.
 
 #### Annotations
 
@@ -136,20 +129,23 @@ Supported inline annotations:
 
 These map onto the `StructureEntry` fields in TypeScript.
 
-> `:` is reserved for annotations (e.g. `@stub:page`). Paths themselves must **not** contain `:`.
-
 ---
 
-### 3. Configure groups (optional but recommended)
+## Config: groups, base, and indent
 
-In `.scaffold/config.ts` you can enable grouped mode:
+In `.scaffold/config.ts` you can enable grouped mode and control the base root + indent step:
 
 ```ts
 import type { ScaffoldConfig } from '@timeax/scaffold';
 
 const config: ScaffoldConfig = {
-  base: '.', // project root (optional, defaults to cwd)
+  // Project root (defaults to cwd if omitted)
+  base: '.',
+
+  // Indent step in spaces (must match your `.tss`/`structure.txt`)
+  indentStep: 2,
 
+  // Optional: grouped mode
   groups: [
     { name: 'app',      root: 'app',          structureFile: 'app.txt' },
     { name: 'frontend', root: 'resources/js', structureFile: 'frontend.txt' },
@@ -176,11 +172,11 @@ src/
     home.tsx
 ```
 
-> When `groups` is defined and non‑empty, single‑root `structure` / `structureFile` is ignored.
+> When `groups` is defined and non‑empty, single‑root `structure`/`structureFile` is ignored.
 
 ---
 
-### 4. Run scaffold
+## Running scaffold
 
 ```bash
 # single run
@@ -195,11 +191,11 @@ What happens:
 * Config is loaded from `.scaffold/config.*` (Prisma‑style resolution).
 * Structure(s) are resolved (grouped or single‑root).
 * Files/directories missing on disk are created.
-* New files are registered in `.scaffold-cache.json` (under project root by default).
+* New files are registered in a cache file (default: `.scaffold-cache.json` under project root).
 * Any previously created files that are no longer in the structure are candidates for deletion:
 
-  * Small files are deleted automatically.
-  * Large files (configurable threshold) trigger an interactive prompt.
+    * Small files are deleted automatically.
+    * Large files (configurable threshold) trigger an interactive prompt.
 
 ### Watch mode
 
@@ -209,8 +205,8 @@ scaffold --watch
 
 * Watches:
 
-  * `.scaffold/config.*`
-  * `.scaffold/*.txt`
+    * `.scaffold/config.*`
+    * `.scaffold/*.txt` / `.scaffold/*.tss` / `.scaffold/*.stx`
 * Debounces rapid edits.
 * Prevents overlapping runs.
 
@@ -251,11 +247,11 @@ Options:
 
 ### `scaffold scan`
 
-Generate `structure.txt`‑style definitions from an existing project.
+Generate `*.tss`/`structure.txt`‑style definitions from an existing project.
 
 Two modes:
 
-#### 1. Config‑aware mode (default if no `--root` / `--out` given)
+#### 1. Config‑aware mode (default if no `--root` / `--out`)
 
 ```bash
 scaffold scan
@@ -266,8 +262,8 @@ scaffold scan --from-config --groups app frontend
 * Loads `.scaffold/config.ts`.
 * For each `group` in config:
 
-  * Scans `group.root` on disk.
-  * Writes to `.scaffold/<group.structureFile || group.name + '.txt'>`.
+    * Scans `group.root` on disk.
+    * Writes to `.scaffold/<group.structureFile || group.name + '.txt'>`.
 * `--groups` filters which groups to scan.
 
 #### 2. Manual mode (single root)
@@ -298,12 +294,12 @@ What it does:
 * Loads `.scaffold/config.*`.
 * Determines which structure files are expected:
 
-  * **Grouped mode** (`config.groups` defined): each group gets `group.structureFile || `${group.name}.txt``.
-  * **Single-root mode** (no groups): uses `config.structureFile || 'structure.txt'`.
+    * **Grouped mode** (`config.groups` defined): each group gets `group.structureFile || \`${group.name}.txt``.
+    * **Single-root mode** (no groups): uses `config.structureFile || 'structure.txt'`.
 * For each expected structure file:
 
-  * If it **already exists** → it is left untouched.
-  * If it is **missing** → it is created with a small header comment.
+    * If it **already exists** → it is left untouched.
+    * If it is **missing** → it is created with a small header comment.
 
 Examples:
 
@@ -365,7 +361,100 @@ await writeScannedStructuresFromConfig(process.cwd(), {
 
 ---
 
-## Hooks & stubs (high‑level overview)
+## AST & Formatter
+
+`@timeax/scaffold` exposes an AST parser and formatter from a dedicated subpath:
+
+```ts
+import { parseStructureAst, formatStructureText } from '@timeax/scaffold/ast';
+```
+
+### `parseStructureAst(text, options)`
+
+Parses a structure file into a loose or strict AST with diagnostics:
+
+```ts
+const ast = parseStructureAst(text, {
+  indentStep: 2,     // must match your structure files
+  mode: 'loose',     // 'loose' | 'strict'
+});
+```
+
+Return shape (simplified):
+
+```ts
+interface StructureAstNode {
+  type: 'dir' | 'file';
+  name: string;
+  path?: string;         // normalized POSIX path (no trailing slash for files)
+  line?: number;         // 1-based source line
+  indentLevel?: number;  // 0,1,2,...
+  stub?: string;
+  include?: string[];
+  exclude?: string[];
+  children?: StructureAstNode[];
+}
+
+interface StructureDiagnostic {
+  code:
+    | 'indent-misaligned'
+    | 'indent-skip-level'
+    | 'child-of-file-loose'
+    | 'path-colon'
+    | 'unknown';
+  message: string;
+  line: number;      // 1-based
+  severity: 'info' | 'warning' | 'error';
+}
+
+interface StructureAst {
+  rootNodes: StructureAstNode[];
+  indentStep: number;
+  mode: 'loose' | 'strict';
+  diagnostics: StructureDiagnostic[];
+}
+```
+
+**Loose mode** tries to recover from small mistakes (over‑indent, under‑indent) and reports them as diagnostics instead of throwing.
+
+**Strict mode** is closer to the CLI parser and may reject invalid indentation entirely.
+
+Typical diagnostics:
+
+* `indent-misaligned` – indent is not a multiple of `indentStep`.
+* `indent-skip-level` – you jumped more than one level at once.
+* `child-of-file-loose` – a line is indented under a file.
+* `path-colon` – path token contains a colon (`:`), which is reserved for annotations.
+
+### `formatStructureText(text, options)`
+
+Smart formatter that:
+
+* Normalizes line endings and trailing whitespace.
+* Re‑indents entries to canonical multiples of `indentStep`.
+* Fixes common over‑indent/under‑indent issues in **loose mode**.
+* Preserves:
+
+    * Blank lines.
+    * Full‑line comments (`#`, `//`).
+    * Inline comments and annotations (keeps them attached to their entries).
+
+```ts
+const { text: formatted, ast, diagnostics } = formatStructureText(input, {
+  indentStep: 2,
+  mode: 'loose',      // 'loose' is recommended for editor integrations
+});
+```
+
+`formatStructureText` reuses the same AST model and diagnostics, so you can:
+
+* Run it in an editor (e.g. VS Code) for formatting.
+* Show the diagnostics in a side panel or gutter.
+* Still feed the formatted text back into the strict CLI parser later.
+
+---
+
+## Hooks & Stubs (high‑level overview)
 
 ### Regular hooks
 
@@ -406,6 +495,7 @@ Each receives a `HookContext` with fields like:
 * `absolutePath`
 * `isDirectory`
 * `stubName?`
+* `group?`
 
 ### Stubs
 
@@ -434,6 +524,7 @@ const config: ScaffoldConfig = {
             },
           },
         ],
+        postStub: [],
       },
     },
   },
@@ -453,110 +544,124 @@ Any file in `pages/` without an explicit stub inherits `@stub:page` from the par
 
 ---
 
-## Cache & safety
+## Cache & Safety
 
 * Cache file (default): `.scaffold-cache.json` under project root (configurable via `cacheFile`).
 * Every file created by scaffold is recorded with:
 
-  * project‑relative path
-  * created time
-  * size at creation
-  * stub name (if any)
-  * group metadata
+    * project‑relative path
+    * created time
+    * size at creation
+    * stub name (if any)
+    * group metadata
 * On each run, scaffold compares the **desired structure** vs. **cached entries**:
 
-  * If a cached file is no longer in the structure and still exists → deletion candidate.
-  * If its size exceeds `sizePromptThreshold` (configurable) and the CLI is interactive → prompt the user.
-  * If the user chooses “keep”, the file is left on disk and removed from the cache (user now owns it).
+    * If a cached file is no longer in the structure and still exists → deletion candidate.
+    * If its size exceeds `sizePromptThreshold` (configurable) and the CLI is interactive → prompt the user.
+    * If the user chooses “keep”, the file is left on disk and removed from the cache (user now owns it).
 
 This keeps scaffolding **idempotent** and avoids reckless deletes.
 
 ---
 
-## Roadmap / Ideas
+## VS Code Extension
 
-Some things this package is intentionally designed to grow into:
+There is a companion VS Code extension that makes editing scaffold files much nicer.
 
-* Richer annotations in `*.txt` (e.g. per‑entry hooks, metadata aliases).
-* Stub groups (one logical stub creating multiple files).
-* Built‑in templates for common stacks (Laravel + Inertia, Next.js, etc.).
-* Better diff/dry‑run UX (show what will change without touching disk).
-* Deeper VS Code integration:
+### Language & files
 
-  * Tree-aware sorting.
-  * Visual tree editor.
-  * Code actions / quick fixes for common mistakes.
+* Registers a `scaffold-structure` language.
+* Treats as scaffold structure files:
 
-PRs and ideas are welcome ✨
+    * `.tss`
+    * `.stx`
+    * `structure.txt`
+    * Any `.txt` inside `.scaffold/` (configurable in the extension’s `package.json`).
 
----
+### Syntax highlighting
+
+* Tree‑like syntax with clear highlighting for:
+
+    * Directories vs files.
+    * Annotations (`@stub:`, `@include:`, `@exclude:`).
+    * Comments and inline comments.
+
+### Formatting
 
-## VS Code extension
+* Command: **“Scaffold: Format structure”** (`timeax-scaffold.formatStructure`).
+* Uses `formatStructureText` from `@timeax/scaffold/ast`:
 
-There is an official VS Code companion extension for `@timeax/scaffold` that makes working with your structure files much nicer.
+    * Normalizes indentation to `indentStep`.
+    * Fixes simple over/under‑indents in loose mode.
+    * Preserves blank lines and comments.
 
-### Language support
+You can wire this as the default formatter for `scaffold-structure` files via your VS Code settings.
 
-The extension adds a custom language **Scaffold Structure** and:
+### Sorting
 
-* Highlights:
+* Command: **“Scaffold: Sort entries”** (`timeax-scaffold.sortEntries`).
+* Sorts non‑comment lines lexicographically while preserving comment/blank line positions.
 
-  * Directories (lines ending with `/`)
-  * Files
-  * Inline annotations like `@stub:name`, `@include:pattern`, `@exclude:pattern`
-  * Comments using `#` or `//` (full-line and inline)
-* Treats the following files as scaffold structures:
+### Diagnostics
 
-  * `*.tss`
-  * `*.stx`
-  * `structure.txt`
-  * Any `.txt` file inside your `.scaffold/` directory
+* Live diagnostics (squiggles) using `parseStructureAst`:
 
-The syntax rules match the CLI parser:
+    * `indent-misaligned`, `indent-skip-level`, `child-of-file-loose`, `path-colon`, etc.
+* Diagnostics update on open and on change.
 
-* Indent is in fixed steps (configurable via `indentStep`).
-* Only directories can have children.
-* `:` is reserved for annotations and not allowed inside path names.
+### Folding
 
-### Editor commands
+* Folding regions for directories based on AST:
 
-The extension contributes several commands (available via the Command Palette and context menus when editing a scaffold structure file):
+    * Collapse an entire subtree under a dir.
 
-* **Scaffold: Go to file**
+### Hover
 
-  * Reads the path on the current line and opens the corresponding file in your project.
-  * Respects `.scaffold/config.*`:
+* Hovering an entry shows:
 
-    * Uses `base`/`root` to resolve paths.
-    * If the current structure file belongs to a `group`, it resolves relative to that group’s `root`.
-  * If the file doesn’t exist, it can prompt to create it and open it immediately.
+    * Kind (dir/file).
+    * Effective `path`.
+    * Stub / include / exclude.
+    * Resolved absolute path based on `base` + group root.
 
-* **Scaffold: Format structure file**
+### “Go to file”
 
-  * Normalizes line endings and trims trailing whitespace.
-  * Designed to be safe even on partially-invalid files.
-  * Future versions may use the full AST from `@timeax/scaffold` to enforce indentation and ordering.
+* Command: **“Scaffold: Go to file”** (`timeax-scaffold.openTargetFile`).
+* On a file line:
 
-* **Scaffold: Sort entries**
+    * Resolves the project base (from `.scaffold/config.*`, `base`, and group `root`).
+    * Opens the target file if it exists.
+    * If it doesn’t exist, you can create it on the spot.
 
-  * Naive helper that sorts non-comment lines lexicographically while keeping comment/blank lines in place.
-  * Useful for quick cleanups of small structure files.
+### Code actions
 
-* **Scaffold: Open config**
+Source actions exposed in the light‑bulb menu for structure files:
 
-  * Opens `.scaffold/config.*` for the current workspace (searching common extensions like `config.ts`, `config.mts`, etc.).
+* **“Scaffold: Ensure structure files exist (scaffold structures)”**
 
-* **Scaffold: Open .scaffold folder**
+    * Runs `npx scaffold structures` in a workspace terminal.
+* **“Scaffold: Apply structure to project (scaffold)”**
 
-  * Reveals the `.scaffold/` directory in the VS Code Explorer.
+    * Runs `npx scaffold` in a workspace terminal.
 
-### Live validation (diagnostics)
+### Status bar integration
 
-Whenever you open or edit a scaffold structure file:
+* Status bar item (left side) shows current scaffold context:
 
-* The extension calls `parseStructureText` from `@timeax/scaffold` under the hood.
-* If parsing fails, the error message (e.g. invalid indentation, children under a file, bad path, etc.) is shown as an editor diagnostic (squiggly underline) on the relevant line.
+    * `Scaffold: frontend (resources/js)` when editing `.scaffold/frontend.txt`.
+    * `Scaffold: single root` when in single‑root mode.
+* Tooltip shows the resolved base root path.
 
-This means your editor and the CLI always agree on what is valid, since they share the same parser and rules.
+---
+
+## Roadmap / Ideas
 
-> The extension is optional, but highly recommended if you edit `*.tss` / `*.stx` or `structure.txt` files frequently.
+Some things this package is intentionally designed to grow into:
+
+* Richer annotations in `*.tss` (e.g. per‑entry hooks, metadata aliases).
+* Stub groups (one logical stub creating multiple files at once).
+* Built‑in templates for common stacks (Laravel + Inertia, Next.js, etc.).
+* Better diff/dry‑run UX (show what will change without touching disk).
+* Deeper editor integrations (per‑group commands, quick‑fixes for diagnostics, etc.).
+
+PRs and ideas are welcome ✨