flatten-tool 1.4.0 → 1.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/flatten-tool)](https://www.npmjs.com/package/flatten-tool)
 
-A CLI utility to flatten directory structures.
+A CLI utility to flatten directory structures, with perfect GitHub Flavored Markdown compatibility.
 
 [![asciicast](docs/demo.gif)](https://asciinema.org/a/ThswNC1vrdlK0wdD)
 
@@ -10,13 +10,31 @@ A CLI utility to flatten directory structures.
 
 Requires [Bun](https://bun.sh) runtime (v1.1+).
 
+### Via npm
+
 ```bash
 npm install -g flatten-tool
 ```
 
+### For Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/MBanucu/flatten-tool.git
+cd flatten-tool
+bun install
+```
+
+Run directly with Bun:
+
+```bash
+bun run index.ts [args]
+```
+
 ## Usage
 
-By default, the tool merges all file contents into a single Markdown file, starting with a project file tree for navigation, followed by each file's content under a header with its relative path, in a code block with appropriate language highlighting based on the file extension. Ignores and filters are applied as usual.
+By default, the tool merges all file contents into a single Markdown file, starting with a project file tree for navigation, followed by each file's content under a header with its full relative path, in a code block with appropriate language highlighting based on the file extension. The tree includes clickable links to file sections using GitHub-compatible anchors. Ignores and filters are applied as usual.
 
 The `<source>` argument is optional and defaults to the current directory (`.`). The `<target>` argument is also optional and defaults to `flattened.md` (or `flattened/` when using `--directory`).
 
@@ -113,6 +131,16 @@ This project uses Bun for runtime, TypeScript for type safety, and follows the g
 
 ## Changelog
 
+### v1.6.0
+- Perfect GitHub compatibility: anchors now exactly match GitHub Flavored Markdown auto-generation using github-slugger.
+- Cleaner directory headers: removed trailing `/` for better readability.
+- Precomputed anchors: ensures no mismatches even with slug collisions.
+- Removed unused treeify dependency.
+
+### v1.5.0
+- Improved navigation: project file tree is now a clickable nested Markdown list with links to each file's content section using standard markdown anchors.
+- Simplified file headers: removed custom anchors from section headers.
+
 ### v1.4.0
 - Added project file tree to the beginning of merged Markdown output for better navigation.
 

package/index.ts

@@ -7,7 +7,7 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { globby } from 'globby';
 import pkg from './package.json' assert { type: 'json' };
-import treeify from 'treeify';
+import GithubSlugger from 'github-slugger';
 
 function escapePathComponent(component: string): string {
   return component.replace(/_/g, '__');
@@ -15,54 +15,22 @@ function escapePathComponent(component: string): string {
 
 function buildTreeObject(relPaths: string[]): any {
   const tree: any = {};
-
-  relPaths.forEach((path) => {
-    // Normalize paths
-    path = path.replace(/\\/g, '/');
-    if (path.startsWith('./')) path = path.slice(2);
-
+  for (const path of relPaths) {
     const parts = path.split('/');
     let node = tree;
-
-    parts.forEach((part, index) => {
+    const currentParts: string[] = [];
+    for (const [index, part] of parts.entries()) {
+      currentParts.push(part);
       const isDir = index < parts.length - 1;
       const key = isDir ? `${part}/` : part;
-
-      if (!node[key]) {
-        node[key] = isDir ? {} : null;
+      if (node[key] === undefined) {
+        node[key] = isDir ? {} : currentParts.join('/');
       }
-
       if (isDir) {
         node = node[key];
       }
-    });
-  });
-
-  // Recursively sort: directories first, then files, case-insensitive
-  function sortNode(node: any): void {
-    if (node === null || typeof node !== 'object') return;
-
-    const entries = Object.entries(node);
-    entries.sort(([a], [b]) => {
-      const aIsDir = a.endsWith('/');
-      const bIsDir = b.endsWith('/');
-      if (aIsDir !== bIsDir) return aIsDir ? -1 : 1; // dirs before files
-      return a.toLowerCase().localeCompare(b.toLowerCase());
-    });
-
-    // Rebuild node in sorted order (preserves insertion order for rendering)
-    const sorted: any = {};
-    entries.forEach(([key, value]) => {
-      sorted[key] = value;
-      sortNode(value);
-    });
-
-    Object.keys(node).forEach((k) => delete node[k]);
-    Object.assign(node, sorted);
+    }
   }
-
-  sortNode(tree);
-
   return tree;
 }
 
@@ -127,46 +95,165 @@ export async function flattenDirectory(
       if (err.code !== 'ENOENT') throw err;
     }
 
-    const relPaths: string[] = files.map((srcPath) =>
-      relative(absSource, srcPath).replace(/\\/g, '/')
-    );
-
-    // Sort paths for consistent insertion
-    relPaths.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+    const fileEntries = files.map(srcPath => ({
+      srcPath,
+      relPath: relative(absSource, srcPath).replace(/\\/g, '/')
+    }));
 
+    const relPaths = fileEntries.map(e => e.relPath);
     const treeObj = buildTreeObject(relPaths);
 
-    // Wrap with root for nice "." header (empty dirs show just ".")
-    const rootTree = { '.': treeObj };
+    // Map for quick lookup of srcPath by relPath
+    const pathMap = new Map<string, string>();
+    fileEntries.forEach(({ srcPath, relPath }) => {
+      pathMap.set(relPath, srcPath);
+    });
+
+    // === NEW: Precompute anchors in document order ===
+    interface Section {
+      path: string;
+      headerText: string;
+    }
+
+    const sections: Section[] = [];
+
+    function collectSections(node: any, currentPath: string): void {
+      const dirs: { name: string; child: any }[] = [];
+      const files: { relPath: string }[] = [];
+
+      for (const [key, value] of Object.entries(node) as [string, any][]) {
+        if (key.endsWith('/')) {
+          const name = key.slice(0, -1);
+          dirs.push({ name, child: value });
+        } else {
+          files.push({ relPath: value as string });
+        }
+      }
+
+      dirs.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+      files.sort((a, b) => a.relPath.toLowerCase().localeCompare(b.relPath.toLowerCase()));
+
+      for (const dir of dirs) {
+        const newPath = currentPath ? `${currentPath}/${dir.name}` : dir.name;
+        collectSections(dir.child, newPath);
+      }
+
+      if (currentPath) {
+        sections.push({ path: currentPath, headerText: currentPath }); // no trailing /
+      }
+
+      for (const file of files) {
+        sections.push({ path: file.relPath, headerText: file.relPath });
+      }
+    }
+
+    collectSections(treeObj, '');
+
+    const anchorMap = new Map<string, string>();
+    const anchorSlugger = new GithubSlugger();
+    for (const sec of sections) {
+      anchorMap.set(sec.path, anchorSlugger.slug(sec.headerText));
+    }
+    // === END NEW ===
+
+    // Updated renderMarkdownTree to use precomputed anchors
+    function renderMarkdownTree(
+      node: any,
+      depth: number = 0,
+      prefix: string = '',
+      anchorMap: Map<string, string>
+    ): string {
+      let result = '';
+      const indent = '  '.repeat(depth);
+      const entries: [string, any][] = Object.entries(node);
+
+      entries.sort(([a], [b]) => {
+        const aDir = a.endsWith('/');
+        const bDir = b.endsWith('/');
+        if (aDir !== bDir) return aDir ? -1 : 1;
+        return a.toLowerCase().localeCompare(b.toLowerCase());
+      });
+
+      for (const [key, value] of entries) {
+        const isDir = key.endsWith('/');
+        const name = isDir ? key.slice(0, -1) : key;
+        const display = isDir ? name + '/' : name;
+        const pathHere = prefix ? `${prefix}/${name}` : name;
+        const anchor = anchorMap.get(pathHere) ?? '';
+        result += `${indent}- [${display}](#${anchor})\n`;
+        if (isDir) {
+          result += renderMarkdownTree(value, depth + 1, pathHere, anchorMap);
+        }
+      }
+      return result;
+    }
+
+    // Render global tree with correct anchors
+    let treeMarkdown = "# Project File Tree\n\n- .\n";
+    treeMarkdown += renderMarkdownTree(treeObj, 1, '', anchorMap);
+    treeMarkdown += "\n\n";
 
     const writeStream = createWriteStream(absTarget);
     writeStream.setMaxListeners(0);
+    writeStream.write(treeMarkdown);
+
+    async function writeContentRecursive(
+      node: any,
+      currentPath: string,
+      writeStream: import('node:fs').WriteStream,
+      pathMap: Map<string, string>
+    ): Promise<void> {
+      const dirs: { name: string; child: any }[] = [];
+      const files: { name: string; relPath: string; srcPath: string }[] = [];
+
+      for (const [key, value] of Object.entries(node) as [string, any][]) {
+        if (key.endsWith('/')) {
+          const name = key.slice(0, -1);
+          dirs.push({ name, child: value });
+        } else {
+          const relPath = value as string;
+          const srcPath = pathMap.get(relPath)!;
+          const name = key;
+          files.push({ name, relPath, srcPath });
+        }
+      }
 
-    writeStream.write("# Project File Tree\n\n");
-    writeStream.write("```\n");
-    writeStream.write(treeify.asTree(rootTree));
-    writeStream.write("```\n\n");
+      dirs.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+      files.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
 
-    for (const srcPath of files) {
-      const relPath = relative(absSource, srcPath).replace(/\\/g, '/');
-      let ext = extname(srcPath).slice(1) || 'text';
-      const isMd = ['md', 'markdown'].includes(ext.toLowerCase());
-      const ticks = isMd ? '````' : '```';
+      for (const dir of dirs) {
+        const newPath = currentPath ? `${currentPath}/${dir.name}` : dir.name;
+        await writeContentRecursive(dir.child, newPath, writeStream, pathMap);
+      }
+
+      // Directory section (only for non-root) — no trailing /
+      if (currentPath) {
+        writeStream.write(`# ${currentPath}\n\n`);
+        writeStream.write(`File Tree\n\n`);
+        writeStream.write(`- .\n`);
+        writeStream.write(renderMarkdownTree(node, 1, currentPath, anchorMap));
+        writeStream.write('\n');
+      }
 
-      // Write header synchronously
-      writeStream.write(`# ${relPath}\n\n${ticks}${ext}\n`);
+      for (const file of files) {
+        writeStream.write(`# ${file.relPath}\n\n`);
 
-      // Stream file content (preserve original UTF-8 text behavior)
-      const readStream = createReadStream(srcPath, { encoding: 'utf8' });
+        let ext = extname(file.srcPath).slice(1) || 'text';
+        const lang = ext;
+        const isMd = ['md', 'markdown'].includes(ext.toLowerCase());
+        const ticks = isMd ? '````' : '```';
 
-      // Pipe with { end: false } so writeStream stays open for next files
-      await pipeline(readStream, writeStream, { end: false });
+        writeStream.write(`${ticks}${lang}\n`);
 
-      // Write closing fence
-      writeStream.write(`\n${ticks}\n\n`);
+        const readStream = createReadStream(file.srcPath, { encoding: 'utf8' });
+        await pipeline(readStream, writeStream, { end: false });
+
+        writeStream.write(`\n${ticks}\n\n`);
+      }
     }
 
-    // Close the output file and wait for it to finish
+    await writeContentRecursive(treeObj, '', writeStream, pathMap);
+
     writeStream.end();
     await finished(writeStream);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flatten-tool",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "CLI tool to flatten directory structures: merge files into a single Markdown file (default) or copy/move to a flat directory with escaped filenames. Respects .gitignore, supports move/overwrite, and more.",
   "module": "index.ts",
   "type": "module",
@@ -46,10 +46,10 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "github-slugger": "^2.0.0",
     "globby": "^16.1.0",
     "ignore": "^7.0.5",
     "minimatch": "^10.1.2",
-    "treeify": "^1.1.0",
     "yargs": "^18.0.0"
   }
 }