combicode 1.3.0 → 1.5.1

package/CHANGELOG.md

@@ -1,35 +1,45 @@
 # Changelog
 
-## [1.3.0](https://github.com/aaurelions/combicode/compare/combicode-js-v1.2.1...combicode-js-v1.3.0) (2025-06-25)
+## [1.5.0](https://github.com/aaurelions/combicode/compare/combicode-js-v1.4.0...combicode-js-v1.5.0) (2025-11-30)
+
+### Features
 
+- **tree:** display file sizes in the generated file tree (e.g., `[1.2KB]`)
+- **output:** improve file header format (`### **FILE:**`) for better LLM parsing
+- **tests:** add integration test suite using native Node.js modules
+
+## [1.4.0](https://github.com/aaurelions/combicode/compare/combicode-js-v1.3.0...combicode-js-v1.4.0) (2025-08-13)
 
 ### Features
 
-* Add package-lock.json for reproducible builds ([06a417a](https://github.com/aaurelions/combicode/commit/06a417a155e9b72e26d0e091d181cfb8c53f0d28))
-* **ci:** implement independent package versioning for monorepo ([d02cf23](https://github.com/aaurelions/combicode/commit/d02cf233239c7af8db19061f34b769178334b388))
-* improve CLI output and version reporting ([7963a10](https://github.com/aaurelions/combicode/commit/7963a10782c2626608750de53023d37d327d51b2))
-* improve CLI output and version reporting ([e74f6d8](https://github.com/aaurelions/combicode/commit/e74f6d8fbed4f9cdf8ad82f3dae87069f66f7bb6))
+- Add --llms-txt flag for llms.txt documentation context ([0817554](https://github.com/aaurelions/combicode/commit/081755435594b0ca5208609b2724eb47bd73c2dc))
+
+## [1.3.0](https://github.com/aaurelions/combicode/compare/combicode-js-v1.2.1...combicode-js-v1.3.0) (2025-06-25)
+
+### Features
 
+- Add package-lock.json for reproducible builds ([06a417a](https://github.com/aaurelions/combicode/commit/06a417a155e9b72e26d0e091d181cfb8c53f0d28))
+- **ci:** implement independent package versioning for monorepo ([d02cf23](https://github.com/aaurelions/combicode/commit/d02cf233239c7af8db19061f34b769178334b388))
+- improve CLI output and version reporting ([7963a10](https://github.com/aaurelions/combicode/commit/7963a10782c2626608750de53023d37d327d51b2))
+- improve CLI output and version reporting ([e74f6d8](https://github.com/aaurelions/combicode/commit/e74f6d8fbed4f9cdf8ad82f3dae87069f66f7bb6))
 
 ### Bug Fixes
 
-* **ci:** permission error ([156b76d](https://github.com/aaurelions/combicode/commit/156b76d3ab1550123df2ded6b1da5d6e2e2cc008))
-* **npm:** Set public access for publishing and bump version to 1.0.1 ([6c91eb7](https://github.com/aaurelions/combicode/commit/6c91eb714c81ec0201bb0fcfad8ad9fb4124cd7e))
-* Use scoped npm package name and bump python version ([8a1b347](https://github.com/aaurelions/combicode/commit/8a1b347f6c54c9762acf354ef289c293d3ef21a3))
+- **ci:** permission error ([156b76d](https://github.com/aaurelions/combicode/commit/156b76d3ab1550123df2ded6b1da5d6e2e2cc008))
+- **npm:** Set public access for publishing and bump version to 1.0.1 ([6c91eb7](https://github.com/aaurelions/combicode/commit/6c91eb714c81ec0201bb0fcfad8ad9fb4124cd7e))
+- Use scoped npm package name and bump python version ([8a1b347](https://github.com/aaurelions/combicode/commit/8a1b347f6c54c9762acf354ef289c293d3ef21a3))
 
 ## [1.2.0](https://github.com/aaurelions/combicode/compare/combicode-js-v1.1.0...combicode-js-v1.2.0) (2025-06-25)
 
-
 ### Features
 
-* Add package-lock.json for reproducible builds ([06a417a](https://github.com/aaurelions/combicode/commit/06a417a155e9b72e26d0e091d181cfb8c53f0d28))
-* **ci:** implement independent package versioning for monorepo ([d02cf23](https://github.com/aaurelions/combicode/commit/d02cf233239c7af8db19061f34b769178334b388))
-* improve CLI output and version reporting ([7963a10](https://github.com/aaurelions/combicode/commit/7963a10782c2626608750de53023d37d327d51b2))
-* improve CLI output and version reporting ([e74f6d8](https://github.com/aaurelions/combicode/commit/e74f6d8fbed4f9cdf8ad82f3dae87069f66f7bb6))
-
+- Add package-lock.json for reproducible builds ([06a417a](https://github.com/aaurelions/combicode/commit/06a417a155e9b72e26d0e091d181cfb8c53f0d28))
+- **ci:** implement independent package versioning for monorepo ([d02cf23](https://github.com/aaurelions/combicode/commit/d02cf233239c7af8db19061f34b769178334b388))
+- improve CLI output and version reporting ([7963a10](https://github.com/aaurelions/combicode/commit/7963a10782c2626608750de53023d37d327d51b2))
+- improve CLI output and version reporting ([e74f6d8](https://github.com/aaurelions/combicode/commit/e74f6d8fbed4f9cdf8ad82f3dae87069f66f7bb6))
 
 ### Bug Fixes
 
-* **ci:** permission error ([156b76d](https://github.com/aaurelions/combicode/commit/156b76d3ab1550123df2ded6b1da5d6e2e2cc008))
-* **npm:** Set public access for publishing and bump version to 1.0.1 ([6c91eb7](https://github.com/aaurelions/combicode/commit/6c91eb714c81ec0201bb0fcfad8ad9fb4124cd7e))
-* Use scoped npm package name and bump python version ([8a1b347](https://github.com/aaurelions/combicode/commit/8a1b347f6c54c9762acf354ef289c293d3ef21a3))
+- **ci:** permission error ([156b76d](https://github.com/aaurelions/combicode/commit/156b76d3ab1550123df2ded6b1da5d6e2e2cc008))
+- **npm:** Set public access for publishing and bump version to 1.0.1 ([6c91eb7](https://github.com/aaurelions/combicode/commit/6c91eb714c81ec0201bb0fcfad8ad9fb4124cd7e))
+- Use scoped npm package name and bump python version ([8a1b347](https://github.com/aaurelions/combicode/commit/8a1b347f6c54c9762acf354ef289c293d3ef21a3))

package/README.md

@@ -80,18 +80,28 @@ Use the `--exclude` or `-e` flag with comma-separated glob patterns.
 npx combicode -e "**/*_test.py,docs/**"
 ```
 
+### Generating Context for `llms.txt`
+
+The `--llms.txt` or `-l` flag is designed for projects that use an [`llms.txt`](https://llmstxt.org/) file to specify important documentation. When this flag is used, Combicode inserts a specialized system prompt telling the LLM that the provided context is the project's definitive documentation for a specific version. This helps the LLM provide more accurate answers and avoid using deprecated functions.
+
+```bash
+# Combine all markdown files for an llms.txt context
+npx combicode -l -i .md -o llms.txt
+```
+
 ## All CLI Options
 
-| Option           | Alias | Description                                                  | Default         |
-| ---------------- | ----- | ------------------------------------------------------------ | --------------- |
-| `--output`       | `-o`  | The name of the output file.                                 | `combicode.txt` |
-| `--dry-run`      | `-d`  | Preview files without creating the output file.              | `false`         |
-| `--include-ext`  | `-i`  | Comma-separated list of extensions to exclusively include.   | (include all)   |
-| `--exclude`      | `-e`  | Comma-separated list of additional glob patterns to exclude. | (none)          |
-| `--no-gitignore` |       | Do not use patterns from the project's `.gitignore` file.    | `false`         |
-| `--no-header`    |       | Omit the introductory prompt and file tree from the output.  | `false`         |
-| `--version`      | `-v`  | Show the version number.                                     |                 |
-| `--help`         | `-h`  | Show the help message.                                       |                 |
+| Option           | Alias | Description                                                                    | Default         |
+| ---------------- | ----- | ------------------------------------------------------------------------------ | --------------- |
+| `--output`       | `-o`  | The name of the output file.                                                   | `combicode.txt` |
+| `--dry-run`      | `-d`  | Preview files without creating the output file.                                | `false`         |
+| `--include-ext`  | `-i`  | Comma-separated list of extensions to exclusively include.                     | (include all)   |
+| `--exclude`      | `-e`  | Comma-separated list of additional glob patterns to exclude.                   | (none)          |
+| `--llms-txt`     | `-l`  | Use a specialized system prompt for context generated from an `llms.txt` file. | `false`         |
+| `--no-gitignore` |       | Do not use patterns from the project's `.gitignore` file.                      | `false`         |
+| `--no-header`    |       | Omit the introductory prompt and file tree from the output.                    | `false`         |
+| `--version`      | `-v`  | Show the version number.                                                       |                 |
+| `--help`         | `-h`  | Show the help message.                                                         |                 |
 
 ## License
 

package/index.js

@@ -8,15 +8,22 @@ const glob = require("fast-glob");
 
 const { version } = require("./package.json");
 
-const SYSTEM_PROMPT = `You are an expert software architect. The user is providing you with the complete source code for a project, contained in a single file. Your task is to meticulously analyze the provided codebase to gain a comprehensive understanding of its structure, functionality, dependencies, and overall architecture.
+const DEFAULT_SYSTEM_PROMPT = `You are an expert software architect. The user is providing you with the complete source code for a project, contained in a single file. Your task is to meticulously analyze the provided codebase to gain a comprehensive understanding of its structure, functionality, dependencies, and overall architecture.
 
-A file tree is provided below to give you a high-level overview. The subsequent sections contain the full content of each file, clearly marked with "// FILE: <path>".
+A file tree is provided below to give you a high-level overview. The subsequent sections contain the full content of each file, clearly marked with a file header.
 
 Your instructions are:
 1.  **Analyze Thoroughly:** Read through every file to understand its purpose and how it interacts with other files.
 2.  **Identify Key Components:** Pay close attention to configuration files (like package.json, pyproject.toml), entry points (like index.js, main.py), and core logic.
 `;
 
+const LLMS_TXT_SYSTEM_PROMPT = `You are an expert software architect. The user is providing you with the full documentation for a project, sourced from the project's 'llms.txt' file. This file contains the complete context needed to understand the project's features, APIs, and usage for a specific version. Your task is to act as a definitive source of truth based *only* on this provided documentation.
+
+When answering questions or writing code, adhere strictly to the functions, variables, and methods described in this context. Do not use or suggest any deprecated or older functionalities that are not present here.
+
+A file tree of the documentation source is provided below for a high-level overview. The subsequent sections contain the full content of each file, clearly marked with a file header.
+`;
+
 function loadDefaultIgnorePatterns() {
   const configPath = path.resolve(__dirname, "config", "ignore.json");
   try {
@@ -46,18 +53,33 @@ function isLikelyBinary(file) {
   }
 }
 
-function generateFileTree(files, root) {
+function formatBytes(bytes, decimals = 1) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + "" + sizes[i];
+}
+
+function generateFileTree(filesWithSize, root) {
   let tree = `${path.basename(root)}/\n`;
   const structure = {};
 
-  files.forEach((file) => {
-    const parts = file.split(path.sep);
+  // Build the structure
+  filesWithSize.forEach(({ relativePath, formattedSize }) => {
+    const parts = relativePath.split(path.sep);
     let currentLevel = structure;
-    parts.forEach((part) => {
-      if (!currentLevel[part]) {
-        currentLevel[part] = {};
+    parts.forEach((part, index) => {
+      const isFile = index === parts.length - 1;
+      if (isFile) {
+        currentLevel[part] = formattedSize;
+      } else {
+        if (!currentLevel[part]) {
+          currentLevel[part] = {};
+        }
+        currentLevel = currentLevel[part];
       }
-      currentLevel = currentLevel[part];
     });
   });
 
@@ -65,9 +87,16 @@ function generateFileTree(files, root) {
     const entries = Object.keys(level);
     entries.forEach((entry, index) => {
       const isLast = index === entries.length - 1;
-      tree += `${prefix}${isLast ? "└── " : "├── "}${entry}\n`;
-      if (Object.keys(level[entry]).length > 0) {
-        buildTree(level[entry], `${prefix}${isLast ? "    " : "│   "}`);
+      const value = level[entry];
+      const isFile = typeof value === "string";
+
+      const connector = isLast ? "└── " : "├── ";
+
+      if (isFile) {
+        tree += `${prefix}${connector}[${value}] ${entry}\n`;
+      } else {
+        tree += `${prefix}${connector}${entry}\n`;
+        buildTree(value, `${prefix}${isLast ? "    " : "│   "}`);
       }
     });
   };
@@ -83,6 +112,7 @@ async function main() {
     process.exit(0);
   }
 
+  // Yargs singleton usage works correctly with arguments passed here
   const argv = yargs(rawArgv)
     .scriptName("combicode")
     .usage("$0 [options]")
@@ -108,6 +138,12 @@ async function main() {
       describe: "Comma-separated glob patterns to exclude",
       type: "string",
     })
+    .option("l", {
+      alias: "llms-txt",
+      describe: "Use the system prompt for llms.txt context",
+      type: "boolean",
+      default: false,
+    })
     .option("no-gitignore", {
       describe: "Ignore the project's .gitignore file",
       type: "boolean",
@@ -150,7 +186,7 @@ async function main() {
     dot: true,
     ignore: ignorePatterns,
     absolute: true,
-    stats: false,
+    stats: true,
   });
 
   const allowedExtensions = argv.includeExt
@@ -162,28 +198,30 @@ async function main() {
     : null;
 
   const includedFiles = allFiles
-    .filter((file) => {
-      const stats = fs.statSync(file, { throwIfNoEntry: false });
-      if (!stats || stats.isDirectory()) return false;
+    .filter((fileObj) => {
+      const file = fileObj.path;
+      if (!fileObj.stats || fileObj.stats.isDirectory()) return false;
       if (isLikelyBinary(file)) return false;
       if (allowedExtensions && !allowedExtensions.has(path.extname(file)))
         return false;
       return true;
     })
-    .sort();
+    .map((fileObj) => ({
+      path: fileObj.path,
+      relativePath: path.relative(projectRoot, fileObj.path),
+      size: fileObj.stats.size,
+      formattedSize: formatBytes(fileObj.stats.size),
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
 
   if (includedFiles.length === 0) {
     console.error("❌ No files to include. Check your path or filters.");
     process.exit(1);
   }
 
-  const relativeFiles = includedFiles.map((file) =>
-    path.relative(projectRoot, file)
-  );
-
   if (argv.dryRun) {
     console.log("\n📋 Files to be included (Dry Run):\n");
-    const tree = generateFileTree(relativeFiles, projectRoot);
+    const tree = generateFileTree(includedFiles, projectRoot);
     console.log(tree);
     console.log(`\nTotal: ${includedFiles.length} files.`);
     return;
@@ -192,21 +230,24 @@ async function main() {
   const outputStream = fs.createWriteStream(argv.output);
 
   if (!argv.noHeader) {
-    outputStream.write(SYSTEM_PROMPT + "\n");
+    const systemPrompt = argv.llmsTxt
+      ? LLMS_TXT_SYSTEM_PROMPT
+      : DEFAULT_SYSTEM_PROMPT;
+    outputStream.write(systemPrompt + "\n");
     outputStream.write("## Project File Tree\n\n");
     outputStream.write("```\n");
-    const tree = generateFileTree(relativeFiles, projectRoot);
+    const tree = generateFileTree(includedFiles, projectRoot);
     outputStream.write(tree);
     outputStream.write("```\n\n");
     outputStream.write("---\n\n");
   }
 
-  for (const file of includedFiles) {
-    const relativePath = path.relative(projectRoot, file).replace(/\\/g, "/");
-    outputStream.write(`// FILE: ${relativePath}` + "\n");
+  for (const fileObj of includedFiles) {
+    const relativePath = fileObj.relativePath.replace(/\\/g, "/");
+    outputStream.write(`### **FILE:** \`${relativePath}\`\n`);
     outputStream.write("```\n");
     try {
-      const content = fs.readFileSync(file, "utf8");
+      const content = fs.readFileSync(fileObj.path, "utf8");
       outputStream.write(content);
     } catch (e) {
       outputStream.write(`... (error reading file: ${e.message}) ...`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "combicode",
-  "version": "1.3.0",
+  "version": "1.5.1",
   "description": "A CLI tool to combine a project's codebase into a single file for LLM context.",
   "main": "index.js",
   "bin": {
@@ -10,7 +10,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "pretest": "mkdir -p config && cp ../configs/ignore.json config/ignore.json",
+    "test": "node test/test.js"
   },
   "repository": {
     "type": "git",
@@ -24,12 +25,15 @@
     "prompt",
     "developer-tool",
     "codegen",
-    "chatgpt"
+    "chatgpt",
+    "llms.txt",
+    "llms",
+    "llms-full.txt"
   ],
   "author": "A. Aurelions",
   "license": "MIT",
   "dependencies": {
-    "fast-glob": "^3.3.1",
+    "fast-glob": "^3.3.3",
     "yargs": "^17.7.2"
   }
 }

package/test/test.js

@@ -0,0 +1,90 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const assert = require("assert");
+
+const CLI_PATH = path.resolve(__dirname, "../index.js");
+const TEST_DIR = path.resolve(__dirname, "temp_env");
+const OUTPUT_FILE = path.join(TEST_DIR, "combicode.txt");
+
+// Setup: Create a temp directory with dummy files
+function setup() {
+  if (fs.existsSync(TEST_DIR)) {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DIR);
+
+  // Create a dummy JS file
+  fs.writeFileSync(path.join(TEST_DIR, "alpha.js"), "console.log('alpha');");
+
+  // Create a dummy text file in a subdir
+  const subDir = path.join(TEST_DIR, "subdir");
+  fs.mkdirSync(subDir);
+  fs.writeFileSync(path.join(subDir, "beta.txt"), "Hello World");
+}
+
+// Teardown: Cleanup temp directory
+function teardown() {
+  if (fs.existsSync(TEST_DIR)) {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+}
+
+function runTest() {
+  console.log("🧪 Starting Node.js Integration Tests...");
+
+  try {
+    setup();
+
+    // 1. Test Version Flag
+    console.log("   Checking --version...");
+    const versionOutput = execSync(`node ${CLI_PATH} --version`).toString();
+    assert.match(versionOutput, /Combicode \(JavaScript\), version/);
+
+    // 2. Test Dry Run
+    console.log("   Checking --dry-run...");
+    const dryRunOutput = execSync(`node ${CLI_PATH} --dry-run`, {
+      cwd: TEST_DIR,
+    }).toString();
+    assert.match(dryRunOutput, /Files to be included \(Dry Run\)/);
+    // Check for file size format in tree (e.g., [21B])
+    assert.match(dryRunOutput, /\[\d+(\.\d+)?[KM]?B\]/);
+
+    // 3. Test Actual Generation
+    console.log("   Checking file generation...");
+    execSync(`node ${CLI_PATH} --output combicode.txt`, { cwd: TEST_DIR });
+
+    assert.ok(fs.existsSync(OUTPUT_FILE), "Output file should exist");
+
+    const content = fs.readFileSync(OUTPUT_FILE, "utf8");
+
+    // Check for System Prompt
+    assert.ok(
+      content.includes("You are an expert software architect"),
+      "System prompt missing"
+    );
+
+    // Check for Tree structure
+    assert.ok(content.includes("subdir"), "Tree should show subdirectory");
+
+    // Check for new Header format
+    assert.ok(
+      content.includes("### **FILE:** `alpha.js`"),
+      "New header format missing for alpha.js"
+    );
+    assert.ok(
+      content.includes("### **FILE:** `subdir/beta.txt`"),
+      "New header format missing for beta.txt"
+    );
+
+    console.log("✅ All Node.js tests passed!");
+  } catch (error) {
+    console.error("❌ Test Failed:", error.message);
+    if (error.stdout) console.log(error.stdout.toString());
+    process.exit(1);
+  } finally {
+    teardown();
+  }
+}
+
+runTest();

package/config/ignore.json

@@ -1,53 +0,0 @@
-[
-  "**/node_modules/**",
-  "**/.git/**",
-  "**/.vscode/**",
-  "**/.idea/**",
-  "**/*.log",
-  "**/.env",
-  "**/*.lock",
-  "**/.venv/**",
-  "**/venv/**",
-  "**/env/**",
-  "**/__pycache__/**",
-  "**/*.pyc",
-  "**/*.egg-info/**",
-  "**/build/**",
-  "**/dist/**",
-  "**/.pytest_cache/**",
-  "**/.npm/**",
-  "**/pnpm-lock.yaml",
-  "**/package-lock.json",
-  "**/.next/**",
-  "**/.DS_Store",
-  "**/Thumbs.db",
-  "**/*.png",
-  "**/*.jpg",
-  "**/*.jpeg",
-  "**/*.gif",
-  "**/*.ico",
-  "**/*.svg",
-  "**/*.webp",
-  "**/*.mp3",
-  "**/*.wav",
-  "**/*.flac",
-  "**/*.mp4",
-  "**/*.mov",
-  "**/*.avi",
-  "**/*.zip",
-  "**/*.tar.gz",
-  "**/*.rar",
-  "**/*.pdf",
-  "**/*.doc",
-  "**/*.docx",
-  "**/*.xls",
-  "**/*.xlsx",
-  "**/*.dll",
-  "**/*.exe",
-  "**/*.so",
-  "**/*.a",
-  "**/*.lib",
-  "**/*.o",
-  "**/*.bin",
-  "**/*.iso"
-]