@hyperfrontend/project-scope 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,370 @@
+# 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/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## 0.1.0 (2026-03-08)
+
+
+### Features
+
+* **lib-project-scope:** complete implementation ([6075fbd](https://github.com/AndrewRedican/hyperfrontend/commit/6075fbd8a8b3b790715d0985612d07a1fb398020))

package/FUNDING.md

@@ -0,0 +1,141 @@
+# Funding & Support
+
+Thank you for considering supporting hyperfrontend! Your contributions help maintain and improve this project.
+
+## Why Support hyperfrontend?
+
+hyperfrontend is an open-source project that provides:
+
+- 🔧 Framework-agnostic micro-frontend architecture
+- 📦 Multiple packages and tools for building scalable web applications
+- 📚 Comprehensive documentation and examples
+- 🆓 Free for everyone to use
+
+Your support helps:
+
+- ⏰ Dedicate more time to development and maintenance
+- 🐛 Fix bugs and address issues faster
+- ✨ Build new features and improvements
+- 📖 Create better documentation and tutorials
+- 🌟 Keep the project sustainable long-term
+
+## How to Support
+
+### 💖 GitHub Sponsors
+
+You can sponsor the project through GitHub Sponsors:
+
+**[Sponsor @AndrewRedican on GitHub](https://github.com/sponsors/AndrewRedican)**
+
+GitHub Sponsors benefits:
+
+- Direct support to the maintainer
+- No platform fees (GitHub covers them)
+- Various sponsorship tiers available
+- Recognition in the project
+
+### 🌐 One-time Donations
+
+You can also make a one-time contribution:
+
+**[Donate via hyperfrontend.dev](https://hyperfrontend.dev/sponsor)**
+
+### 🏢 Corporate Sponsorship
+
+If your company uses hyperfrontend in production, consider becoming a corporate sponsor:
+
+- **Bronze Sponsor** ($100/month) - Logo in README
+- **Silver Sponsor** ($500/month) - Logo in README + website
+- **Gold Sponsor** ($1000/month) - Logo placement + priority support
+- **Platinum Sponsor** ($2500/month) - All benefits + consulting hours
+
+Contact: andrew.redican.mejia@gmail.com
+
+## Other Ways to Contribute
+
+Not everyone can contribute financially, and that's okay! There are many other ways to support:
+
+### 💻 Code Contributions
+
+- Submit bug fixes
+- Add new features
+- Improve documentation
+- Write tests
+
+See our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### 📣 Spread the Word
+
+- ⭐ Star the repository on GitHub
+- 🐦 Share on social media
+- 📝 Write blog posts or tutorials
+- 🎤 Give talks about hyperfrontend at meetups/conferences
+
+### 🐛 Bug Reports
+
+- Report issues you encounter
+- Help triage existing issues
+- Provide detailed reproduction steps
+
+### 📚 Documentation
+
+- Improve existing docs
+- Write tutorials and guides
+- Translate documentation
+- Create video tutorials
+
+### 💬 Community Support
+
+- Answer questions in issues
+- Help other users on discussions
+- Share your use cases and examples
+
+## Current Sponsors
+
+Thank you to all our sponsors and backers! 🙏
+
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+
+[![All Contributors](https://img.shields.io/github/all-contributors/AndrewRedican/hyperfrontend?color=ee8449&style=flat-square)](#contributors)
+
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
+### Corporate Sponsors
+
+<!-- Corporate sponsors will be listed here -->
+
+_Interested in corporate sponsorship? [Contact us](mailto:andrew.redican.mejia@gmail.com)_
+
+### Individual Sponsors
+
+<!-- Sponsors will be automatically listed through GitHub Sponsors -->
+
+_Become the first sponsor!_ ❤️
+
+## Recognition
+
+All sponsors and contributors are recognized in:
+
+- Project README
+- Project website (coming soon)
+- Release notes (for significant contributions)
+
+## Transparency
+
+All sponsorship funds are used for:
+
+- Development time and effort
+- Infrastructure costs (hosting, CI/CD, domains)
+- Development tools and services
+- Community building and events
+
+## Questions?
+
+If you have questions about sponsorship or funding, please contact:
+
+**Email**: andrew.redican.mejia@gmail.com
+**GitHub**: [@AndrewRedican](https://github.com/AndrewRedican)
+
+---
+
+Thank you for your support! Every contribution, whether code, documentation, or financial, helps make hyperfrontend better for everyone. 🚀

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Redican
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.