@timeax/scaffold 0.0.2 → 0.0.4

package/src/core/structure-txt.ts

@@ -1,15 +1,38 @@
 // src/core/structure-txt.ts
 
-import type { StructureEntry, DirEntry, FileEntry } from '../schema';
-import { toPosixPath } from '../util/fs-utils';
+import type {StructureEntry, DirEntry, FileEntry} from '../schema';
+import {toPosixPath} from '../util/fs-utils';
+import {mapThrough} from "../ast";
 
 interface ParsedLine {
-   lineNo: number;
-   indentSpaces: number;
-   rawPath: string;
-   stub?: string;
-   include?: string[];
-   exclude?: string[];
+    lineNo: number;
+    indentSpaces: number;
+    rawPath: string;
+    stub?: string;
+    include?: string[];
+    exclude?: string[];
+}
+
+/**
+ * Strip inline comments from a content segment.
+ *
+ * Supports:
+ *   - "index.ts  # comment"
+ *   - "index.ts  // comment"
+ *
+ * Rules:
+ * - We assume leading indentation has already been removed.
+ * - Leading '#' or '//' (full-line comments) are handled BEFORE this function.
+ * - A comment starts at the first '#' or '//' that is
+ *   preceded by whitespace (space or tab).
+ */
+function stripInlineComment(content: string): string {
+    const cutIndex = mapThrough(content);
+    if (cutIndex === -1) {
+        return content.trimEnd();
+    }
+
+    return content.slice(0, cutIndex).trimEnd();
 }
 
 /**
@@ -20,184 +43,208 @@ interface ParsedLine {
  * - @exclude:pattern,pattern2
  */
 function parseLine(line: string, lineNo: number): ParsedLine | null {
-   const match = line.match(/^(\s*)(.+)$/);
-   if (!match) return null;
-
-   const indentSpaces = match[1].length;
-   const rest = match[2].trim();
-   if (!rest || rest.startsWith('#')) return null;
-
-   const parts = rest.split(/\s+/);
-   const pathToken = parts[0];
-
-   let stub: string | undefined;
-   const include: string[] = [];
-   const exclude: string[] = [];
-
-   for (const token of parts.slice(1)) {
-      if (token.startsWith('@stub:')) {
-         stub = token.slice('@stub:'.length);
-      } else if (token.startsWith('@include:')) {
-         const val = token.slice('@include:'.length);
-         if (val) {
-            include.push(
-               ...val
-                  .split(',')
-                  .map((s) => s.trim())
-                  .filter(Boolean),
-            );
-         }
-      } else if (token.startsWith('@exclude:')) {
-         const val = token.slice('@exclude:'.length);
-         if (val) {
-            exclude.push(
-               ...val
-                  .split(',')
-                  .map((s) => s.trim())
-                  .filter(Boolean),
-            );
-         }
-      }
-   }
-
-   return {
-      lineNo,
-      indentSpaces,
-      rawPath: pathToken,
-      stub,
-      include: include.length ? include : undefined,
-      exclude: exclude.length ? exclude : undefined,
-   };
+    const match = line.match(/^(\s*)(.*)$/);
+    if (!match) return null;
+
+    const indentSpaces = match[1].length;
+    let rest = match[2];
+
+    // If line (after indent) is empty, skip
+    if (!rest.trim()) return null;
+
+    // Full-line comments after indent
+    const trimmedRest = rest.trimStart();
+    if (trimmedRest.startsWith('#') || trimmedRest.startsWith('//')) {
+        return null;
+    }
+
+    // Strip inline comments (# or //) before parsing tokens
+    const stripped = stripInlineComment(rest);
+    const trimmed = stripped.trim();
+    if (!trimmed) return null;
+
+    const parts = trimmed.split(/\s+/);
+    if (!parts.length) return null;
+
+    const pathToken = parts[0];
+
+    // 🚫 Reserve ":" for annotations only – paths may not contain it.
+    if (pathToken.includes(':')) {
+        throw new Error(
+            `structure.txt: ":" is reserved for annotations (@stub:, @include:, etc). ` +
+            `Invalid path "${pathToken}" on line ${lineNo}.`,
+        );
+    }
+
+    let stub: string | undefined;
+    const include: string[] = [];
+    const exclude: string[] = [];
+
+    for (const token of parts.slice(1)) {
+        if (token.startsWith('@stub:')) {
+            stub = token.slice('@stub:'.length);
+        } else if (token.startsWith('@include:')) {
+            const val = token.slice('@include:'.length);
+            if (val) {
+                include.push(
+                    ...val
+                        .split(',')
+                        .map((s) => s.trim())
+                        .filter(Boolean),
+                );
+            }
+        } else if (token.startsWith('@exclude:')) {
+            const val = token.slice('@exclude:'.length);
+            if (val) {
+                exclude.push(
+                    ...val
+                        .split(',')
+                        .map((s) => s.trim())
+                        .filter(Boolean),
+                );
+            }
+        }
+    }
+
+    return {
+        lineNo,
+        indentSpaces,
+        rawPath: pathToken,
+        stub,
+        include: include.length ? include : undefined,
+        exclude: exclude.length ? exclude : undefined,
+    };
 }
 
 /**
  * Convert a structure.txt content into a nested StructureEntry[].
  *
  * Rules:
- * - Indentation is **2 spaces per level** (strict).
- * - Indent must be a multiple of 2.
+ * - Indentation is **indentStep** spaces per level (default: 2).
+ * - Indent must be a multiple of indentStep.
  * - You cannot "skip" levels (no jumping from level 0 to 2 directly).
  * - **Only directories can have children**:
  *   - If you indent under a file, an error is thrown.
  * - Folders must end with "/" in the txt; paths are normalized to POSIX.
  */
-export function parseStructureText(text: string): StructureEntry[] {
-   const lines = text.split(/\r?\n/);
-   const parsed: ParsedLine[] = [];
-
-   for (let i = 0; i < lines.length; i++) {
-      const lineNo = i + 1;
-      const p = parseLine(lines[i], lineNo);
-      if (p) parsed.push(p);
-   }
-
-   const rootEntries: StructureEntry[] = [];
-
-   type StackItem = {
-      level: number;
-      entry: DirEntry | FileEntry;
-      isDir: boolean;
-   };
-
-   const stack: StackItem[] = [];
-   const INDENT_STEP = 2;
-
-   for (const p of parsed) {
-      const { indentSpaces, lineNo } = p;
-
-      if (indentSpaces % INDENT_STEP !== 0) {
-         throw new Error(
-            `structure.txt: Invalid indent on line ${lineNo}. ` +
-            `Indent must be multiples of ${INDENT_STEP} spaces.`,
-         );
-      }
-
-      const level = indentSpaces / INDENT_STEP;
-
-      // Determine parent level and enforce no skipping
-      if (level > stack.length) {
-         // e.g. current stack depth 1, but line level=2+ is invalid
-         if (level !== stack.length + 1) {
-            throw new Error(
-               `structure.txt: Invalid indentation on line ${lineNo}. ` +
-               `You cannot jump more than one level at a time. ` +
-               `Previous depth: ${stack.length}, this line depth: ${level}.`,
-            );
-         }
-      }
+export function parseStructureText(
+    text: string,
+    indentStep = 2,
+): StructureEntry[] {
+    const lines = text.split(/\r?\n/);
+    const parsed: ParsedLine[] = [];
 
-      // If this line is indented (level > 0), parent must exist and must be dir
-      if (level > 0) {
-         const parent = stack[level - 1]; // parent level is (level - 1)
-         if (!parent) {
-            throw new Error(
-               `structure.txt: Indented entry without a parent on line ${lineNo}.`,
-            );
-         }
-         if (!parent.isDir) {
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const p = parseLine(lines[i], lineNo);
+        if (p) parsed.push(p);
+    }
+
+    const rootEntries: StructureEntry[] = [];
+
+    type StackItem = {
+        level: number;
+        entry: DirEntry | FileEntry;
+        isDir: boolean;
+    };
+
+    const stack: StackItem[] = [];
+
+    for (const p of parsed) {
+        const {indentSpaces, lineNo} = p;
+
+        if (indentSpaces % indentStep !== 0) {
             throw new Error(
-               `structure.txt: Cannot indent under a file on line ${lineNo}. ` +
-               `Files cannot have children. Parent: "${parent.entry.path}".`,
+                `structure.txt: Invalid indent on line ${lineNo}. ` +
+                `Indent must be multiples of ${indentStep} spaces.`,
             );
-         }
-      }
-
-      const isDir = p.rawPath.endsWith('/');
-      const clean = p.rawPath.replace(/\/$/, '');
-      const basePath = toPosixPath(clean);
-
-      // Determine parent based on level
-      // Pop stack until we are at the correct depth
-      while (stack.length > level) {
-         stack.pop();
-      }
-
-      const parent = stack[stack.length - 1]?.entry as DirEntry | undefined;
-      const parentPath = parent ? parent.path.replace(/\/$/, '') : '';
-
-      const fullPath = parentPath
-         ? `${parentPath}/${basePath}${isDir ? '/' : ''}`
-         : `${basePath}${isDir ? '/' : ''}`;
-
-      if (isDir) {
-         const dirEntry: DirEntry = {
-            type: 'dir',
-            path: fullPath,
-            children: [],
-            ...(p.stub ? { stub: p.stub } : {}),
-            ...(p.include ? { include: p.include } : {}),
-            ...(p.exclude ? { exclude: p.exclude } : {}),
-         };
-
-         if (parent && parent.type === 'dir') {
-            parent.children = parent.children ?? [];
-            parent.children.push(dirEntry);
-         } else if (!parent) {
-            rootEntries.push(dirEntry);
-         }
-
-         stack.push({ level, entry: dirEntry, isDir: true });
-      } else {
-         const fileEntry: FileEntry = {
-            type: 'file',
-            path: fullPath,
-            ...(p.stub ? { stub: p.stub } : {}),
-            ...(p.include ? { include: p.include } : {}),
-            ...(p.exclude ? { exclude: p.exclude } : {}),
-         };
-
-         if (parent && parent.type === 'dir') {
-            parent.children = parent.children ?? [];
-            parent.children.push(fileEntry);
-         } else if (!parent) {
-            rootEntries.push(fileEntry);
-         }
-
-         // files are not added to the stack; they cannot have children
-         stack.push({ level, entry: fileEntry, isDir: false });
-         // but next lines at same or lower level will pop correctly
-      }
-   }
-
-   return rootEntries;
+        }
+
+        const level = indentSpaces / indentStep;
+
+        // Determine parent level and enforce no skipping
+        if (level > stack.length) {
+            // e.g. current stack depth 1, but line level=3 is invalid
+            if (level !== stack.length + 1) {
+                throw new Error(
+                    `structure.txt: Invalid indentation on line ${lineNo}. ` +
+                    `You cannot jump more than one level at a time. ` +
+                    `Previous depth: ${stack.length}, this line depth: ${level}.`,
+                );
+            }
+        }
+
+        // If this line is indented (level > 0), parent must exist and must be dir
+        if (level > 0) {
+            const parent = stack[level - 1]; // parent level is (level - 1)
+            if (!parent) {
+                throw new Error(
+                    `structure.txt: Indented entry without a parent on line ${lineNo}.`,
+                );
+            }
+            if (!parent.isDir) {
+                throw new Error(
+                    `structure.txt: Cannot indent under a file on line ${lineNo}. ` +
+                    `Files cannot have children. Parent: "${parent.entry.path}".`,
+                );
+            }
+        }
+
+        const isDir = p.rawPath.endsWith('/');
+        const clean = p.rawPath.replace(/\/$/, '');
+        const basePath = toPosixPath(clean);
+
+        // Pop stack until we are at the correct depth
+        while (stack.length > level) {
+            stack.pop();
+        }
+
+        const parent = stack[stack.length - 1]?.entry as DirEntry | undefined;
+        const parentPath = parent ? parent.path.replace(/\/$/, '') : '';
+
+        const fullPath = parentPath
+            ? `${parentPath}/${basePath}${isDir ? '/' : ''}`
+            : `${basePath}${isDir ? '/' : ''}`;
+
+        if (isDir) {
+            const dirEntry: DirEntry = {
+                type: 'dir',
+                path: fullPath,
+                children: [],
+                ...(p.stub ? {stub: p.stub} : {}),
+                ...(p.include ? {include: p.include} : {}),
+                ...(p.exclude ? {exclude: p.exclude} : {}),
+            };
+
+            if (parent && parent.type === 'dir') {
+                parent.children = parent.children ?? [];
+                parent.children.push(dirEntry);
+            } else if (!parent) {
+                rootEntries.push(dirEntry);
+            }
+
+            stack.push({level, entry: dirEntry, isDir: true});
+        } else {
+            const fileEntry: FileEntry = {
+                type: 'file',
+                path: fullPath,
+                ...(p.stub ? {stub: p.stub} : {}),
+                ...(p.include ? {include: p.include} : {}),
+                ...(p.exclude ? {exclude: p.exclude} : {}),
+            };
+
+            if (parent && parent.type === 'dir') {
+                parent.children = parent.children ?? [];
+                parent.children.push(fileEntry);
+            } else if (!parent) {
+                rootEntries.push(fileEntry);
+            }
+
+            // We still push files into the stack at this level so that
+            // bad indentation under them can be detected and rejected.
+            stack.push({level, entry: fileEntry, isDir: false});
+        }
+    }
+
+    return rootEntries;
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 // src/index.ts
-
 export * from './schema';
 export * from './core/runner';
-export * from './core/scan-structure';
+export * from './core/config-loader';
+export * from './core/scan-structure';
+export * from './core/structure-txt';

package/src/schema/config.ts

@@ -143,9 +143,18 @@ export interface ScaffoldConfig {
     * runner / CLI.
     */
    watch?: boolean;
-}
 
 
+   /**
+    * Number of spaces per indent level in structure files.
+    * Default: 2.
+    *
+    * Examples:
+    * - 2  → "··entry"
+    * - 4  → "····entry"
+    */
+   indentStep?: number;
+}
 /**
  * Options when scanning an existing directory into a structure.txt tree.
  */

package/src/schema/index.ts

@@ -1,4 +1,5 @@
 // src/schema/index.ts
+export const SCAFFOLD_ROOT_DIR = '.scaffold';
 export * from './structure';
 export * from './hooks';
 export * from './config';

package/test/format-roundtrip.spec.ts

@@ -0,0 +1,20 @@
+// test/format-roundtrip.spec.ts
+import {describe, it, expect} from 'vitest';
+import {formatStructureText} from '../src/ast';
+
+describe('formatStructureText roundtrip', () => {
+    it('is idempotent for a valid tree', () => {
+        const input = [
+            'src/',
+            '  index.ts # entry',
+            '',
+            '  schema/',
+            '    index.ts',
+        ].join('\n');
+
+        const first = formatStructureText(input, {indentStep: 2});
+        const second = formatStructureText(first.text, {indentStep: 2});
+
+        expect(second.text).toBe(first.text);
+    });
+});

package/test/format.spec.ts

@@ -0,0 +1,104 @@
+// test/format.spec.ts
+
+import {describe, it, expect} from 'vitest';
+import {formatStructureText} from '../src/ast';
+
+describe('formatStructureText', () => {
+    it('formats a simple tree with canonical indentation', () => {
+        const input = [
+            'src/',
+            '    index.ts',
+            '',
+            '    schema/',
+            '        index.ts',
+            '        field.ts',
+        ].join('\n');
+
+        const {text} = formatStructureText(input, {indentStep: 2});
+
+        expect(text).toBe(
+            [
+                'src/',
+                '  index.ts',
+                '',
+                '  schema/',
+                '    index.ts',
+                '    field.ts',
+            ].join('\n'),
+        );
+    });
+
+    it('preserves blank lines and comments', () => {
+        const input = [
+            '# root comment',
+            'src/   # src dir',
+            '',
+            '    index.ts  // main entry',
+            '',
+            '    schema/  # schema section',
+            '        index.ts',
+        ].join('\n');
+
+        const {text} = formatStructureText(input, {indentStep: 2});
+
+        expect(text).toBe(
+            [
+                '# root comment',
+                'src/ # src dir',
+                '',
+                '  index.ts // main entry',
+                '',
+                '  schema/ # schema section',
+                '    index.ts',
+            ].join('\n'),
+        );
+    });
+
+    it('fixes over-indented children in loose mode', () => {
+        const input = [
+            'src/',
+            '        schema/', // 8 spaces (depth 4 if step=2), but no intermediate levels
+            '            index.ts',
+        ].join('\n');
+
+        const {text, ast} = formatStructureText(input, {
+            indentStep: 2,
+            mode: 'loose',
+        });
+
+        // In loose mode, this should become src/ (depth 0) and schema/ (depth 1)
+        expect(text).toBe(
+            [
+                'src/',
+                '  schema/',
+                '    index.ts',
+            ].join('\n'),
+        );
+
+        // And there should be at least one warning about the indent jump.
+        const hasIndentWarning = ast.diagnostics.some(
+            (d) => d.code && d.code.includes('indent-skip-level'),
+        );
+        expect(hasIndentWarning).toBe(true);
+    });
+
+    it('keeps inline comments attached to their entries', () => {
+        const input = [
+            'src/',
+            '  index.ts    # comment one',
+            '  schema/   @stub:schema   // comment two',
+            '    index.ts',
+        ].join('\n');
+
+        const {text} = formatStructureText(input, {indentStep: 2});
+
+        expect(text).toBe(
+            [
+                'src/',
+                '  index.ts # comment one',
+                '  schema/ @stub:schema // comment two',
+                '    index.ts',
+            ].join('\n'),
+        );
+    });
+});

package/test/parser-diagnostics.spec.ts

@@ -0,0 +1,86 @@
+// test/parser-diagnostics.spec.ts
+
+import { describe, it, expect } from 'vitest';
+import { parseStructureAst } from '../src/ast';
+
+describe('parseStructureAst diagnostics', () => {
+    it('reports indent-skip-level when jumping multiple levels', () => {
+        const text = [
+            'src/',
+            '        index.ts', // 8 spaces, with indentStep=2 this is a big jump
+        ].join('\n');
+
+        const ast = parseStructureAst(text, { indentStep: 2, mode: 'loose' });
+
+        const codes = ast.diagnostics.map((d) => d.code);
+        expect(codes).toContain('indent-skip-level');
+    });
+
+    it('reports indent-misaligned when decreasing indent by a non-multiple', () => {
+        // Here the *third* line has LESS indent than the second, and not a clean multiple.
+        // 0 spaces -> 4 spaces -> 3 spaces
+        const text = [
+            'src/',
+            '    schema/',
+            '   index.ts', // 3 spaces: decrease from 4 by 1 → not multiple of 2
+        ].join('\n');
+
+        const ast = parseStructureAst(text, { indentStep: 2, mode: 'loose' });
+
+        const diag = ast.diagnostics.find((d) => d.code === 'indent-misaligned');
+        expect(diag).toBeDefined();
+        expect(diag?.line).toBe(3);
+    });
+
+    it('reports path-colon when a path token contains ":"', () => {
+        const text = [
+            'src/',
+            '  api:v1/', // invalid: colon in path token
+        ].join('\n');
+
+        const ast = parseStructureAst(text, { indentStep: 2, mode: 'loose' });
+
+        const diag = ast.diagnostics.find((d) => d.code === 'path-colon');
+        expect(diag).toBeDefined();
+        expect(diag?.line).toBe(2);
+    });
+
+    it('reports child-of-file-loose when an entry is indented under a file', () => {
+        const text = [
+            'index.ts',
+            '  child.ts',
+        ].join('\n');
+
+        const ast = parseStructureAst(text, { indentStep: 2, mode: 'loose' });
+
+        const diag = ast.diagnostics.find(
+            (d) => d.code === 'child-of-file-loose' || d.code === 'child-of-file',
+        );
+
+        expect(diag).toBeDefined();
+        expect(diag?.line).toBe(2);
+    });
+
+    it('does NOT treat comments or blanks as entries (no diagnostics for them)', () => {
+        const text = [
+            '# comment',
+            '',
+            '   // another comment',
+            'src/',
+        ].join('\n');
+
+        const ast = parseStructureAst(text, { indentStep: 2, mode: 'loose' });
+
+        // Should parse fine, with no indent-related diagnostics on comment lines
+        const indentDiags = ast.diagnostics.filter(
+            (d) =>
+                d.code === 'indent-skip-level' ||
+                d.code === 'indent-misaligned' ||
+                d.code === 'indent-tabs',
+        );
+
+        expect(indentDiags.length).toBe(0);
+        expect(ast.rootNodes.length).toBe(1);
+        expect(ast.rootNodes[0].name).toBe('src/');
+    });
+});