@hyperfrontend/project-scope§

_{Four repositories read without being installed, built or run: the number beside each detection is what lets a tool decide whether to act on it or ask.}

Comprehensive project analysis, technology stack detection, and transactional virtual file system for Node.js tooling.

What is @hyperfrontend/project-scope?

@hyperfrontend/project-scope provides intelligent codebase analysis for JavaScript/TypeScript projects. It uses multi-signal heuristics to classify project types, detect frameworks and build tools, discover entry points, and map dependency graphs - all with confidence scoring and explainable evidence. The library also includes a virtual file system (VFS) for safe, atomic file modifications.

Designed for tooling authors building code generators, IDE extensions, CI/CD pipelines, and monorepo tooling. Built-in NX workspace detection reads nx.json, workspace.json, and project.json so tooling can adapt to NX-shaped repos with zero runtime peer dependencies.

Key Features

Why Use @hyperfrontend/project-scope?

Accurate Framework Detection for Code Generators

Simple package.json parsing misses meta-frameworks, optional dependencies, and configuration-based setups. A project with next installed might be Next.js, but could also be a library that exports Next.js components. This library's multi-signal heuristics analyze dependencies, directory structure (pages/, app/), and config files (next.config.js) together, returning confidence-scored results. Your generator knows with certainty whether to scaffold Next.js pages or React components.

Safe File Modifications with Rollback

Code generators that write directly to disk risk leaving projects in broken states when errors occur mid-generation. The VFS buffers all changes in memory - write 50 files, validate the result, then commitChanges() atomically or rollbackChanges() to discard everything. Path traversal attacks are blocked at the VFS layer, making generators safe to run on untrusted input.

Adaptive Tooling in Heterogeneous Monorepos

Monorepos contain React apps, Vue libraries, Node.js services, and Cypress suites - each requiring different lint rules, build configs, and CI pipelines. Use detectAll() per project to get technology detection with version info, then conditionally apply configurations. Cached results (30-60s TTL) ensure repeated analysis during builds stays fast.

IDE Extensions Without Manual Configuration

IDE features that adapt to frameworks typically require users to configure their project type manually. This library provides runtime detection - determine React vs Vue for component snippets, identify Jest vs Vitest for test runners, detect Vite vs Webpack for build task integration. The CLI enables integration with shell-based tooling and editor extensions.

Migration Planning with Evidence

Modernizing legacy codebases requires understanding current technology stack before planning migrations. analyzeProject() detects legacy frameworks (jQuery, AngularJS, Backbone), maps internal dependency graphs, and provides confidence-scored evidence for each detection. Generate reports that explain why each technology was detected, enabling data-driven migration decisions.

Installation

npm install @hyperfrontend/project-scope

Requirements

• Node.js: 18.0.0 or higher
• npm: 8.0.0 or higher

Note: This library is designed for Node.js environments only (no browser support). All file system operations use synchronous Node.js APIs.

Quick Start

Project Analysis

import { analyzeProject, detectAll } from '@hyperfrontend/project-scope'

// Full project analysis
const analysis = analyzeProject('./my-project')
console.log(analysis.projectType) // 'library' | 'application' | 'e2e' | 'tool'
console.log(analysis.frameworks.map((f) => `${f.name} (${f.confidence}%)`))

// Technology stack detection
const tech = detectAll('./my-project')
console.log(
  'Frontend:',
  tech.frontendFrameworks.map((f) => f.name)
)
console.log(
  'Build:',
  tech.buildTools.map((t) => t.name)
)
console.log(
  'Testing:',
  tech.testingFrameworks.map((t) => t.name)
)

Virtual File System

import { createTree, commitChanges, rollbackChanges } from '@hyperfrontend/project-scope'

const tree = createTree('./my-project')

tree.write('src/new-file.ts', 'export const hello = "world"')
tree.rename('src/old.ts', 'src/renamed.ts')
tree.delete('src/deprecated.ts')

commitChanges(tree) // Atomic commit, or rollbackChanges(tree) to discard

CLI

The package declares no bin, so nothing is installed onto your PATH. The commands are reached by calling run() with the argument list yourself, from a script or from your own tool's binary:

import { run } from '@hyperfrontend/project-scope'

run(['analyze', './my-project', '--format', 'json'])
run(['config', './my-project', '--type', 'typescript,eslint'])

const result = run(['tree', './my-project', '--depth', '3'])
process.exit(result.exitCode)

API Overview

The surface answers three questions about a directory on disk, and which one you are asking decides what you reach for.

What is this repository? analyzeProject(dir) answers the whole question in one call and returns an AnalysisResult: project type, workspace type, frameworks, build tools, testing frameworks, entry points, config files and a dependency summary, all in one object. Nothing is installed, built or executed to produce it.

Each detection carries a confidence from 0 to 100 and the evidence that earned it, and that number is the useful part: a repository with a Svelte dependency but no SvelteKit routing scores SvelteKit at 20, which is the signal a tool needs to ask rather than assume. When the whole report is more than you want, detectProjectType classifies the project alone and detectAll runs only the technology detectors. Results are memoised for 30 to 60 seconds, so a loop over a monorepo does not re-read the same package twice.

Where are its pieces? discoverEntryPoints works out what the project actually starts from, reading exports, main and bin off the manifest and scoring convention and framework paths beside them, and buildDependencyGraph follows first-party imports through the source to a graph with its roots and leaves marked. Root and workspace finders walk upwards from any nested path, so a tool handed one file can still locate the repository it belongs to.

How do I change it safely? createTree(dir) returns a Tree that buffers every write, delete, rename and permission change in memory; exists() and read() see those pending changes, so the tree reads as though the edits had already landed. Committing is a free function rather than a method: commitChanges(tree) applies the batch to disk and reports what it did, commitChanges(tree, { dryRun: true }) reports the same without touching anything, and rollbackChanges(tree) discards it. Paths that escape the root are rejected before any of that.

Subpath imports narrow the surface rather than adding to it. /heuristics is the inference layer above, /tech is the detector catalogue (with /tech/frontend, /tech/build, /tech/testing and their siblings splitting it by category), /project reads package manifests, config files and repository roots, /nx reads nx.json and project.json for Nx-shaped repos, /vfs is the transactional tree, /models is types only, and /core holds the filesystem, path, encoding and platform primitives everything else is built from. /cli is the command layer: the package declares no bin, so run(argv) is how analyze, config, deps and tree are invoked, from your own binary rather than from a shell.

Every export, option and return type is in the API reference.

Compatibility