@timeax/scaffold 0.0.3 → 0.0.5

package/src/core/init-scaffold.ts

@@ -2,48 +2,50 @@
 
 import fs from 'fs';
 import path from 'path';
-import { ensureDirSync } from '../util/fs-utils';
-import { defaultLogger } from '../util/logger';
-import { SCAFFOLD_ROOT_DIR } from '../schema';
+import {ensureDirSync} from '../util/fs-utils';
+import {defaultLogger} from '../util/logger';
+import {SCAFFOLD_ROOT_DIR} from '../schema';
 
 const logger = defaultLogger.child('[init]');
 
 export interface InitScaffoldOptions {
-   /**
-    * Path to the scaffold directory (relative to cwd).
-    * Default: "scaffold"
-    */
-   scaffoldDir?: string;
-
-   /**
-    * Overwrite existing config/structure files if they already exist.
-    */
-   force?: boolean;
-
-   /**
-    * Name of the config file inside the scaffold directory.
-    * Default: "config.ts"
-    */
-   configFileName?: string;
-
-   /**
-    * Name of the default structure file inside the scaffold directory
-    * for single-root mode.
-    * Default: "structure.txt"
-    */
-   structureFileName?: string;
+    /**
+     * Path to the scaffold directory (relative to cwd).
+     * Default: ".scaffold"
+     */
+    scaffoldDir?: string;
+
+    /**
+     * Overwrite existing config/structure files if they already exist.
+     */
+    force?: boolean;
+
+    /**
+     * Name of the config file inside the scaffold directory.
+     * Default: "config.ts"
+     */
+    configFileName?: string;
+
+    /**
+     * Name of the default structure file inside the scaffold directory
+     * for single-root mode.
+     * Default: "structure.txt"
+     */
+    structureFileName?: string;
 }
 
-// src/core/init-scaffold.ts
+// ---------------------------------------------------------------------------
+// Default config + structure templates
+// ---------------------------------------------------------------------------
 
 const DEFAULT_CONFIG_TS = `import type { ScaffoldConfig } from '@timeax/scaffold';
 
 const config: ScaffoldConfig = {
-  // Root for resolving the scaffold/ folder & this config file.
+  // Root for resolving the .scaffold folder & this config file.
   // By default, this is the directory where you run \`scaffold\`.
   // Example:
-  //   root: '.',          // scaffold/ at <cwd>/scaffold
-  //   root: 'tools',      // scaffold/ at <cwd>/tools/scaffold
+  //   root: '.',          // .scaffold at <cwd>/.scaffold
+  //   root: 'tools',      // .scaffold at <cwd>/tools/.scaffold
   // root: '.',
 
   // Base directory where structures are applied and files/folders are created.
@@ -53,13 +55,42 @@ const config: ScaffoldConfig = {
   //   base: 'src',        // apply to <root>/src
   //   base: '..',         // apply to parent of <root>
   // base: '.',
-  
+
   // Number of spaces per indent level in structure files (default: 2).
+  // This also informs the formatter when indenting entries.
   // indentStep: 2,
-  
+
   // Cache file path, relative to base.
   // cacheFile: '.scaffold-cache.json',
 
+  // Formatting options for structure files.
+  // These are used by:
+  //  - \`scaffold --format\` (forces formatting before apply)
+  //  - \`scaffold --watch\` when \`formatOnWatch\` is true
+  //
+  // format: {
+  //   // Enable config-driven formatting in general.
+  //   // \`scaffold --format\` always forces formatting even if this is false.
+  //   enabled: true,
+  //
+  //   // Override indent step specifically for formatting (falls back to
+  //   // top-level \`indentStep\` if omitted).
+  //   indentStep: 2,
+  //
+  //   // AST mode:
+  //   //  - 'loose' (default): tries to repair mild indentation issues.
+  //   //  - 'strict': mostly cosmetic changes (trims trailing whitespace, etc.).
+  //   mode: 'loose',
+  //
+  //   // Sort non-comment entries lexicographically within their parent block.
+  //   // Comments and blank lines keep their relative positions.
+  //   sortEntries: true,
+  //
+  //   // When running \`scaffold --watch\`, format structure files on each
+  //   // detected change before applying scaffold.
+  //   formatOnWatch: true,
+  // },
+
   // --- Single-structure mode (simple) ---
   // structureFile: 'structure.txt',
 
@@ -83,20 +114,25 @@ const config: ScaffoldConfig = {
     //   getContent: (ctx) =>
     //     \`export default function Page() { return <div>\${ctx.targetPath}</div>; }\`,
     // },
-  },
+  }
 };
 
 export default config;
 `;
 
-
 const DEFAULT_STRUCTURE_TXT = `# ${SCAFFOLD_ROOT_DIR}/structure.txt
 # Example structure definition.
-# - Indent with 2 spaces per level
+# - Indent with 2 spaces per level (or your configured indentStep)
 # - Directories must end with "/"
 # - Files do not
 # - Lines starting with "#" are comments and ignored by parser
-
+# - Inline comments are allowed after "#" or "//" separated by whitespace
+#
+# The formatter (when enabled via config.format or --format) will:
+# - Normalize indentation based on indentStep
+# - Preserve blank lines and comments
+# - Keep inline comments attached to their entries
+#
 # Example:
 # src/
 #   index.ts
@@ -110,58 +146,60 @@ const DEFAULT_STRUCTURE_TXT = `# ${SCAFFOLD_ROOT_DIR}/structure.txt
  * - Writes a default structure.txt if missing (or if force = true).
  */
 export async function initScaffold(
-   cwd: string,
-   options: InitScaffoldOptions = {},
+    cwd: string,
+    options: InitScaffoldOptions = {},
 ): Promise<{
-   scaffoldDir: string;
-   configPath: string;
-   structurePath: string;
-   created: { config: boolean; structure: boolean };
+    scaffoldDir: string;
+    configPath: string;
+    structurePath: string;
+    created: { config: boolean; structure: boolean };
 }> {
-   const scaffoldDirRel = options.scaffoldDir ?? SCAFFOLD_ROOT_DIR;
-   const scaffoldDirAbs = path.resolve(cwd, scaffoldDirRel);
-   const configFileName = options.configFileName ?? 'config.ts';
-   const structureFileName = options.structureFileName ?? 'structure.txt';
-
-   ensureDirSync(scaffoldDirAbs);
-
-   const configPath = path.join(scaffoldDirAbs, configFileName);
-   const structurePath = path.join(scaffoldDirAbs, structureFileName);
-
-   let createdConfig = false;
-   let createdStructure = false;
-
-   // config.ts
-   if (fs.existsSync(configPath) && !options.force) {
-      logger.info(`Config already exists at ${configPath} (use --force to overwrite).`);
-   } else {
-      fs.writeFileSync(configPath, DEFAULT_CONFIG_TS, 'utf8');
-      createdConfig = true;
-      logger.info(
-         `${fs.existsSync(configPath) ? 'Overwrote' : 'Created'} config at ${configPath}`,
-      );
-   }
-
-   // structure.txt
-   if (fs.existsSync(structurePath) && !options.force) {
-      logger.info(
-         `Structure file already exists at ${structurePath} (use --force to overwrite).`,
-      );
-   } else {
-      fs.writeFileSync(structurePath, DEFAULT_STRUCTURE_TXT, 'utf8');
-      createdStructure = true;
-      logger.info(
-         `${fs.existsSync(structurePath) ? 'Overwrote' : 'Created'} structure file at ${structurePath}`,
-      );
-   }
-
-   return {
-      scaffoldDir: scaffoldDirAbs,
-      configPath,
-      structurePath,
-      created: {
-         config: createdConfig,
-         structure: createdStructure,
-      },
-   };
+    const scaffoldDirRel = options.scaffoldDir ?? SCAFFOLD_ROOT_DIR;
+    const scaffoldDirAbs = path.resolve(cwd, scaffoldDirRel);
+    const configFileName = options.configFileName ?? 'config.ts';
+    const structureFileName = options.structureFileName ?? 'structure.txt';
+
+    ensureDirSync(scaffoldDirAbs);
+
+    const configPath = path.join(scaffoldDirAbs, configFileName);
+    const structurePath = path.join(scaffoldDirAbs, structureFileName);
+
+    let createdConfig = false;
+    let createdStructure = false;
+
+    // config.ts
+    if (fs.existsSync(configPath) && !options.force) {
+        logger.info(
+            `Config already exists at ${configPath} (use --force to overwrite).`,
+        );
+    } else {
+        fs.writeFileSync(configPath, DEFAULT_CONFIG_TS, 'utf8');
+        createdConfig = true;
+        logger.info(
+            `${fs.existsSync(configPath) ? 'Overwrote' : 'Created'} config at ${configPath}`,
+        );
+    }
+
+    // structure.txt
+    if (fs.existsSync(structurePath) && !options.force) {
+        logger.info(
+            `Structure file already exists at ${structurePath} (use --force to overwrite).`,
+        );
+    } else {
+        fs.writeFileSync(structurePath, DEFAULT_STRUCTURE_TXT, 'utf8');
+        createdStructure = true;
+        logger.info(
+            `${fs.existsSync(structurePath) ? 'Overwrote' : 'Created'} structure file at ${structurePath}`,
+        );
+    }
+
+    return {
+        scaffoldDir: scaffoldDirAbs,
+        configPath,
+        structurePath,
+        created: {
+            config: createdConfig,
+            structure: createdStructure,
+        },
+    };
 }

package/src/core/runner.ts

@@ -1,94 +1,102 @@
 // src/core/runner.ts
 
 import path from 'path';
-import { loadScaffoldConfig } from './config-loader';
+import {loadScaffoldConfig} from './config-loader';
 import {
-   resolveGroupStructure,
-   resolveSingleStructure,
+    resolveGroupStructure,
+    resolveSingleStructure,
 } from './resolve-structure';
-import { CacheManager } from './cache-manager';
-import { HookRunner } from './hook-runner';
-import { applyStructure, type InteractiveDeleteParams } from './apply-structure';
-import type { Logger } from '../util/logger';
-import { defaultLogger } from '../util/logger';
+import {CacheManager} from './cache-manager';
+import {HookRunner} from './hook-runner';
+import {applyStructure, type InteractiveDeleteParams} from './apply-structure';
+import type {Logger} from '../util/logger';
+import {defaultLogger} from '../util/logger';
+import {formatStructureFilesFromConfig} from "./format";
 
 export interface RunOptions {
-   /**
-    * Optional interactive delete callback; if omitted, deletions
-    * above the size threshold will be skipped (kept + removed from cache).
-    */
-   interactiveDelete?: (
-      params: InteractiveDeleteParams,
-   ) => Promise<'delete' | 'keep'>;
+    /**
+     * Optional interactive delete callback; if omitted, deletions
+     * above the size threshold will be skipped (kept + removed from cache).
+     */
+    interactiveDelete?: (
+        params: InteractiveDeleteParams,
+    ) => Promise<'delete' | 'keep'>;
 
-   /**
-    * Optional logger override.
-    */
-   logger?: Logger;
+    /**
+     * Optional logger override.
+     */
+    logger?: Logger;
 
-   /**
-    * Optional overrides (e.g. allow CLI to point at a different scaffold dir).
-    */
-   scaffoldDir?: string;
-   configPath?: string;
+    /**
+     * Optional overrides (e.g. allow CLI to point at a different scaffold dir).
+     */
+    scaffoldDir?: string;
+    configPath?: string;
+    /**
+     * If true, force formatting even if config.format?.enabled === false.
+     * This is what `--format` will use.
+     */
+    format?: boolean;
 }
 
 /**
  * Run scaffold once for the current working directory.
  */
 export async function runOnce(cwd: string, options: RunOptions = {}): Promise<void> {
-   const logger = options.logger ?? defaultLogger.child('[runner]');
-   const { config, scaffoldDir, projectRoot } = await loadScaffoldConfig(cwd, {
-      scaffoldDir: options.scaffoldDir,
-      configPath: options.configPath,
-   });
+    const logger = options.logger ?? defaultLogger.child('[runner]');
+    const {config, scaffoldDir, projectRoot} = await loadScaffoldConfig(cwd, {
+        scaffoldDir: options.scaffoldDir,
+        configPath: options.configPath,
+    });
 
-   const cachePath = config.cacheFile ?? '.scaffold-cache.json';
-   const cache = new CacheManager(projectRoot, cachePath);
-   cache.load();
+    await formatStructureFilesFromConfig(projectRoot, scaffoldDir, config, {force: options.format})
 
-   const hooks = new HookRunner(config);
+    const cachePath = config.cacheFile ?? '.scaffold-cache.json';
+    const cache = new CacheManager(projectRoot, cachePath);
+    cache.load();
 
-   // Grouped mode
-   if (config.groups && config.groups.length > 0) {
-      for (const group of config.groups) {
-         const groupRootAbs = path.resolve(projectRoot, group.root);
-         const structure = resolveGroupStructure(scaffoldDir, group);
+    const hooks = new HookRunner(config);
 
-         const groupLogger = logger.child(`[group:${group.name}]`);
+    // Grouped mode
+    if (config.groups && config.groups.length > 0) {
+        for (const group of config.groups) {
+            const groupRootAbs = path.resolve(projectRoot, group.root);
+            const structure = resolveGroupStructure(scaffoldDir, group);
 
-         // eslint-disable-next-line no-await-in-loop
-         await applyStructure({
+            const groupLogger = logger.child(`[group:${group.name}]`);
+
+            // eslint-disable-next-line no-await-in-loop
+            await applyStructure({
+                config,
+                projectRoot,
+                baseDir: groupRootAbs,
+                structure,
+                cache,
+                hooks,
+                groupName: group.name,
+                groupRoot: group.root,
+                interactiveDelete: options.interactiveDelete,
+                logger: groupLogger,
+            });
+        }
+    } else {
+        // Single-root mode
+        const structure = resolveSingleStructure(scaffoldDir, config);
+        const baseLogger = logger.child('[group:default]');
+
+        await applyStructure({
             config,
             projectRoot,
-            baseDir: groupRootAbs,
+            baseDir: projectRoot,
             structure,
             cache,
             hooks,
-            groupName: group.name,
-            groupRoot: group.root,
+            groupName: 'default',
+            groupRoot: '.',
             interactiveDelete: options.interactiveDelete,
-            logger: groupLogger,
-         });
-      }
-   } else {
-      // Single-root mode
-      const structure = resolveSingleStructure(scaffoldDir, config);
-      const baseLogger = logger.child('[group:default]');
-
-      await applyStructure({
-         config,
-         projectRoot,
-         baseDir: projectRoot,
-         structure,
-         cache,
-         hooks,
-         groupName: 'default',
-         groupRoot: '.',
-         interactiveDelete: options.interactiveDelete,
-         logger: baseLogger,
-      });
-   }
+            logger: baseLogger,
+        });
+    }
 
-   cache.save();
+    cache.save();
 }