flatten-tool 1.5.0 → 1.6.1

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,40 @@ A CLI utility to flatten directory structures.
 
 Requires [Bun](https://bun.sh) runtime (v1.1+).
 
+### Via npm
+
 ```bash
 npm install -g flatten-tool
 ```
 
+### Run without installation
+
+You can run flatten-tool directly without installing:
+
+```bash
+npx flatten-tool [args]
+bunx flatten-tool [args]
+```
+
+### 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 +140,15 @@ This project uses Bun for runtime, TypeScript for type safety, and follows the g
 
 ## Changelog
 
+### v1.6.1
+- Added instructions for running flatten-tool directly with npx and bunx.
+
+### 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.

package/index.ts

@@ -7,19 +7,12 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { globby } from 'globby';
 import pkg from './package.json' assert { type: 'json' };
+import GithubSlugger from 'github-slugger';
 
 function escapePathComponent(component: string): string {
   return component.replace(/_/g, '__');
 }
 
-function generateMarkdownAnchor(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '') // Remove punctuation except hyphens and underscores
-    .replace(/\s+/g, '-') // Replace spaces with hyphens
-    .replace(/^-+|-+$/g, ''); // Remove leading/trailing hyphens
-}
-
 function buildTreeObject(relPaths: string[]): any {
   const tree: any = {};
   for (const path of relPaths) {
@@ -41,33 +34,6 @@ function buildTreeObject(relPaths: string[]): any {
   return tree;
 }
 
-function renderMarkdownTree(node: any, depth: number): 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 display = isDir ? key.slice(0, -1) + '/' : key;
-    if (isDir) {
-      result += `${indent}- ${display}\n`;
-      result += renderMarkdownTree(value, depth + 1);
-    } else {
-      const fullPath = value as string;
-      const anchor = generateMarkdownAnchor(fullPath);
-      result += `${indent}- [${display}](#${anchor})\n`;
-    }
-  }
-  return result;
-}
-
 async function removeEmptyDirs(dir: string, root?: string): Promise<void> {
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -129,44 +95,165 @@ export async function flattenDirectory(
       if (err.code !== 'ENOENT') throw err;
     }
 
-    // Sort files for consistent content order
     const fileEntries = files.map(srcPath => ({
       srcPath,
       relPath: relative(absSource, srcPath).replace(/\\/g, '/')
     }));
-    fileEntries.sort((a, b) => a.relPath.toLowerCase().localeCompare(b.relPath.toLowerCase()));
 
     const relPaths = fileEntries.map(e => e.relPath);
-
-    // Build tree structure
     const treeObj = buildTreeObject(relPaths);
 
-    // Render as clickable nested Markdown list
+    // 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);
-    treeMarkdown += "\n";
+    treeMarkdown += renderMarkdownTree(treeObj, 1, '', anchorMap);
+    treeMarkdown += "\n\n";
 
     const writeStream = createWriteStream(absTarget);
     writeStream.setMaxListeners(0);
-
     writeStream.write(treeMarkdown);
 
-    // Write file contents (now in sorted order)
-    for (const { srcPath, relPath } of fileEntries) {
-      let ext = extname(srcPath).slice(1) || 'text';
-      const lang = ext;
-      const isMd = ['md', 'markdown'].includes(ext.toLowerCase());
-      const ticks = isMd ? '````' : '```';
+    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 });
+        }
+      }
+
+      dirs.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+      files.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
 
-      writeStream.write(`## ${relPath}\n\n${ticks}${lang}\n`);
+      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');
+      }
 
-      const readStream = createReadStream(srcPath, { encoding: 'utf8' });
-      await pipeline(readStream, writeStream, { end: false });
+      for (const file of files) {
+        writeStream.write(`# ${file.relPath}\n\n`);
 
-      writeStream.write(`\n${ticks}\n\n`);
+        let ext = extname(file.srcPath).slice(1) || 'text';
+        const lang = ext;
+        const isMd = ['md', 'markdown'].includes(ext.toLowerCase());
+        const ticks = isMd ? '````' : '```';
+
+        writeStream.write(`${ticks}${lang}\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.5.0",
+  "version": "1.6.1",
   "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"
   }
 }