🔍 Project Root

A TypeScript library that automatically detects project root directories by analyzing file patterns and project indicators.

🎯 What it does

This library scans file system paths to find the root directory of software projects. It looks for common project files like package.json, tsconfig.json, go.mod, and many others to determine where a project actually begins.

📦 Installation

npm install @neabyte/project-root

🚀 Basic Usage

🔎 Find Project Root

import { findProjectRoot } from '@neabyte/project-root'

// Find the project root from a file path
const projectRoot = findProjectRoot('/path/to/some/file.ts')
console.log(projectRoot) // '/path/to/project/root'

🌳 Deep Project Discovery

import { findProjectDeep } from '@neabyte/project-root'

// Find all projects in a directory tree
const projects = findProjectDeep('/path/to/directory', 5, false)
console.log(projects)
// [
//   { path: '/path/to/directory/project1', score: 45, depth: 0, relativePath: '.' },
//   { path: '/path/to/directory/project2', score: 32, depth: 1, relativePath: 'subfolder' }
// ]

📚 API Reference

findProjectRoot(startPath: string): string | null

Searches upward from the given path to find the project root.

Parameters:

• startPath - The file system path to begin searching from

Returns:

• The absolute path of the project root, or null if none found

findProjectDeep(startPath: string, maxDepth?: number, includeSubdirectories?: boolean): ProjectDiscovery[]

Recursively scans a directory tree to find all project roots.

Parameters:

• startPath - The root directory to begin scanning
• maxDepth - Maximum depth to scan (default: 10, use -1 for unlimited)
• includeSubdirectories - Whether to include subdirectories of found projects (default: false)

Returns:

• Array of discovered projects with metadata

🛠️ Supported Project Types

The library detects projects based on common configuration files and patterns:

💻 Languages

• JavaScript/TypeScript: package.json, tsconfig.json, yarn.lock
• Go: go.mod, go.sum
• Rust: Cargo.toml, Cargo.lock
• Java: pom.xml, build.gradle
• Python: pyproject.toml, requirements.txt
• PHP: composer.json, composer.lock
• Ruby: Gemfile, Gemfile.lock
• Dart/Flutter: pubspec.yaml, pubspec.lock
• Swift: Package.swift
• Elixir: mix.exs, mix.lock
• Clojure: project.clj, deps.edn
• Haskell: stack.yaml, package.yaml
• Julia: Project.toml, Manifest.toml
• Crystal: shard.yml, shard.lock
• Lua: rockspec, luarocks.lock

🔨 Build Systems

• CMake: CMakeLists.txt
• Make: Makefile
• Zig: build.zig
• D: dub.json, dub.sdl
• V: v.mod, vpkg.json
• Scala: build.sbt
• OCaml: dune-project, opam
• Erlang: rebar.config, erlang.mk

📋 Version Control

• Git: .git/
• Mercurial: .hg/
• Subversion: .svn/
• Bazaar: .bzr/
• Fossil: .fossil
• Perforce: .p4config
• Darcs: _darcs/
• Monotone: _MTN/
• Jujutsu: .jj/
• Pijul: .pijul/

🛠️ IDE and Tools

• VSCode: .vscode/, *.code-workspace
• Webpack: webpack.config.js
• Vite: vite.config.js
• Rollup: rollup.config.js
• Babel: babel.config.js
• Jest: jest.config.js

⚙️ How it works

The library uses a scoring system to determine project roots:

1. Scans directories for known project indicator files
2. Calculates confidence scores based on found indicators
3. Filters out common directories like node_modules, dist, build
4. Returns the highest scoring directory as the project root

Each indicator has a different score weight. For example:

• package.json has a score of 20
• yarn.lock has a score of 60
• .git/ has a score of 25

🚫 Excluded Directories

The library automatically excludes common build and cache directories:

• node_modules/, vendor/, bower_components/
• target/, build/, dist/, out/, bin/, obj/
• .idea/, .vs/, .cache/, .npm/, .yarn/
• coverage/, .nyc_output/, .jest/
• __pycache__/, .pytest_cache/
• tmp/, temp/, .tmp/, .temp/
• logs/, log/
• And many more...

📝 TypeScript Support

The library is written in TypeScript and provides full type definitions:

interface ProjectDiscovery {
  path: string
  score: number
  depth: number
  relativePath: string
}

interface BestMatch {
  path: string
  score: number
}

interface Indicator extends BestMatch {
  name: string
}

📄 License

This project is licensed under the MIT license. See the LICENSE file for more info.