@brunobrise/xfeat 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve the analysis
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Run command '...'
+2. Directory structure looks like '...'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen in the FEATURES.md or console.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+
+- OS: [e.g. macOS]
+- Node Version [e.g. 18.x]
+- Target Language [e.g. Python, TypeScript]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[FEAT] "
+labels: enhancement
+assignees: ""
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen. Perhaps a new CLI flag or language support.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
+
+Fixes # (issue number)
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+## Checklist:
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings or lints (`npm run lint`)
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes (`npm test`)

package/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run lint
+    - run: npm test
+    - run: npm audit --audit-level=critical

package/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+on:
+  push:
+    branches:
+      - main
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to be able to publish a GitHub release
+      issues: write # to be able to comment on released issues
+      pull-requests: write # to be able to comment on released pull requests
+      id-token: write # to enable use of OIDC for npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install dependencies
+        run: npm ci
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm run pre-commit

package/.releaserc.json

@@ -0,0 +1,9 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1 @@
+{}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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.

package/README.md

@@ -0,0 +1,105 @@
+# xfeat
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18.x-green.svg)](https://nodejs.org/)
+
+**xfeat** is an automated, AI-driven CLI engine that deeply analyzes your codebase to extract product-level features, component architectures, and global system scopes. By combining precise AST-based structural parsing (via `web-tree-sitter`) with the reasoning capabilities of Anthropic's Claude 3.7 Sonnet, this tool auto-generates comprehensive, human-readable documentation of what your code _actually_ does.
+
+## Key Features
+
+- **AST-Powered Parsing:** Fast and accurate structural footprint generation (classes, functions, exports, imports) for modern ecosystem languages.
+- **Agentic Source Code Reading:** Rather than guessing based off function identifiers, the AI utilizes a specialized `view_file` tool to selectively dive into the raw source code wherever AST context is insufficient.
+- **Automated Mermaid Diagrams:** Visually maps out how files interact at macro and global architecture levels.
+- **Structured Markdown Deliverables:** Produces a neat, hierarchical `FEATURES.md` report encompassing everything from the executive summary to granular file logic.
+- **Smart Directory Traversal:** Adheres to your local `.gitignore` rules to avoid processing build artifacts and generic dependencies.
+
+## How It Works
+
+The engine executes in an expanding 3-stage pipeline:
+
+1. **Micro Analysis (File-Level):**
+   - Identifies granular structural signatures across source files.
+   - Leverages an LLM sub-agent loop to request file contents as needed.
+   - Outputs 1-2 sentence overviews alongside high-level feature bullet points for each file.
+
+2. **Macro Analysis (Component-Level):**
+   - Groups files logically by their enclosing directory.
+   - Synthesizes isolated file summaries into a curated **Component Summary**.
+   - Generates localized [Mermaid.js](https://mermaid.js.org/) flow/architecture diagrams per directory.
+
+3. **Global Analysis (System-Level):**
+   - Ties localized component summaries together into a master architecture overview.
+   - Documents the core pillars and overarching domain of the application.
+   - Renders a highly-abstracted global Mermaid architecture diagram representing the entire system interaction.
+
+## Installation
+
+Ensure you have [Node.js](https://nodejs.org/) installed, then clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/brunobrise/code-features-extract.git xfeat
+cd xfeat
+npm install
+```
+
+## Configuration
+
+Create a `.env` file at the root of the project to define your API authorization:
+
+```env
+# Required: Your Anthropic API Key
+ANTHROPIC_API_KEY="sk-ant-..."
+
+# Optional Environment Overrides
+ANTHROPIC_AUTH_TOKEN=""
+ANTHROPIC_BASE_URL=""
+CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"
+```
+
+## Usage
+
+You can scan the immediate working directory, or pass a relative/absolute path to dynamically scan another repository on your machine.
+
+### Scan Current Directory
+
+```bash
+npx xfeat
+```
+
+### Scan Remote Directory Path
+
+```bash
+npx xfeat /path/to/your/custom/project
+```
+
+### Development Tooling
+
+For developers contributing to this tool, standard npm scripts are available:
+
+- `npm run dev` — Hot-reloads the analysis script using Nodemon.
+- `npm run lint` — Analyzes the source using ESLint against best practices.
+- `npm run format` — Standardizes code styling uniformly with Prettier.
+
+## Expected Output
+
+The script concludes by generating a structured `FEATURES.md` record at your execution root. Inside, you can expect:
+
+1. **Global Architecture Overview** _(Executive Summary, Application Pillars, Main System Diagram)_
+2. **Component Breakdown** _(Directory-by-Directory Insights, Narrow Context Diagrams)_
+3. **File-Level Details** _(Deeply granular feature lists)_
+
+## Supported Languages
+
+The foundational Tree-sitter AST parser natively understands:
+
+- JavaScript (`.js`, `.jsx`)
+- TypeScript (`.ts`, `.tsx`)
+- Python (`.py`)
+
+## License
+
+This tooling is open-sourced under the **MIT** License.
+
+---
+
+_Built organically with the [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-typescript) and [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)._

package/eslint.config.js

@@ -0,0 +1,5 @@
+module.exports = [
+  {
+    rules: {},
+  },
+];