scaffoldrite 1.0.0

package/dist/parser.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStructure = parseStructure;
+const constraints_1 = require("./constraints");
+const INVALID_NAME_REGEX = /[^a-zA-Z0-9._-]/;
+function validateName(name, line) {
+    if (name === "__root__") {
+        throw new Error(`[Line ${line}] Reserved name "__root__" is not allowed`);
+    }
+    if (INVALID_NAME_REGEX.test(name)) {
+        throw new Error(`[Line ${line}] Invalid characters in name: "${name}"`);
+    }
+}
+function parseStructure(input) {
+    const lines = input.split("\n");
+    const root = { type: "folder", name: "__root__", children: [] };
+    const stack = [root];
+    let constraints = [];
+    let inConstraints = false;
+    let braceDepth = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const lineNumber = i + 1;
+        const raw = lines[i];
+        const line = raw.trim();
+        const codeLine = line.split("//")[0].trim();
+        if (codeLine.length === 0)
+            continue;
+        if (line.length === 0)
+            continue;
+        // Start constraints block
+        if (line === "constraints {") {
+            inConstraints = true;
+            braceDepth = 1;
+            continue;
+        }
+        // If we are inside constraints block
+        if (inConstraints) {
+            if (line.includes("{"))
+                braceDepth++;
+            if (line.includes("}"))
+                braceDepth--;
+            // If braceDepth becomes 0, constraints ended
+            if (braceDepth === 0) {
+                inConstraints = false;
+                continue;
+            }
+            constraints.push(line);
+            continue;
+        }
+        // Folder logic
+        if (line.startsWith("folder ")) {
+            const match = line.match(/^folder\s+(.+)\s+\{$/);
+            if (!match) {
+                throw new Error(`[Line ${lineNumber}] Invalid folder syntax: "${line}"`);
+            }
+            const name = match[1];
+            validateName(name, lineNumber);
+            const parent = stack[stack.length - 1];
+            if (parent.children.some(c => c.type === "folder" && c.name === name)) {
+                throw new Error(`[Line ${lineNumber}] Duplicate folder name "${name}" in the same scope`);
+            }
+            const folder = { type: "folder", name, children: [] };
+            parent.children.push(folder);
+            stack.push(folder);
+            continue;
+        }
+        // File logic
+        if (line.startsWith("file ")) {
+            const match = line.match(/^file\s+(.+)$/);
+            if (!match) {
+                throw new Error(`[Line ${lineNumber}] Invalid file syntax: "${line}"`);
+            }
+            const name = match[1];
+            validateName(name, lineNumber);
+            const parent = stack[stack.length - 1];
+            if (parent.children.some(c => c.type === "file" && c.name === name)) {
+                throw new Error(`[Line ${lineNumber}] Duplicate file name "${name}" in the same scope`);
+            }
+            const file = { type: "file", name };
+            parent.children.push(file);
+            continue;
+        }
+        // Close folder
+        if (line === "}") {
+            if (stack.length === 1) {
+                throw new Error(`[Line ${lineNumber}] Unexpected "}"`);
+            }
+            stack.pop();
+            continue;
+        }
+        throw new Error(`[Line ${lineNumber}] Unknown statement: "${line}"`);
+    }
+    if (stack.length !== 1) {
+        throw new Error(`Unclosed folder block`);
+    }
+    return {
+        root,
+        constraints: (0, constraints_1.parseConstraints)(constraints.join("\n")),
+        rawConstraints: constraints
+    };
+}

package/dist/structure.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findNode = findNode;
+exports.addNode = addNode;
+exports.deleteNode = deleteNode;
+exports.renameNode = renameNode;
+function findNode(root, pathStr) {
+    const parts = pathStr.split("/").filter(Boolean);
+    let current = root;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const child = current.children.find(c => c.name === part);
+        if (!child)
+            return null;
+        if (i === parts.length - 1)
+            return child;
+        if (child.type !== "folder")
+            return null;
+        current = child;
+    }
+    return null;
+}
+function addNode(root, pathStr, type, options = {}) {
+    const parts = pathStr.split("/").filter(Boolean);
+    const name = parts.pop();
+    if (!name) {
+        throw new Error("Invalid path: path is empty. Example: src/components/Button.ts");
+    }
+    let current = root;
+    for (const part of parts) {
+        let child = current.children.find(c => c.name === part && c.type === "folder");
+        if (!child) {
+            child = { type: "folder", name: part, children: [] };
+            current.children.push(child);
+        }
+        current = child;
+    }
+    const exists = current.children.some(c => c.name === name);
+    if (exists) {
+        if (options.ifNotExists)
+            return; // do nothing
+        if (!options.force) {
+            throw new Error(`Cannot create ${type}: '${pathStr}' already exists in the structure.`);
+        }
+        // force = true -> replace existing node
+        const idx = current.children.findIndex(c => c.name === name);
+        current.children.splice(idx, 1);
+    }
+    const newNode = type === "folder"
+        ? { type: "folder", name, children: [] }
+        : { type: "file", name };
+    current.children.push(newNode);
+    return current;
+}
+function deleteNode(root, pathStr) {
+    const parts = pathStr.split("/").filter(Boolean);
+    const name = parts.pop();
+    if (!name) {
+        throw new Error("Invalid path: path is empty. Example: src/components/Button.ts");
+    }
+    let current = root;
+    for (const part of parts) {
+        const child = current.children.find(c => c.name === part && c.type === "folder");
+        if (!child) {
+            throw new Error(`Path not found: '${parts.join("/")}' does not exist in the structure.`);
+        }
+        current = child;
+    }
+    const index = current.children.findIndex(c => c.name === name);
+    if (index === -1) {
+        throw new Error(`Node not found: '${pathStr}' does not exist in the structure.`);
+    }
+    current.children.splice(index, 1);
+}
+function renameNode(root, pathStr, newName) {
+    const node = findNode(root, pathStr);
+    if (!node) {
+        throw new Error(`Node not found: '${pathStr}' does not exist.`);
+    }
+    if (!newName || newName.trim().length === 0) {
+        throw new Error("Invalid new name: name cannot be empty.");
+    }
+    node.name = newName;
+}

package/dist/validateFS.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IGNORES = void 0;
+exports.loadIgnoreList = loadIgnoreList;
+exports.validateFS = validateFS;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const ignoreFilePath = "./.scaffoldignore";
+exports.DEFAULT_IGNORES = [
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    "coverage",
+    ".turbo",
+];
+function loadIgnoreList(filePath) {
+    if (!fs_1.default.existsSync(filePath))
+        return [];
+    const content = fs_1.default.readFileSync(filePath, "utf-8");
+    return content
+        .split("\n")
+        .map((x) => x.trim())
+        .map((x) => x.split("#")[0].trim())
+        .filter(Boolean);
+}
+function getIgnoreList() {
+    return fs_1.default.existsSync(ignoreFilePath)
+        ? loadIgnoreList(ignoreFilePath)
+        : exports.DEFAULT_IGNORES;
+}
+function isIgnored(itemName) {
+    return getIgnoreList().includes(itemName);
+}
+function validateFS(root, dir, allowExtra = false, allowExtraPaths = []) {
+    if (!fs_1.default.existsSync(dir)) {
+        throw new Error(`Folder does not exist: ${dir}`);
+    }
+    const actualItems = fs_1.default.readdirSync(dir);
+    // Check missing items in filesystem
+    for (const child of root.children) {
+        // skip ignored files/folders
+        if (isIgnored(child.name))
+            continue;
+        const expectedPath = path_1.default.join(dir, child.name);
+        if (!fs_1.default.existsSync(expectedPath)) {
+            throw new Error(`Missing in filesystem: ${expectedPath}`);
+        }
+        if (child.type === "folder") {
+            if (!fs_1.default.statSync(expectedPath).isDirectory()) {
+                throw new Error(`Expected folder but found file: ${expectedPath}`);
+            }
+            validateFS(child, expectedPath, allowExtra, allowExtraPaths);
+        }
+        else {
+            if (!fs_1.default.statSync(expectedPath).isFile()) {
+                throw new Error(`Expected file but found folder: ${expectedPath}`);
+            }
+        }
+    }
+    // Check extra items in filesystem not in .sr
+    for (const item of actualItems) {
+        // skip ignored files/folders
+        if (isIgnored(item))
+            continue;
+        const existsInSr = root.children.some((c) => c.name === item);
+        if (!existsInSr) {
+            const extraPath = path_1.default.join(dir, item);
+            const allowedExplicitly = allowExtraPaths.some((p) => {
+                const normalized = path_1.default.normalize(p);
+                const extraRel = path_1.default.relative(dir, extraPath);
+                const extraBasename = path_1.default.basename(extraPath);
+                return (extraBasename === normalized ||
+                    extraRel === normalized ||
+                    extraRel.endsWith(normalized));
+            });
+            if (allowExtra || allowedExplicitly)
+                continue;
+            throw new Error(`Extra file/folder found in filesystem: ${extraPath}`);
+        }
+    }
+}

package/dist/validator.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateConstraints = validateConstraints;
+function normalizePath(path) {
+    if (!path || path.trim() === "")
+        return "__root__";
+    return path.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function findNodeByPath(root, path) {
+    const normalizedPath = normalizePath(path);
+    const parts = normalizedPath.split("/").filter(Boolean);
+    let current = root;
+    if (parts[0] === root.name) {
+        parts.shift();
+    }
+    for (const part of parts) {
+        if (current.type !== "folder")
+            return null;
+        const next = current.children.find((c) => c.name === part);
+        if (!next)
+            return null;
+        current = next;
+    }
+    return current;
+}
+function countFiles(folder) {
+    return folder.children.filter((c) => c.type === "file").length;
+}
+function countFolders(folder) {
+    return folder.children.filter((c) => c.type === "folder").length;
+}
+function countFilesRecursive(folder, ext) {
+    let count = 0;
+    for (const child of folder.children) {
+        if (child.type === "file") {
+            if (!ext || child.name.endsWith(ext))
+                count++;
+        }
+        if (child.type === "folder")
+            count += countFilesRecursive(child, ext);
+    }
+    return count;
+}
+function countFoldersRecursive(folder) {
+    let count = 0;
+    for (const child of folder.children) {
+        if (child.type === "folder")
+            count++;
+        if (child.type === "folder")
+            count += countFoldersRecursive(child);
+    }
+    return count;
+}
+function maxDepth(folder, current = 0) {
+    let depth = current;
+    for (const child of folder.children) {
+        if (child.type === "folder") {
+            depth = Math.max(depth, maxDepth(child, current + 1));
+        }
+    }
+    return depth;
+}
+function getFoldersByScope(root, path, scope) {
+    const folder = findNodeByPath(root, path);
+    if (!folder || folder.type !== "folder")
+        return [];
+    const folders = [];
+    if (scope === "*") {
+        // only direct child folders
+        for (const child of folder.children) {
+            if (child.type === "folder")
+                folders.push(child);
+        }
+    }
+    if (scope === "**") {
+        // recursively collect all folders
+        function traverse(f) {
+            for (const child of f.children) {
+                if (child.type === "folder") {
+                    folders.push(child);
+                    traverse(child);
+                }
+            }
+        }
+        traverse(folder);
+    }
+    return folders;
+}
+function validateConstraints(root, constraints) {
+    for (const c of constraints) {
+        if ((c.type !== "eachFolderMustContain" &&
+            c.type !== "eachFolderMustContainFile" &&
+            c.type !== "eachFolderMustContainFolder" &&
+            c.type !== "eachFolderMustHaveExt") &&
+            (!c.path || c.path.trim() === "")) {
+            throw new Error(`Constraint failed: path missing for ${c.type}`);
+        }
+        if (c.type === "require") {
+            const node = findNodeByPath(root, c.path);
+            if (!node)
+                throw new Error(`Constraint failed: required path not found: ${c.path}`);
+        }
+        if (c.type === "forbid") {
+            const node = findNodeByPath(root, c.path);
+            if (node)
+                throw new Error(`Constraint failed: forbidden path exists: ${c.path}`);
+        }
+        if (c.type === "maxFiles") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const fileCount = countFiles(folder);
+            if (fileCount > c.value)
+                throw new Error(`Constraint failed: ${c.path} has more than ${c.value} files`);
+        }
+        if (c.type === "maxFilesRecursive") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const fileCount = countFilesRecursive(folder);
+            if (fileCount > c.value)
+                throw new Error(`Constraint failed: ${c.path} has more than ${c.value} files recursively`);
+        }
+        if (c.type === "maxFilesByExt") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const fileCount = folder.children
+                .filter((x) => x.type === "file")
+                .filter((f) => f.name.endsWith(c.ext)).length;
+            if (fileCount > c.value)
+                throw new Error(`Constraint failed: ${c.path} has more than ${c.value} files of ${c.ext}`);
+        }
+        if (c.type === "maxFilesByExtRecursive") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const extCount = countFilesRecursive(folder, c.ext);
+            if (extCount > c.value)
+                throw new Error(`Constraint failed: ${c.path} has more than ${c.value} files of ${c.ext} recursively`);
+        }
+        if (c.type === "maxFolders") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const folderCount = countFolders(folder);
+            if (folderCount > c.value)
+                throw new Error(`Constraint failed: ${c.path} has more than ${c.value} folders`);
+        }
+        if (c.type === "maxFoldersRecursive") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const folderCount = countFoldersRecursive(folder);
+            if (folderCount > c.value)
+                throw new Error(`Constraint failed: ${c.path} has more than ${c.value} folders recursively`);
+        }
+        if (c.type === "minFiles") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const fileCount = countFiles(folder);
+            if (fileCount < c.value)
+                throw new Error(`Constraint failed: ${c.path} has less than ${c.value} files`);
+        }
+        if (c.type === "minFolders") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const folderCount = countFolders(folder);
+            if (folderCount < c.value)
+                throw new Error(`Constraint failed: ${c.path} has less than ${c.value} folders`);
+        }
+        if (c.type === "mustContain") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const exists = folder.children.some((x) => x.name === c.value);
+            if (!exists)
+                throw new Error(`Constraint failed: ${c.path} must contain ${c.value}`);
+        }
+        if (c.type === "fileNameRegex") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const regex = new RegExp(c.regex);
+            for (const child of folder.children) {
+                if (child.type === "file" && !regex.test(child.name)) {
+                    throw new Error(`Constraint failed: ${child.name} in ${c.path} does not match regex`);
+                }
+            }
+        }
+        if (c.type === "maxDepth") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const depth = maxDepth(folder);
+            if (depth > c.value)
+                throw new Error(`Constraint failed: ${c.path} exceeds max depth of ${c.value}`);
+        }
+        if (c.type === "mustHaveFile") {
+            const folder = findNodeByPath(root, c.path);
+            if (!folder || folder.type !== "folder")
+                continue;
+            const exists = folder.children.some((x) => x.type === "file" && x.name === c.value);
+            if (!exists)
+                throw new Error(`Constraint failed: ${c.path} must have file ${c.value}`);
+        }
+        // ⭐ NEW RULES ⭐
+        if (c.type === "eachFolderMustContain") {
+            const folders = getFoldersByScope(root, c.path, c.scope);
+            for (const folder of folders) {
+                const exists = folder.children.some((x) => x.name === c.value);
+                if (!exists) {
+                    throw new Error(`Constraint failed: ${folder.name} must contain ${c.value}`);
+                }
+            }
+        }
+        if (c.type === "eachFolderMustContainFile") {
+            const folders = getFoldersByScope(root, c.path, c.scope);
+            for (const folder of folders) {
+                const exists = folder.children.some((x) => x.type === "file" && x.name === c.value);
+                if (!exists) {
+                    throw new Error(`Constraint failed: ${folder.name} must contain file ${c.value}`);
+                }
+            }
+        }
+        if (c.type === "eachFolderMustContainFolder") {
+            const folders = getFoldersByScope(root, c.path, c.scope);
+            for (const folder of folders) {
+                const exists = folder.children.some((x) => x.type === "folder" && x.name === c.value);
+                if (!exists) {
+                    throw new Error(`Constraint failed: ${folder.name} must contain folder ${c.value}`);
+                }
+            }
+        }
+        if (c.type === "eachFolderMustHaveExt") {
+            const folders = getFoldersByScope(root, c.path, c.scope);
+            for (const folder of folders) {
+                const exists = folder.children.some((x) => x.type === "file" && x.name.endsWith(c.ext));
+                if (!exists) {
+                    throw new Error(`Constraint failed: ${folder.name} must contain a file with extension ${c.ext}`);
+                }
+            }
+        }
+    }
+}

package/dist/visitor.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visit = visit;
+function visit(node, visitor, currentPath = "") {
+    // 👇 ignore virtual root in path
+    const isVirtualRoot = node.name === "__root__";
+    const nodePath = isVirtualRoot
+        ? currentPath
+        : currentPath
+            ? `${currentPath}/${node.name}`
+            : node.name;
+    if (!isVirtualRoot) {
+        visitor.folder?.(node, nodePath);
+    }
+    for (const child of node.children) {
+        if (child.type === "folder") {
+            visit(child, visitor, nodePath);
+        }
+        else {
+            visitor.file?.(child, `${nodePath}/${child.name}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "scaffoldrite",
+  "version": "1.0.0",
+  "description": "A project structure validator and generator CLI tool.",
+  "author": "Isaac Anasonye",
+  "license": "MIT",
+  "homepage": "https://github.com/Isaacprogi/scaffoldrite#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Isaacprogi/scaffoldrite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Isaacprogi/scaffoldrite/issues"
+  },
+  "keywords": [
+    "cli",
+    "scaffold",
+    "project-structure",
+    "validator",
+    "generator",
+    "developer-tools",
+    "devtools",
+    "node"
+  ],
+  "type": "commonjs",
+  "bin": {
+    "scaffoldrite": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "type-check": "tsc --noEmit",
+    "validate": "npm run type-check && npm run build",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.9",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=17"
+  }
+}