Timeax Scaffold – VS Code Extension

Rich editor support for @timeax/scaffold structure files.

This extension adds:

• Syntax highlighting for scaffold structure trees (.tss, .stx, structure.txt).
• Formatting commands powered by the AST formatter from @timeax/scaffold.
• Sorting helpers that keep comments and blank lines in place.
• Diagnostics for invalid / suspicious structure definitions.
• “Go to file” navigation: jump from a structure entry to the real file.
• Helpers to open your .scaffold config and folder directly from VS Code.
• Support for the default .scaffold/ layout used by @timeax/scaffold.

Installation

Until this is published to the Marketplace, you can use it as a local / dev extension.

1. Clone or download the extension repo:

   git clone https://github.com/timeax/timeax-scaffold-extension
   cd timeax-scaffold-extension
   

2. Install dependencies and build:

   npm install
   npm run compile
   

3. Press F5 in VS Code to launch an Extension Development Host.

4. Open a project that uses @timeax/scaffold and the .scaffold/ folder.

When published to the Marketplace:

ext install timeax.timeax-scaffold-extension

(Exact identifier may change.)

File associations

The extension registers a custom language scaffold-structure for structure files. By default, it treats these as scaffold files:

• Files ending with **.tss**
• Files ending with **.stx**
• Files named structure.txt

It also associates files in the .scaffold/ directory so you usually don’t need extra config.

If you want to associate additional patterns manually:

// settings.json
"files.associations": {
  "*.tss": "scaffold-structure",
  "*.stx": "scaffold-structure",
  "structure.txt": "scaffold-structure"
}

Language features

Syntax highlighting

The extension provides TextMate-based highlighting for:

• Path entries (directories ending in /, files without /).

• Indentation levels (2 spaces per level by default).

• Inline annotations:

  • @stub:name
  • @include:pattern,pattern2
  • @exclude:pattern,pattern2

• Comments:

  • Full-line: # ... and // ...
  • Inline comments after entries: index.ts # comment, index.ts // comment

This mirrors the rules used by @timeax/scaffold’s parser.

Formatting

The formatter uses the AST parser from @timeax/scaffold (loose/strict modes) to make the file tidy but still forgiving.

• Normalizes indentation according to indentStep (from config).
• Preserves blank lines and full-line comments.
• Keeps inline comments attached to their entries.
• Can softly fix certain indentation mistakes in loose mode.

Commands

• Timeax Scaffold: Format structure file Command ID: timeax-scaffold.formatStructure

This command reformats the entire current structure file.

The extension delegates to @timeax/scaffold’s formatter API (formatStructureText) so the behaviour matches your CLI runs (scaffold --format).

VS Code format-on-save

You can enable format-on-save for scaffold structure files:

// settings.json
"[scaffold-structure]": {
  "editor.formatOnSave": true
}

The extension registers a document formatter for the scaffold-structure language, so any Format Document call (or format-on-save) will use the same logic as the dedicated command.

Sorting entries

Sometimes you just want to alphabetize entries while preserving comments and spacing.

• Timeax Scaffold: Sort entries Command ID: timeax-scaffold.sortEntries

Behaviour:

• Non-comment lines (actual entries) are sorted lexicographically.
• Comment-only and blank lines keep their positions.
• Inline comments stay attached to their original entries.

This is useful for keeping large sections readable without losing contextual comments.

Diagnostics

The extension surfaces parser errors and structural issues as VS Code diagnostics (squiggles + Problems panel).

It uses parseStructureText from @timeax/scaffold and maps common errors to line ranges, for example:

• Invalid indentation steps (not a multiple of indentStep).
• Skipped indentation levels (jumping from depth 0 directly to depth 2).
• Indenting under a file (files can’t have children).
• Paths with forbidden tokens (e.g. : reserved for annotations).

Diagnostics are updated when:

• A scaffold structure document is opened.
• The document changes.
• Formatting / sorting commands run.

Go to file

Quickly navigate from a structure entry to the corresponding file in your project.

• Timeax Scaffold: Open target file Command ID: timeax-scaffold.openTargetFile

Behaviour:

1. Looks at the current line under the cursor.

2. Extracts the path token, ignoring annotations and comments.

3. Resolves it relative to the appropriate base directory:

   • If your .scaffold/config.* defines groups, it matches the current structure file to a group and uses that group’s root as base.
   • Otherwise, it falls back to the project’s base (config.base or root).

4. Attempts to open the file:

   • If it exists and is a file → opens in a new editor tab.
   • If it’s a directory → shows an informational message (directory navigation is not yet implemented).
   • If it doesn’t exist → offers to create the file and open it.

This mirrors the way the CLI resolves paths when applying structure groups.

Scaffold helpers

To avoid hunting for config files and folders, the extension exposes a few convenience commands:

• Timeax Scaffold: Open config ID: timeax-scaffold.openConfig Opens the first matching config.* inside .scaffold/ (supports ts/js/mts/cts/mjs/cjs).

• Timeax Scaffold: Reveal .scaffold folder ID: timeax-scaffold.openScaffoldFolder Focuses the .scaffold/ directory in the Explorer panel.

These commands are workspace-aware and use the current workspace folder as base.

Folding (optional / planned)

The extension can provide folding regions such that:

• Directories and their descendants can be folded as a block.
• Comment blocks at the top of the file can be folded as a header.

Implementation uses the same AST as the formatter, so folds follow real structure (not just indentation heuristics).

If folding is not yet active in your build, it’s planned to be wired through a FoldingRangeProvider on the scaffold-structure language.

Integration with @timeax/scaffold

This extension is intentionally thin: almost all of the important logic lives in the core package:

• Parsing / AST / diagnostics → @timeax/scaffold/ast
• Structure parsing → parseStructureText
• Formatting → formatStructureText (loose/strict modes)
• Config resolution → loadScaffoldConfig (Prisma-style discovery)

This means:

• Your CLI (scaffold), your programmatic API (runOnce), and the VS Code extension all agree on what’s valid and how formatting behaves.
• Upgrading @timeax/scaffold gives you better parsing/formatting/diagnostics in the editor without changing editor-specific logic.

Commands summary

All commands are namespaced under Timeax Scaffold in the Command Palette:

• timeax-scaffold.formatStructure – Format current structure file.
• timeax-scaffold.sortEntries – Sort entries while preserving comments.
• timeax-scaffold.openTargetFile – Open the file referenced by the current line.
• timeax-scaffold.openConfig – Open .scaffold/config.*.
• timeax-scaffold.openScaffoldFolder – Reveal the .scaffold/ directory.

Recommended settings

// settings.json
{
  // Associate additional patterns if needed
  "files.associations": {
    "*.tss": "scaffold-structure",
    "*.stx": "scaffold-structure",
    "structure.txt": "scaffold-structure"
  },

  // Format scaffold structure files on save
  "[scaffold-structure]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "timeax.timeax-scaffold-extension"
  }
}

Development

Basic dev loop:

npm install
npm run watch  # or: npm run compile

Then press F5 in VS Code to launch an Extension Development Host.

Tests (Mocha via @vscode/test-electron):

npm test

This runs the extension’s integration tests which:

• Activate the extension.
• Assert that core commands are registered.
• Exercise formatting/sorting behaviour on in-memory documents.
• Verify diagnostics are produced for obviously invalid structures.

Feedback & contributions

This extension is tightly coupled to the evolution of @timeax/scaffold. Ideas and PRs are welcome, especially around:

• Better inline diagnostics (e.g. per-annotation warnings).
• Richer folding behaviours.
• Code actions (e.g. “Fix indentation”, “Convert to group config”).
• Multi-root workspace support and status bar integration.

Enjoy a Prisma-style, text-driven scaffold workflow with first-class editor support ✨