@hyperfrontend/project-scope 0.2.0 → 0.2.2

package/ARCHITECTURE.md

@@ -1,370 +0,0 @@
-# Architecture
-
-This document describes the architecture of `@hyperfrontend/project-scope`, a comprehensive library for analyzing JavaScript/TypeScript project structure, technology stack, and dependencies.
-
-## Overview
-
-```mermaid
-graph LR
-    subgraph "High Level"
-        CLI[cli/]
-        ANALYZE[analyze.ts]
-    end
-
-    subgraph "Domain Logic"
-        TECH[tech/]
-        HEUR[heuristics/]
-        PROJ[project/]
-        NX[nx/]
-        VFS[vfs/]
-    end
-
-    subgraph "Foundation"
-        CORE[core/]
-        MODELS[models/]
-    end
-
-    CLI --> ANALYZE
-    ANALYZE --> TECH
-    ANALYZE --> HEUR
-    ANALYZE --> PROJ
-    ANALYZE --> NX
-
-    TECH --> CORE
-    TECH --> PROJ
-    HEUR --> CORE
-    HEUR --> PROJ
-    HEUR --> TECH
-    PROJ --> CORE
-    NX --> CORE
-    NX --> PROJ
-    VFS --> CORE
-
-    CLI --> MODELS
-    ANALYZE --> MODELS
-    TECH --> MODELS
-    HEUR --> MODELS
-```
-
-## Module Structure
-
-```
-libs/project-scope/src/
-├── analyze.ts           # Main entry point (analyzeProject)
-├── index.ts             # Public exports
-├── cli/                 # Command-line interface
-├── core/                # Foundation utilities
-├── heuristics/          # Intelligent detection algorithms
-├── models/              # TypeScript types and interfaces
-├── nx/                  # NX workspace integration
-├── project/             # Project structure analysis
-├── tech/                # Technology stack detection
-└── vfs/                 # Virtual file system
-```
-
-## Data Flow
-
-### Analysis Pipeline
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant analyzeProject
-    participant tech/detectAll
-    participant heuristics
-    participant project
-    participant core/fs
-
-    User->>analyzeProject: analyzeProject('./my-project')
-    analyzeProject->>core/fs: readPackageJson
-    core/fs-->>analyzeProject: PackageJson
-
-    analyzeProject->>tech/detectAll: detectAll(path, pkg)
-    tech/detectAll->>core/fs: exists(), readFile()
-    core/fs-->>tech/detectAll: file contents
-    tech/detectAll-->>analyzeProject: AllDetections
-
-    analyzeProject->>heuristics: detectProjectType()
-    heuristics->>tech/detectAll: detectAll (cached)
-    heuristics-->>analyzeProject: ProjectTypeDetection
-
-    analyzeProject->>heuristics: discoverEntryPoints()
-    heuristics-->>analyzeProject: EntryPointInfo[]
-
-    analyzeProject->>project: detectConfigs()
-    project->>core/fs: findFiles()
-    project-->>analyzeProject: DetectedConfig[]
-
-    analyzeProject-->>User: AnalysisResult
-```
-
-## Core Components
-
-### 1. Analysis Engine (`analyze.ts`)
-
-The main entry point that orchestrates all detection modules:
-
-```typescript
-function analyzeProject(projectPath: string, options?: AnalyzeOptions): AnalysisResult
-```
-
-**Responsibilities:**
-
-- Coordinate all detection modules
-- Aggregate results into unified structure
-- Handle options for selective analysis
-- Track analysis metadata (timing, version)
-
-### 2. Technology Detection (`tech/`)
-
-Detects frameworks, build tools, and testing frameworks:
-
-```mermaid
-graph TB
-    subgraph "tech/"
-        INDEX[index.ts/detectAll]
-        FE[frontend/]
-        BE[backend/]
-        BUILD[build/]
-        TEST[testing/]
-        MONO[monorepo/]
-        TYPES[types/]
-        LINT[linting/]
-        LEGACY[legacy/]
-    end
-
-    INDEX --> FE
-    INDEX --> BE
-    INDEX --> BUILD
-    INDEX --> TEST
-    INDEX --> MONO
-    INDEX --> TYPES
-    INDEX --> LINT
-    INDEX --> LEGACY
-
-    FE --> DETECT[Detection Results]
-    BE --> DETECT
-    BUILD --> DETECT
-    TEST --> DETECT
-    MONO --> DETECT
-    TYPES --> DETECT
-    LINT --> DETECT
-    LEGACY --> DETECT
-```
-
-**Design Patterns:**
-
-- Each detector implements a common interface
-- Results include confidence scores (0-100)
-- Detection sources are tracked for transparency
-- Caching with 60-second TTL
-
-### 3. Heuristics (`heuristics/`)
-
-Intelligent detection using multiple signals:
-
-```mermaid
-graph LR
-    subgraph "Evidence Collection"
-        PKG[package.json patterns]
-        DIR[Directory structure]
-        FILES[File patterns]
-        TECH[Tech detections]
-    end
-
-    subgraph "Scoring"
-        SCORE[Score Aggregation]
-        CONF[Confidence Calculation]
-    end
-
-    PKG --> SCORE
-    DIR --> SCORE
-    FILES --> SCORE
-    TECH --> SCORE
-    SCORE --> CONF
-    CONF --> |ProjectTypeDetection| RESULT[Result with Evidence]
-```
-
-**Key Characteristics:**
-
-- Multi-signal analysis for accuracy
-- Evidence tracking for explainability
-- Confidence scoring for reliability indication
-- Caching for performance
-
-### 4. Virtual File System (`vfs/`)
-
-Transactional file operations:
-
-```mermaid
-stateDiagram-v2
-    [*] --> Clean: createTree()
-    Clean --> Modified: write/delete/rename
-    Modified --> Modified: more changes
-    Modified --> Clean: commitChanges()
-    Modified --> Clean: rollbackChanges()
-```
-
-**Properties:**
-
-- All changes buffered in memory
-- Atomic commit or rollback
-- Path traversal protection
-- Symlink security validation
-
-### 5. Core Utilities (`core/`)
-
-Foundation layer providing:
-
-| Component   | Purpose                                 |
-| ----------- | --------------------------------------- |
-| `fs/`       | Safe file system operations             |
-| `path/`     | Cross-platform path manipulation        |
-| `logger.ts` | Scoped logging with secret sanitization |
-| `cache.ts`  | In-memory caching with TTL              |
-| `errors/`   | Structured error creation               |
-| `patterns/` | ReDoS-safe glob matching                |
-| `encoding/` | File encoding detection                 |
-| `platform/` | OS detection                            |
-
-## Caching Strategy
-
-```mermaid
-graph TB
-    subgraph "Cache Layers"
-        L1[detectAll Cache<br/>TTL: 60s]
-        L2[configDetection Cache<br/>TTL: 30s]
-        L3[entryPoint Cache<br/>TTL: 60s]
-        L4[framework Cache<br/>TTL: 60s]
-    end
-
-    subgraph "Cache Management"
-        REG[Cache Registry]
-        CLEAR[clearAllCaches]
-    end
-
-    L1 --> REG
-    L2 --> REG
-    L3 --> REG
-    L4 --> REG
-    REG --> CLEAR
-```
-
-**Cache Characteristics:**
-
-- Function-specific TTLs based on volatility
-- Size limits prevent memory issues
-- Skip-cache option for fresh results
-- Global clear for testing
-
-## Error Handling
-
-```mermaid
-graph LR
-    OP[Operation] --> CHECK{Error?}
-    CHECK -->|Yes| STRUCT[StructuredError]
-    CHECK -->|No| RESULT[Result]
-    STRUCT --> CODE[Error Code]
-    STRUCT --> CTX[Context Object]
-    STRUCT --> MSG[Human Message]
-```
-
-**Error Types:**
-
-- `FS_NOT_FOUND` - File/directory not found
-- `FS_READ_ERROR` - Read operation failed
-- `FS_WRITE_ERROR` - Write operation failed
-- `FS_PARSE_ERROR` - JSON/config parse failure
-- `CONFIG_NOT_FOUND` - Configuration not found
-- `VALIDATION_ERROR` - Invalid input
-
-## Security Considerations
-
-### Path Traversal Prevention
-
-```typescript
-// VFS normalizes and validates all paths
-tree.read('../../../etc/passwd') // Throws: Path escapes tree root
-```
-
-### Symlink Security
-
-```mermaid
-graph LR
-    SYMLINK[Symlink] --> CHECK{Target in root?}
-    CHECK -->|Yes| ALLOW[Allow operation]
-    CHECK -->|No| DENY[Throw error]
-```
-
-### Secret Sanitization
-
-```typescript
-// Logger automatically redacts sensitive keys
-logger.debug('Config loaded', { apiKey: 'secret123' })
-// Output: [scope] Config loaded {"apiKey":"[REDACTED]"}
-```
-
-Sensitive key patterns: `token`, `key`, `password`, `secret`, `credential`, `auth`, `bearer`, `api_key`, `private`, `passphrase`
-
-### ReDoS Protection
-
-Glob matching uses character-by-character iteration instead of regex to prevent Regular Expression Denial of Service attacks.
-
-## Extension Points
-
-### Adding a New Framework Detector
-
-```typescript
-// tech/frontend/my-framework.ts
-import type { FrameworkDetector } from './types'
-
-export const myFrameworkDetector: FrameworkDetector = {
-  id: 'my-framework',
-  name: 'MyFramework',
-  category: 'frontend',
-  detect(projectPath, packageJson) {
-    // Detection logic
-    return {
-      id: 'my-framework',
-      name: 'MyFramework',
-      confidence: 80,
-      detectedFrom: [{ type: 'package.json', field: 'dependencies.my-framework' }],
-    }
-  },
-}
-
-// Register in tech/frontend/index.ts
-export const frameworkDetectors = [..., myFrameworkDetector]
-```
-
-### Adding a New CLI Command
-
-```typescript
-// cli/commands/my-command.ts
-import type { Command } from '../types'
-
-export const myCommandDef: Command = {
-  name: 'my-command',
-  description: 'Does something useful',
-  execute(args, globalOptions) {
-    // Command logic
-    return { exitCode: 0 }
-  },
-  getHelp() {
-    return 'Usage: project-scope my-command [options]'
-  },
-}
-
-// Register in cli/run.ts
-const commands = { ..., 'my-command': myCommandDef }
-```
-
-## Performance Characteristics
-
-| Operation               | Typical Time | Caching       |
-| ----------------------- | ------------ | ------------- |
-| `analyzeProject` (full) | 50-200ms     | Per-component |
-| `detectAll`             | 20-50ms      | 60s TTL       |
-| `detectConfigs`         | 10-30ms      | 30s TTL       |
-| `buildDependencyGraph`  | 100-500ms    | None          |
-| `findFiles`             | 10-100ms     | None          |

package/analyze.d.ts

@@ -1,33 +0,0 @@
-import type { AnalysisResult } from './models';
-/**
- * Options for project analysis.
- */
-export interface AnalyzeOptions {
-    /** Analysis depth */
-    depth?: 'basic' | 'full' | 'deep';
-    /** Specific analyses to include */
-    include?: Array<'frameworks' | 'buildTools' | 'testing' | 'entryPoints' | 'configs' | 'dependencies'>;
-    /** Analyses to skip */
-    exclude?: Array<'frameworks' | 'buildTools' | 'testing' | 'entryPoints' | 'configs' | 'dependencies'>;
-    /** Enable verbose logging */
-    verbose?: boolean;
-}
-/**
- * Analyze a project for frameworks, build tools, and structure.
- *
- * This is the main entry point for comprehensive project analysis.
- * It orchestrates all detection modules and returns a unified result.
- *
- * @param projectPath - Path to project directory
- * @param options - Analysis options
- * @returns Complete analysis result
- *
- * @example
- * ```typescript
- * const result = analyzeProject('./my-project')
- * console.log(result.projectType) // 'application' | 'library' | ...
- * console.log(result.frameworks)  // [{ id: 'react', name: 'React', ... }]
- * ```
- */
-export declare function analyzeProject(projectPath: string, options?: AnalyzeOptions): AnalysisResult;
-//# sourceMappingURL=analyze.d.ts.map

package/analyze.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../../../../../libs/project-scope/src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,cAAc,EASf,MAAM,UAAU,CAAA;AAmBjB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;IACjC,mCAAmC;IACnC,OAAO,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC,CAAA;IACrG,uBAAuB;IACvB,OAAO,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC,CAAA;IACrG,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AA8FD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CA2J5F"}

package/cli/commands/analyze.d.ts

@@ -1,20 +0,0 @@
-import type { Command, CommandResult, OutputFormat } from '../types';
-export interface AnalyzeCommandOptions {
-    path?: string;
-    format?: OutputFormat;
-    depth?: 'basic' | 'full' | 'deep';
-    include?: string[];
-    exclude?: string[];
-}
-/**
- * Execute analyze command with given options.
- *
- * @param options - Configuration for the analyze operation
- * @returns Command execution result with exit code and output
- */
-export declare function analyzeCommand(options: AnalyzeCommandOptions): CommandResult;
-/**
- * Analyze command definition implementing Command interface.
- */
-export declare const analyzeCommandDef: Command;
-//# sourceMappingURL=analyze.d.ts.map

package/cli/commands/analyze.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/cli/commands/analyze.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAiB,YAAY,EAAE,MAAM,UAAU,CAAA;AAQnF,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;IACjC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAiOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAgC5E;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,OA6C/B,CAAA"}

package/cli/commands/config.d.ts

@@ -1,20 +0,0 @@
-import type { ConfigType } from '../../project/config';
-import type { Command, CommandResult, OutputFormat } from '../types';
-export interface ConfigCommandOptions {
-    path?: string;
-    type?: ConfigType;
-    showContents?: boolean;
-    format?: OutputFormat;
-}
-/**
- * Execute config command with given options.
- *
- * @param options - Configuration command options
- * @returns Command execution result with exit code and output
- */
-export declare function configCommand(options: ConfigCommandOptions): CommandResult;
-/**
- * Config command definition implementing Command interface.
- */
-export declare const configCommandDef: Command;
-//# sourceMappingURL=config.d.ts.map

package/cli/commands/config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/cli/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,sBAAsB,CAAA;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAiB,YAAY,EAAE,MAAM,UAAU,CAAA;AAOnF,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AA2ND;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAqB1E;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAmC9B,CAAA"}

package/cli/commands/deps.d.ts

@@ -1,18 +0,0 @@
-import type { Command, CommandResult, OutputFormat } from '../types';
-export interface DepsCommandOptions {
-    path?: string;
-    type?: 'production' | 'development' | 'peer' | 'optional' | 'all';
-    format?: OutputFormat;
-}
-/**
- * Execute deps command with given options.
- *
- * @param options - Parsed command options
- * @returns Command execution result with exit code and output
- */
-export declare function depsCommand(options: DepsCommandOptions): CommandResult;
-/**
- * Deps command definition implementing Command interface.
- */
-export declare const depsCommandDef: Command;
-//# sourceMappingURL=deps.d.ts.map

package/cli/commands/deps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/cli/commands/deps.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAiB,YAAY,EAAE,MAAM,UAAU,CAAA;AAQnF,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,YAAY,GAAG,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAA;IACjE,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAyKD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAqBtE;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,OAuC5B,CAAA"}

package/cli/commands/tree.d.ts

@@ -1,24 +0,0 @@
-import type { Command, CommandResult, OutputFormat } from '../types';
-export interface TreeCommandOptions {
-    path?: string;
-    depth?: number;
-    pattern?: string;
-    ignore?: string[];
-    dirsOnly?: boolean;
-    filesOnly?: boolean;
-    showSize?: boolean;
-    showModified?: boolean;
-    format?: OutputFormat;
-}
-/**
- * Execute tree command with given options.
- *
- * @param options - Configuration for the tree operation
- * @returns Command execution result with exit code and output
- */
-export declare function treeCommand(options: TreeCommandOptions): CommandResult;
-/**
- * Tree command definition implementing Command interface.
- */
-export declare const treeCommandDef: Command;
-//# sourceMappingURL=tree.d.ts.map

package/cli/commands/tree.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/cli/commands/tree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAiB,YAAY,EAAE,MAAM,UAAU,CAAA;AASnF,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAgQD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAmCtE;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,OAyC5B,CAAA"}