@timeax/scaffold 0.0.5 → 0.0.6

package/dist/config-C0067l3c.d.cts

@@ -0,0 +1,383 @@
+/**
+ * Common options that can be applied to both files and directories
+ * in the scaffold structure.
+ *
+ * These options are *declarative* — they do not enforce behavior by
+ * themselves; they are consumed by the core engine.
+ */
+interface BaseEntryOptions {
+    /**
+     * Glob patterns relative to the group root or project root
+     * (depending on how the engine is called).
+     *
+     * If provided, at least one pattern must match the entry path
+     * for the entry to be considered.
+     */
+    include?: string[];
+    /**
+     * Glob patterns relative to the group root or project root.
+     *
+     * If any pattern matches the entry path, the entry will be ignored.
+     */
+    exclude?: string[];
+    /**
+     * Name of the stub to use when creating this file or directory’s
+     * content. For directories, this can act as an “inherited” stub
+     * for child files if the engine chooses to support that behavior.
+     */
+    stub?: string;
+}
+/**
+ * A single file entry in the structure tree.
+ *
+ * Paths are always stored as POSIX-style forward-slash paths
+ * relative to the group root / project root.
+ */
+interface FileEntry extends BaseEntryOptions {
+    type: 'file';
+    /**
+     * File path (e.g. "src/index.ts", "Models/User.php").
+     * Paths should never end with a trailing slash.
+     */
+    path: string;
+}
+/**
+ * A directory entry in the structure tree.
+ *
+ * Paths should *logically* represent directories and may end
+ * with a trailing slash for readability (the engine can normalize).
+ */
+interface DirEntry extends BaseEntryOptions {
+    type: 'dir';
+    /**
+     * Directory path (e.g. "src/", "src/schema/", "Models/").
+     * It is recommended (but not strictly required) that directory
+     * paths end with a trailing slash.
+     */
+    path: string;
+    /**
+     * Nested structure entries for files and subdirectories.
+     */
+    children?: StructureEntry[];
+}
+/**
+ * A single node in the structure tree:
+ * either a file or a directory.
+ */
+type StructureEntry = FileEntry | DirEntry;
+
+/**
+ * Lifecycle stages for non-stub (regular) hooks.
+ *
+ * These hooks are called around file operations (create/delete).
+ */
+type RegularHookKind = 'preCreateFile' | 'postCreateFile' | 'preDeleteFile' | 'postDeleteFile';
+/**
+ * Lifecycle stages for stub-related hooks.
+ *
+ * These hooks are called around stub resolution for file content.
+ */
+type StubHookKind = 'preStub' | 'postStub';
+/**
+ * Context object passed to all hooks (both regular and stub).
+ */
+interface HookContext {
+    /**
+     * Absolute path to the group root / project root that this
+     * scaffold run is targeting.
+     */
+    projectRoot: string;
+    /**
+     * Path of the file or directory relative to the project root
+     * used for this run (or group root, if grouped).
+     *
+     * Example: "src/index.ts", "Http/Controllers/Controller.php".
+     */
+    targetPath: string;
+    /**
+     * Absolute path to the file or directory on disk.
+     */
+    absolutePath: string;
+    /**
+     * Whether the target is a directory.
+     * (For now, most hooks will be for files, but this is future-proofing.)
+     */
+    isDirectory: boolean;
+    /**
+     * The stub name associated with the file (if any).
+     *
+     * For regular hooks, this can be used to detect which stub
+     * produced a given file.
+     */
+    stubName?: string;
+}
+/**
+ * Common filter options used by both regular and stub hooks.
+ *
+ * Filters are evaluated against the `targetPath`.
+ */
+interface HookFilter {
+    /**
+     * Glob patterns which must match for the hook to run.
+     * If provided, at least one pattern must match.
+     */
+    include?: string[];
+    /**
+     * Glob patterns which, if any match, will prevent the hook
+     * from running.
+     */
+    exclude?: string[];
+    /**
+     * Additional patterns or explicit file paths, treated similarly
+     * to `include` — mainly a convenience alias.
+     */
+    files?: string[];
+}
+/**
+ * Function signature for regular hooks.
+ */
+type RegularHookFn = (ctx: HookContext) => void | Promise<void>;
+/**
+ * Function signature for stub hooks.
+ */
+type StubHookFn = (ctx: HookContext) => void | Promise<void>;
+/**
+ * Configuration for a regular hook instance.
+ *
+ * Each hook category (e.g. `preCreateFile`) can have an array
+ * of these, each with its own filter.
+ */
+interface RegularHookConfig extends HookFilter {
+    fn: RegularHookFn;
+}
+/**
+ * Configuration for a stub hook instance.
+ *
+ * Each stub can have its own `preStub` / `postStub` hook arrays,
+ * each with independent filters.
+ */
+interface StubHookConfig extends HookFilter {
+    fn: StubHookFn;
+}
+/**
+ * Stub configuration, defining how file content is generated
+ * and which stub-specific hooks apply.
+ */
+interface StubConfig {
+    /**
+     * Unique name of this stub within the config.
+     * This is referenced from structure entries via `stub: name`.
+     */
+    name: string;
+    /**
+     * Content generator for files that use this stub.
+     *
+     * If omitted, the scaffold engine may default to an empty file.
+     */
+    getContent?: (ctx: HookContext) => string | Promise<string>;
+    /**
+     * Stub-specific hooks called for files that reference this stub.
+     */
+    hooks?: {
+        preStub?: StubHookConfig[];
+        postStub?: StubHookConfig[];
+    };
+}
+
+type FormatMode = 'strict' | 'loose';
+interface FormatConfig {
+    /**
+     * Enable CLI-driven formatting.
+     *
+     * If false or omitted, formatting is only run when the user explicitly
+     * passes `--format` on the CLI.
+     */
+    enabled?: boolean;
+    /**
+     * Default indent step for formatting.
+     * Falls back to top-level `indentStep` or 2 if undefined.
+     */
+    indentStep?: number;
+    /**
+     * AST mode used by the formatter.
+     * - 'loose' (default): try to repair mild indentation issues.
+     * - 'strict': keep lines as-is and only normalize cosmetic whitespace.
+     */
+    mode?: FormatMode;
+    /**
+     * Sort non-comment entries lexicographically within their parent block.
+     * Matches the simple "sortEntries" behaviour you already had.
+     */
+    sortEntries?: boolean;
+    /**
+     * When running `scaffold --watch`, if true then any changed structure file
+     * is formatted after save and before the scaffold run.
+     */
+    formatOnWatch?: boolean;
+}
+/**
+ * Configuration for a single structure group.
+ *
+ * Groups allow you to clearly separate different roots in a project,
+ * such as "app", "routes", "resources/js", etc., each with its own
+ * structure definition.
+ */
+interface StructureGroupConfig {
+    /**
+     * Human-readable identifier for the group (e.g. "app", "routes", "frontend").
+     * Used mainly for logging and, optionally, cache metadata.
+     */
+    name: string;
+    /**
+     * Root directory for this group, relative to the overall project root.
+     *
+     * Example: "app", "routes", "resources/js".
+     *
+     * All paths produced from this group's structure are resolved
+     * relative to this directory.
+     */
+    root: string;
+    /**
+     * Optional inline structure entries for this group.
+     * If present and non-empty, these take precedence over `structureFile`.
+     */
+    structure?: StructureEntry[];
+    /**
+     * Name of the structure file inside the scaffold directory for this group.
+     *
+     * Example: "app.txt", "routes.txt".
+     *
+     * If omitted, the default is `<name>.txt` within the scaffold directory.
+     */
+    structureFile?: string;
+}
+/**
+ * Root configuration object for @timeax/scaffold.
+ *
+ * This is what you export from `scaffold/config.ts` in a consuming
+ * project, or from any programmatic usage of the library.
+ */
+interface ScaffoldConfig {
+    /**
+     * Absolute or relative project root (where files are created).
+     *
+     * If omitted, the engine will treat `process.cwd()` as the root.
+     */
+    root?: string;
+    /**
+     * Base directory where structures are applied and files/folders
+     * are actually created.
+     *
+     * This is resolved relative to `root` (not CWD).
+     *
+     * Default: same as `root`.
+     *
+     * Examples:
+     * - base: '.'       with root: '.'       → apply to <cwd>
+     * - base: 'src'     with root: '.'       → apply to <cwd>/src
+     * - base: '..'      with root: 'tools'   → apply to <cwd>/tools/..
+     */
+    base?: string;
+    /**
+     * Path to the scaffold cache file, relative to `root`.
+     *
+     * Default: ".scaffold-cache.json"
+     */
+    cacheFile?: string;
+    /**
+     * File size threshold (in bytes) above which deletions become
+     * interactive (e.g. ask "are you sure?").
+     *
+     * Default is determined by the core engine (e.g. 128 KB).
+     */
+    sizePromptThreshold?: number;
+    /**
+     * Optional single-root structure (legacy or simple mode).
+     *
+     * If `groups` is defined and non-empty, this is ignored.
+     * Paths are relative to `root` in this mode.
+     */
+    structure?: StructureEntry[];
+    /**
+     * Name of the single structure file in the scaffold directory
+     * for legacy mode.
+     *
+     * If `groups` is empty and `structure` is not provided, this
+     * file name is used (default: "structure.txt").
+     */
+    structureFile?: string;
+    /**
+     * Multiple structure groups (recommended).
+     *
+     * When provided and non-empty, the engine will iterate over each
+     * group and apply its structure relative to each group's `root`.
+     */
+    groups?: StructureGroupConfig[];
+    /**
+     * Hook configuration for file lifecycle events.
+     *
+     * Each category (e.g. "preCreateFile") is an array of hook configs,
+     * each with its own `include` / `exclude` / `files` filters.
+     */
+    hooks?: {
+        [K in RegularHookKind]?: RegularHookConfig[];
+    };
+    /**
+     * Stub definitions keyed by stub name.
+     *
+     * These are referenced from structure entries by `stub: name`.
+     */
+    stubs?: Record<string, StubConfig>;
+    /**
+     * When true, the CLI or consuming code may choose to start scaffold
+     * in watch mode by default (implementation-specific).
+     *
+     * This flag itself does not start watch mode; it is a hint to the
+     * runner / CLI.
+     */
+    watch?: boolean;
+    /**
+     * Number of spaces per indent level in structure files.
+     * Default: 2.
+     *
+     * Examples:
+     * - 2  → "··entry"
+     * - 4  → "····entry"
+     */
+    indentStep?: number;
+    /**
+     * Formatting configuration for structure files.
+     */
+    format?: FormatConfig;
+}
+/**
+ * Options when scanning an existing directory into a structure.txt tree.
+ */
+interface ScanStructureOptions {
+    /**
+     * Glob patterns (relative to the scanned root) to ignore.
+     */
+    ignore?: string[];
+    /**
+     * Maximum depth to traverse (0 = only that dir).
+     * Default: Infinity (no limit).
+     */
+    maxDepth?: number;
+}
+/**
+ * Options when scanning based on the scaffold config/groups.
+ */
+interface ScanFromConfigOptions extends ScanStructureOptions {
+    /**
+     * If provided, only scan these group names (by `StructureGroupConfig.name`).
+     * If omitted, all groups are scanned (or single-root mode).
+     */
+    groups?: string[];
+    /**
+     * Optional override for scaffold directory; normally you can let
+     * loadScaffoldConfig resolve this from "<cwd>/scaffold".
+     */
+    scaffoldDir?: string;
+}
+
+export type { BaseEntryOptions as B, DirEntry as D, FileEntry as F, HookContext as H, RegularHookKind as R, ScaffoldConfig as S, ScanStructureOptions as a, ScanFromConfigOptions as b, StructureEntry as c, StubHookKind as d, HookFilter as e, RegularHookFn as f, StubHookFn as g, RegularHookConfig as h, StubHookConfig as i, StubConfig as j, FormatMode as k, FormatConfig as l, StructureGroupConfig as m };