blytz 1.1.0 → 1.2.0

package/README.md

@@ -7,7 +7,7 @@
 - Updates an existing `README.md`
 - Creates a new `README.md` with `--init`
 - Replaces an existing `README.md` with `--force`
-- Reads `package.json` to build README sections automatically
+- Reads `package.json` / `requirements.txt` to build README sections automatically
 - Generates a basic folder tree for the project structure section
 
 ## Install
@@ -16,12 +16,6 @@
 npm install -g blytz
 ```
 
-If you are developing locally from this repository, you can link it instead:
-
-```bash
-npm link
-```
-
 ## Usage
 
 Run the CLI from the root of the project you want to document:
@@ -96,9 +90,9 @@ blytz
 
 ## Notes
 
-- The CLI expects to run in a folder that contains `package.json`
+- The CLI expects to run in a folder that contains `package.json` or `requirements.txt`
 - The CLI reads the local `README.md` in the current directory
-- The folder tree excludes `node_modules` and `.git`
+- The folder tree excludes `node_modules` and `.git` and any folder that might be in `.gitignore`
 
 ## License
 

package/bin/README-NPM.md

@@ -7,7 +7,7 @@
 - Updates an existing `README.md`
 - Creates a new `README.md` with `--init`
 - Replaces an existing `README.md` with `--force`
-- Reads `package.json` to build README sections automatically
+- Reads `package.json` / `requirements.txt` to build README sections automatically
 - Generates a basic folder tree for the project structure section
 
 ## Install
@@ -16,12 +16,6 @@
 npm install -g blytz
 ```
 
-If you are developing locally from this repository, you can link it instead:
-
-```bash
-npm link
-```
-
 ## Usage
 
 Run the CLI from the root of the project you want to document:
@@ -96,9 +90,9 @@ blytz
 
 ## Notes
 
-- The CLI expects to run in a folder that contains `package.json`
+- The CLI expects to run in a folder that contains `package.json` or `requirements.txt`
 - The CLI reads the local `README.md` in the current directory
-- The folder tree excludes `node_modules` and `.git`
+- The folder tree excludes `node_modules` and `.git` and any folder that might be in `.gitignore`
 
 ## License
 

package/bin/cli.js

@@ -2,8 +2,16 @@
 
 import fs from 'fs';
 import path from 'path';
+import readline from 'readline/promises';
 
 import processReadme from '../src/processReadme.js';
+import {
+    buildLocalFileTree,
+    collectNodeDependencies,
+    collectPythonDependencies,
+    collectScripts,
+    getLicenseName
+} from '../src/readmeContext.js';
 
 const args = process.argv.slice(2);
 const shouldShowHelp = args.includes('--help') || args.includes('-h');
@@ -12,113 +20,118 @@ const shouldForce = args.includes('--force');
 const shouldUpdate = args.length === 0 || args.includes('--update');
 const hasAction = shouldUpdate || shouldInit || shouldForce;
 
-if (shouldShowHelp) {
-    console.log('Usage: blytz [--update|--init|--force]');
-    process.exit(0);
-}
-
-if (!hasAction) {
-    console.log('Usage: blytz [--update|--init|--force]');
-    process.exit(0);
-}
-
-function buildFileTree(dirPath, depth = 0, maxDepth = 4) {
-    if (depth >= maxDepth) {
-        return {};
+const supportsColor = process.stdout.isTTY && process.env.NO_COLOR !== '1';
+const ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    blue: '\x1b[34m'
+};
+
+function colorize(text, ...codes) {
+    if (!supportsColor) {
+        return text;
     }
 
-    const tree = {};
-    const entries = fs.readdirSync(dirPath, { withFileTypes: true })
-        .filter(entry => entry.name !== 'node_modules' && entry.name !== '.git')
-        .sort((left, right) => left.name.localeCompare(right.name));
-
-    for (const entry of entries) {
-        const entryPath = path.join(dirPath, entry.name);
-
-        if (entry.isDirectory()) {
-            tree[entry.name] = buildFileTree(entryPath, depth + 1, maxDepth);
-        } else {
-            tree[entry.name] = null;
-        }
-    }
-
-    return tree;
+    return `${codes.join('')}${text}${ANSI.reset}`;
 }
 
-function collectDependencies(packageJson) {
-    return Object.keys(packageJson.dependencies || {}).sort();
+function formatLabel(label, color) {
+    return colorize(label, ANSI.bold, color);
 }
 
-function collectPythonDependencies(requirementsContent) {
-    return requirementsContent
-        .split(/\r?\n/)
-        .map(line => line.trim())
-        .filter(line => line && !line.startsWith('#'))
-        .filter(line => !line.startsWith('-'))
-        .map(line => line.split(';')[0].trim())
-        .map(line => line.split(/[=<>!~]/)[0].trim())
-        .filter(Boolean)
-        .sort((left, right) => left.localeCompare(right));
+function printHelp(output = console.log) {
+    output([
+        formatLabel('Usage', ANSI.blue),
+        `  ${colorize('blytz', ANSI.bold, ANSI.green)} ${colorize('[command]', ANSI.dim)}`,
+        '',
+        formatLabel('Commands', ANSI.blue),
+        `  ${colorize('--update', ANSI.yellow)}         ${colorize('Update the existing README.md using project metadata.', ANSI.dim)}`,
+        `  ${colorize('--init', ANSI.yellow)}           ${colorize('Create a new README.md and prompt for title and description.', ANSI.dim)}`,
+        `  ${colorize('--force', ANSI.yellow)}          ${colorize('Replace the existing README.md with a newly generated one.', ANSI.dim)}`,
+        `  ${colorize('--help, -h', ANSI.yellow)}       ${colorize('Show this help message.', ANSI.dim)}`,
+        '',
+    ].join('\n'));
 }
 
-function collectScripts(packageJson) {
-    const scripts = new Map();
+if (shouldShowHelp) {
+    printHelp();
+    process.exit(0);
+}
 
-    for (const [name, command] of Object.entries(packageJson.scripts || {})) {
-        scripts.set(name, [{ package: '(root)', command }]);
+if (!hasAction) {
+    if (args.length > 0) {
+        const invalidCommand = args.find(arg => arg.startsWith('-')) || args[0];
+        console.error(`${formatLabel('Error', ANSI.red)} Command not available: ${colorize(invalidCommand, ANSI.bold, ANSI.red)}`);
+        console.error('');
+        printHelp(console.error);
+        process.exit(1);
     }
-
-    return scripts;
+    printHelp();
+    process.exit(0);
 }
 
-function getLicenseName(licenseContent) {
-    const firstLine = licenseContent
-        .split(/\r?\n/)
-        .map(line => line.trim())
-        .find(Boolean);
-
-    return firstLine || '';
+async function promptForTitleAndDescription() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    try {
+        const titleContent = (await rl.question(`${formatLabel('Title', ANSI.yellow)} ${colorize('(leave blank to use project name)', ANSI.dim)}: `)).trim();
+        const descriptionContent = (await rl.question(`${formatLabel('Description', ANSI.yellow)} ${colorize('(leave blank to use default intro)', ANSI.dim)}: `)).trim();
+        return { titleContent, descriptionContent };
+    } finally {
+        rl.close();
+    }
 }
 
-console.log("Scanning for project files...");
-
-const targetDir = process.cwd();
-const readmePath = path.join(targetDir, 'README.md');
-const packageJsonPath = path.join(targetDir, 'package.json');
-const requirementsPath = path.join(targetDir, 'requirements.txt');
-const licensePath = path.join(targetDir, 'LICENSE');
-const readmeExists = fs.existsSync(readmePath);
-const hasPackageJson = fs.existsSync(packageJsonPath);
-const hasRequirements = fs.existsSync(requirementsPath);
-const hasLicense = fs.existsSync(licensePath);
-
-if (!readmeExists && !shouldInit && !shouldForce) {
-    console.error("Error: No README.md found in this directory. Try --init.");
-    process.exit(1);
-}
+async function main() {
+    console.log(`${formatLabel('Info', ANSI.cyan)} Scanning for project files...`);
+
+    const targetDir = process.cwd();
+    const readmePath = path.join(targetDir, 'README.md');
+    const packageJsonPath = path.join(targetDir, 'package.json');
+    const requirementsPath = path.join(targetDir, 'requirements.txt');
+    const licensePath = path.join(targetDir, 'LICENSE');
+    const readmeExists = fs.existsSync(readmePath);
+    const hasPackageJson = fs.existsSync(packageJsonPath);
+    const hasRequirements = fs.existsSync(requirementsPath);
+    const hasLicense = fs.existsSync(licensePath);
+
+    if (!readmeExists && !shouldInit && !shouldForce) {
+        console.error(`${formatLabel('Error', ANSI.red)} No README.md found in this directory. Try ${colorize('--init', ANSI.bold, ANSI.yellow)}.`);
+        process.exit(1);
+    }
 
-if (readmeExists && shouldInit && !shouldForce) {
-    console.error("README.md already exists. Try --force.");
-    process.exit(1);
-}
+    if (readmeExists && shouldInit && !shouldForce) {
+        console.error(`${formatLabel('Error', ANSI.red)} README.md already exists. Try ${colorize('--force', ANSI.bold, ANSI.red)}.`);
+        process.exit(1);
+    }
 
-if (!hasPackageJson && !hasRequirements) {
-    console.error("Error: No package.json or requirements.txt found in this directory.");
-    process.exit(1);
-}
+    if (!hasPackageJson && !hasRequirements) {
+        console.error(`${formatLabel('Error', ANSI.red)} No ${colorize('package.json', ANSI.bold)} or ${colorize('requirements.txt', ANSI.bold)} found in this directory.`);
+        process.exit(1);
+    }
 
-console.log("Files found. Processing README...");
+    console.log(`${formatLabel('Info', ANSI.cyan)} Files found. Processing README...`);
 
-try {
     if (shouldForce && readmeExists) {
         fs.unlinkSync(readmePath);
     }
 
-    // 1. Read the raw text of both files
     const readmeContent = fs.existsSync(readmePath) ? fs.readFileSync(readmePath, 'utf-8') : '';
-    const fileTree = buildFileTree(targetDir);
+    const fileTree = buildLocalFileTree(fs, path, targetDir, targetDir);
     const projectName = path.basename(targetDir);
     const licenseName = hasLicense ? getLicenseName(fs.readFileSync(licensePath, 'utf-8')) : '';
+    const shouldPromptMetadata = !shouldUpdate;
+    const { titleContent, descriptionContent } = shouldPromptMetadata
+        ? await promptForTitleAndDescription()
+        : { titleContent: '', descriptionContent: '' };
     let context;
     let projectType;
 
@@ -129,9 +142,11 @@ try {
         context = {
             packageJson,
             packages: [{ path: 'package.json', content: packageJson }],
-            dependencies: collectDependencies(packageJson),
-            scripts: collectScripts(packageJson),
+            dependencies: collectNodeDependencies([{ path: 'package.json', content: packageJson }]),
+            scripts: collectScripts([{ path: 'package.json', content: packageJson }]),
             fileTree,
+            titleContent,
+            descriptionContent,
             licenseName,
             username: packageJson.author || process.env.USERNAME || 'Unknown Author',
             projectName: packageJson.name || projectName,
@@ -144,9 +159,11 @@ try {
 
         context = {
             packages: [{ path: 'requirements.txt', content: requirementsContent }],
-            dependencies: collectPythonDependencies(requirementsContent),
+            dependencies: collectPythonDependencies([{ path: 'requirements.txt', content: requirementsContent }]),
             scripts: new Map(),
             fileTree,
+            titleContent,
+            descriptionContent,
             licenseName,
             username: process.env.USERNAME || 'Unknown Author',
             projectName,
@@ -156,15 +173,15 @@ try {
         projectType = 'python';
     }
 
-    // 3. Feed everything into your pure engine
     const updatedReadme = processReadme(readmeContent, projectType, context);
 
-    // 4. Overwrite the existing README.md with the new content
     fs.writeFileSync(readmePath, updatedReadme, 'utf-8');
 
-    console.log("Success! README.md has been auto-fixed.");
-
-} catch (error) {
-    console.error("An error occurred during processing:", error.message);
-    process.exit(1);
+    console.log(`${formatLabel('Success', ANSI.green)} README.md has been auto-fixed.`);
 }
+
+(main()
+    .catch(error => {
+        console.error(`${formatLabel('Error', ANSI.red)} An error occurred during processing: ${error.message}`);
+        process.exit(1);
+    }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blytz",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "bin": {
     "blytz": "./bin/cli.js"
   },

package/src/processReadme.js

@@ -2,16 +2,22 @@ import getDefaultContent from "./template.js";
 
 
 //Core engine: processes README content and returns updated version
-export default function processReadme(content, projectType, context = {}) {
-
-    const normalizedContent = (content || "").replace(/^##(?=\S)/gm, "## ");
+export default function processReadme(content, projectType, context = {}) {
+    const { titleContent = "", descriptionContent = "", projectName = "" } = context ?? {};
+
+    const normalizedContent = (content || "").replace(/^##(?=\S)/gm, "## ");
 
     // Split into sections
     const sections = normalizedContent.split("## ");
     const sectionMap = {};
 
-    // Extract intro (title + description)
-    const intro = sections[0].trim();
+    // Extract intro (title + description)
+    const intro = sections[0].trim();
+    const resolvedTitle = titleContent || projectName || "";
+    const resolvedDescription = descriptionContent || getDefaultContent("description", projectType, context);
+    const finalIntro = resolvedTitle
+        ? [`# ${resolvedTitle}`, resolvedDescription].filter(Boolean).join("\n\n")
+        : intro;
 
     // Parse sections
     sections.slice(1).forEach(section => {
@@ -22,14 +28,13 @@ export default function processReadme(content, projectType, context = {}) {
         sectionMap[title] = body;
     });
 
-    // Required sections
-    const requiredSections = [
-        "description",
-        "installation",
-        "usage",
-        "dependencies",
-        "folder structure",
-        "license",
+    // Required sections
+    const requiredSections = [
+        "installation",
+        "usage",
+        "dependencies",
+        "folder structure",
+        "license",
         "built by"
     ];
 
@@ -65,7 +70,7 @@ export default function processReadme(content, projectType, context = {}) {
             .join(" ");
 
     // Rebuild README
-    let newReadme = intro ? intro + "\n\n" : "";
+    let newReadme = finalIntro ? finalIntro + "\n\n" : "";
 
     // Ordered sections
     requiredSections.forEach(section => {
@@ -80,4 +85,4 @@ export default function processReadme(content, projectType, context = {}) {
     });
 
     return newReadme.trim();
-}
+}

package/src/readmeContext.js

@@ -0,0 +1,264 @@
+export const DEFAULT_IGNORED_NAMES = new Set([
+    "node_modules",
+    ".git",
+    ".agent",
+    "dist",
+    "build",
+    "out",
+    "target",
+    "venv",
+    ".venv",
+    "__pycache__",
+    ".idea",
+    ".vscode",
+    ".DS_Store",
+    "Thumbs.db",
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production"
+]);
+
+export function collectNodeDependencies(packages = []) {
+    const dependencies = new Set();
+
+    for (const pkg of packages) {
+        for (const dependency of Object.keys(pkg?.content?.dependencies || {})) {
+            dependencies.add(dependency);
+        }
+    }
+
+    return Array.from(dependencies).sort((left, right) => left.localeCompare(right));
+}
+
+export function collectPythonDependencies(files = []) {
+    const dependencies = new Set();
+
+    for (const file of files) {
+        if (!file?.content) {
+            continue;
+        }
+
+        file.content
+            .split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(line => line && !line.startsWith("#"))
+            .filter(line => !line.startsWith("-"))
+            .map(line => line.split(";")[0].trim())
+            .map(line => line.split(/[=<>!~]/)[0].trim())
+            .filter(Boolean)
+            .forEach(dependency => dependencies.add(dependency));
+    }
+
+    return Array.from(dependencies).sort((left, right) => left.localeCompare(right));
+}
+
+export function collectScripts(packages = []) {
+    const scripts = new Map();
+
+    for (const pkg of packages) {
+        const packageDir = pkg.path === "package.json" ? "(root)" : pkg.path.replace("/package.json", "");
+
+        for (const [name, command] of Object.entries(pkg?.content?.scripts || {})) {
+            if (!scripts.has(name)) {
+                scripts.set(name, []);
+            }
+
+            scripts.get(name).push({ package: packageDir, command });
+        }
+    }
+
+    return scripts;
+}
+
+export function getLicenseName(licenseContent = "") {
+    const firstLine = licenseContent
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(Boolean);
+
+    return firstLine || "";
+}
+
+function escapeRegex(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+
+function globToRegex(pattern) {
+    let regex = "";
+
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        const nextChar = pattern[index + 1];
+
+        if (char === "*") {
+            if (nextChar === "*") {
+                regex += ".*";
+                index += 1;
+            } else {
+                regex += "[^/]*";
+            }
+            continue;
+        }
+
+        if (char === "?") {
+            regex += "[^/]";
+            continue;
+        }
+
+        regex += escapeRegex(char);
+    }
+
+    return regex;
+}
+
+export function parseGitignoreContent(content, baseDir = "") {
+    return content
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(line => line && !line.startsWith("#"))
+        .map(line => {
+            const negated = line.startsWith("!");
+            const rawPattern = negated ? line.slice(1).trim() : line;
+
+            if (!rawPattern) {
+                return null;
+            }
+
+            const directoryOnly = rawPattern.endsWith("/");
+            const normalizedPattern = rawPattern.replace(/\/+$/, "").replace(/\\/g, "/");
+
+            if (!normalizedPattern) {
+                return null;
+            }
+
+            const anchored = normalizedPattern.startsWith("/");
+            const matcherPattern = anchored ? normalizedPattern.slice(1) : normalizedPattern;
+
+            return {
+                baseDir: baseDir.replace(/\\/g, "/"),
+                negated,
+                directoryOnly,
+                hasSlash: matcherPattern.includes("/"),
+                regex: new RegExp(`^${globToRegex(matcherPattern)}(?:/.*)?$`),
+                basenameRegex: new RegExp(`^${globToRegex(matcherPattern)}$`)
+            };
+        })
+        .filter(Boolean);
+}
+
+export function isIgnoredByGitignore(relativePath, isDirectory, gitignoreRules = []) {
+    const normalizedPath = relativePath.replace(/\\/g, "/");
+    let ignored = false;
+
+    for (const rule of gitignoreRules) {
+        if (rule.directoryOnly && !isDirectory) {
+            continue;
+        }
+
+        if (rule.baseDir && normalizedPath !== rule.baseDir && !normalizedPath.startsWith(`${rule.baseDir}/`)) {
+            continue;
+        }
+
+        const scopedPath = rule.baseDir
+            ? normalizedPath.slice(rule.baseDir.length).replace(/^\/+/, "")
+            : normalizedPath;
+        const pathParts = scopedPath.split("/");
+        const matches = rule.hasSlash
+            ? rule.regex.test(scopedPath)
+            : pathParts.some(part => rule.basenameRegex.test(part));
+
+        if (matches) {
+            ignored = !rule.negated;
+        }
+    }
+
+    return ignored;
+}
+
+export function parseLocalGitignore(fs, gitignorePath, baseDir = "") {
+    if (!fs.existsSync(gitignorePath)) {
+        return [];
+    }
+
+    return parseGitignoreContent(fs.readFileSync(gitignorePath, "utf-8"), baseDir);
+}
+
+export function buildLocalFileTree(fs, path, dirPath, rootDir = dirPath, inheritedGitignoreRules = [], depth = 0, maxDepth = 3) {
+    if (depth >= maxDepth) {
+        return {};
+    }
+
+    const relativeDir = path.relative(rootDir, dirPath).replace(/\\/g, "/");
+    const localGitignoreRules = parseLocalGitignore(
+        fs,
+        path.join(dirPath, ".gitignore"),
+        relativeDir === "" ? "" : relativeDir
+    );
+    const gitignoreRules = [...inheritedGitignoreRules, ...localGitignoreRules];
+    const tree = {};
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true })
+        .filter(entry => {
+            if (DEFAULT_IGNORED_NAMES.has(entry.name)) {
+                return false;
+            }
+
+            const entryPath = path.join(dirPath, entry.name);
+            const relativePath = path.relative(rootDir, entryPath);
+
+            return !isIgnoredByGitignore(relativePath, entry.isDirectory(), gitignoreRules);
+        })
+        .sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+        const entryPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+            tree[entry.name] = buildLocalFileTree(fs, path, entryPath, rootDir, gitignoreRules, depth + 1, maxDepth);
+        } else {
+            tree[entry.name] = null;
+        }
+    }
+
+    return tree;
+}
+
+export function buildRemoteFileTree(treeData, gitignoreRules = [], maxDepth = 3) {
+    const fileTree = {};
+
+    if (!treeData?.tree || !Array.isArray(treeData.tree)) {
+        return fileTree;
+    }
+
+    for (const item of treeData.tree) {
+        const parts = item.path.split("/");
+        const name = parts[parts.length - 1];
+        const isDirectory = item.type === "tree";
+
+        if (DEFAULT_IGNORED_NAMES.has(name) || isIgnoredByGitignore(item.path, isDirectory, gitignoreRules)) {
+            continue;
+        }
+
+        if (parts.length > maxDepth) {
+            continue;
+        }
+
+        let current = fileTree;
+
+        for (let index = 0; index < parts.length; index += 1) {
+            const part = parts[index];
+            const isFile = index === parts.length - 1 && item.type === "blob";
+
+            if (isFile) {
+                current[part] = null;
+            } else {
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+    }
+
+    return fileTree;
+}

package/src/template.js

@@ -1,23 +1,24 @@
 import getProjectStructure from "./fileTree.js";
 
 export default function getDefaultContent(section, projectType, context = {}) {
-    const {
-        packages = [],
-        dependencies = [],
-        scripts = new Map(),
+    const {
+        packages = [],
+        dependencies = [],
+        scripts = new Map(),
         fileTree = null,
+        descriptionContent = "",
         licenseName = "",
         username = "Unknown",
-        projectName = "this project",
-        isMonorepo = false,
-    } = context ?? {};
+        projectName = "this project",
+        isMonorepo = false,
+    } = context ?? {};
 
     const safeProjectType = projectType || "unknown";
     const safeSection = (section || "").toLowerCase().trim();
 
-    switch (safeSection) {
-        case "description":
-            return getDescriptionContent(safeProjectType, projectName, isMonorepo);
+    switch (safeSection) {
+        case "description":
+            return getDescriptionContent(safeProjectType, projectName, isMonorepo, descriptionContent);
         case "installation":
             return getInstallationContent(safeProjectType, packages, isMonorepo);
         case "usage":
@@ -35,8 +36,12 @@ export default function getDefaultContent(section, projectType, context = {}) {
     }
 }
 
-function getDescriptionContent(projectType, projectName, isMonorepo) {
-    const name = projectName || "this project";
+function getDescriptionContent(projectType, projectName, isMonorepo, descriptionContent) {
+    if (descriptionContent) {
+        return descriptionContent;
+    }
+
+    const name = projectName || "this project";
     if (projectType === "node") {
         if (isMonorepo) {
             return `${name} is a Node.js monorepo containing multiple packages. Add a brief description of its purpose and what problem it solves.`;