docs(readme): expand project details, features, and configuration

- Add initial tests for the CLI program.
- Export utility functions for improved testability.
- Standardize markdown list formatting and improve issue templates.

Author: ioncakephper

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,17 +1,17 @@
 ---
 name: Bug Report
 about: Report a reproducible bug
-title: "[BUG] <short description of bug>"
-labels: ["bug", "triage"]
+title: '[BUG] <short description of bug>'
+labels: ['bug', 'triage']
 assignees: ''
-
 ---
 
 **Describe the bug**
 A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,11 +24,13 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
+
 - OS: [e.g. iOS]
 - Browser [e.g. chrome, safari]
 - Version [e.g. 22]
 
 **Smartphone (please complete the following information):**
+
 - Device: [e.g. iPhone6]
 - OS: [e.g. iOS8.1]
 - Browser [e.g. stock browser, safari]

.github/ISSUE_TEMPLATE/documentation_issue.md

@@ -1,10 +1,9 @@
 ---
 name: Documentation Issue
 about: Report an issue with the documentation
-title: "[DOCS] <short description of documentation issue>"
-labels: ["documentation", "triage"]
+title: '[DOCS] <short description of documentation issue>'
+labels: ['documentation', 'triage']
 assignees: ''
-
 ---
 
 **Describe the documentation issue**

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,10 +1,9 @@
 ---
 name: Feature Request
 about: Suggest an idea for this project
-title: "[FEATURE] <short description of feature>"
-labels: ["enhancement", "triage"]
+title: '[FEATURE] <short description of feature>'
+labels: ['enhancement', 'triage']
 assignees: ''
-
 ---
 
 **Is your feature request related to a problem? Please describe.**

.github/ISSUE_TEMPLATE/general_question.md

@@ -1,10 +1,9 @@
 ---
 name: General Question
 about: Ask a general question about the project
-title: "[QUESTION] <short description of question>"
-labels: ["question", "triage"]
+title: '[QUESTION] <short description of question>'
+labels: ['question', 'triage']
 assignees: ''
-
 ---
 
 **What is your question?**

CONTRIBUTING.md

@@ -10,11 +10,11 @@ Please note that this project is released with a [Code of Conduct](RULES_OF_COND
 
 If you find a bug, please open an issue on our [GitHub Issues page](https://github.com/IonGireada/repo-description/issues). When reporting a bug, please include:
 
-*   A clear and concise description of the bug.
-*   Steps to reproduce the behavior.
-*   Expected behavior.
-*   Screenshots or error messages if applicable.
-*   Your operating system and Node.js version.
+- A clear and concise description of the bug.
+- Steps to reproduce the behavior.
+- Expected behavior.
+- Screenshots or error messages if applicable.
+- Your operating system and Node.js version.
 
 ### Suggesting Enhancements
 
@@ -72,8 +72,8 @@ You can then use the scripts defined in `package.json` for linting, formatting,
 
 This project uses ESLint and Prettier to enforce code style. Please ensure your code is formatted and linted correctly before submitting a pull request.
 
-*   Format your code: `npm run format`
-*   Lint your code: `npm run lint`
-*   Fix linting issues: `npm run lint:fix`
+- Format your code: `npm run format`
+- Lint your code: `npm run lint`
+- Fix linting issues: `npm run lint:fix`
 
 Thank you for contributing!

README.md

@@ -1,14 +1,29 @@
 # repo-description
 
-> AI‑powered CLI that automatically generates clear, natural‑language descriptions of every file in a repository.
+> An AI-powered CLI tool that automatically generates clear, natural-language descriptions for every file within a given repository. `repo-description` helps developers quickly understand unfamiliar codebases, onboard new team members, and maintain comprehensive documentation effortlessly. By leveraging advanced AI, it transforms raw code into insightful summaries, making project navigation and collaboration significantly smoother.
+
+## Features
+
+- **AI-Powered Descriptions**: Generates concise, natural-language summaries for individual files using advanced AI models.
+- **Flexible Output Formats**: Supports output in JSON or Markdown, allowing for easy integration into various workflows.
+- **Repository Agnostic**: Works with both local directories and remote GitHub repositories (automatically clones them).
+- **Customizable Ignoring**: Exclude specific files or directories (e.g., `node_modules`, `.git`) from the description process.
+- **Markdown-Magic Integration**: Seamlessly updates `markdown-magic.config.js` files to embed descriptions directly into your documentation.
+- **CLI & Module Usage**: Can be used as a standalone command-line tool or integrated as a JavaScript module within other projects.
 
 <!-- doc-gen BADGES -->
 
 [![npm version](https://img.shields.io/npm/v/repo-description.svg?style=for-the-badge)](https://www.npmjs.com/package/repo-description) [![npm downloads](https://img.shields.io/npm/dw/repo-description.svg?style=for-the-badge)](https://www.npmjs.com/package/repo-description) [![license](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](https://www.npmjs.com/package/repo-description) [![actions status](https://img.shields.io/github/actions/workflow/status/IonGireada/repo-description/ci.yml?branch=main&style=for-the-badge)](https://github.com/IonGireada/repo-description/actions) [![codecov](https://img.shields.io/codecov/c/github/IonGireada/repo-description?branch=main&style=for-the-badge)](https://codecov.io/gh/IonGireada/repo-description) [![release](https://img.shields.io/github/v/release/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/releases) [![maintained](https://img.shields.io/github/commit-activity/y/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/graphs/commit-activity) [![stars](https://img.shields.io/github/stars/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/stargazers) [![forks](https://img.shields.io/github/forks/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/network/members) [![watchers](https://img.shields.io/github/watchers/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/watchers) [![last commit](https://img.shields.io/github/last-commit/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/commits) [![contributors](https://img.shields.io/github/contributors/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/graphs/contributors) [![issues](https://img.shields.io/github/issues/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/issues) [![pull requests](https://img.shields.io/github/issues-pr/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/pulls) [![repo size](https://img.shields.io/github/repo-size/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description) [![top language](https://img.shields.io/github/languages/top/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description) [![languages](https://img.shields.io/github/languages/count/IonGireada/repo-description?style=for-the-badge)](https://github.com/IonGireada/repo-description/search?l=)
 
 <!-- end-doc-gen -->
 
-## Installation
+## Getting Started
+
+:::note
+**Important:** Before running, create a `.env` file in your project root with your Groq API key. The key must be named `GROQ_API_KEY`. You can obtain an API key by creating an account and visiting [https://console.groq.com/keys](https://console.groq.com/keys).
+:::
+
+### Installation
 
 <!-- doc-gen INSTALL global=true -->
 
@@ -22,11 +37,7 @@ yarn add -g repo-description
 
 <!-- end-doc-gen -->
 
-## Usage
-
-:::note
-**Important:** Before running, create a `.env` file in your project root with your Groq API key. The key name should be `GROQ_API_KEY`. You can obtain an API key by creating an account and visiting [https://console.groq.com/keys](https://console.groq.com/keys).
-:::
+### Usage
 
 ### As a JavaScript Module
 
@@ -108,6 +119,19 @@ repo-describer . -i "dist" "build" --update-config ./md.config.js --transform-na
 repo-describer --help
 ```
 
+## Configuration
+
+`repo-description` requires an API key from [Groq](https://groq.com) to function. Follow these steps to configure your API key:
+
+1.  **Obtain an API Key**: Visit [https://console.groq.com/keys](https://console.groq.com/keys) and create a new API key.
+2.  **Create `.env` file**: In the root directory of your project (or where you run `repo-describer`), create a file named `.env`.
+3.  **Add API Key**: Add your Groq API key to the `.env` file in the format:
+    ```
+    GROQ_API_KEY=your_groq_api_key_here
+    ```
+
+Ensure your `.env` file is included in your `.gitignore` to prevent your API key from being committed to version control.
+
 ## CLI API
 
 ### Help Output
@@ -157,43 +181,43 @@ Options:
 
 <!-- doc-gen COMMANDS format=list -->
 
-- `describe` — Generates AI-powered descriptions for repository files and outputs them in various formats. (line [89](./package.json#L89))
+- `describe` — Generates AI-powered descriptions for repository files and outputs them in various formats. (line [86](./package.json#L86))
 
   ```bash
   node src/cli.js . descriptions.json && node src/cli.js . descriptions.md --format markdown && node src/cli.js . descriptions-table.md --format markdown --table && node src/cli.js . descriptions-summary.md --format markdown --summary && node src/cli.js . descriptions-table-summary.md --format markdown --table --summary
   ```
 
-- `docs` — Generates documentation by processing Markdown files with markdown-magic. (line [94](./package.json#L94))
+- `docs` — Generates documentation by processing Markdown files with markdown-magic. (line [91](./package.json#L91))
 
   ```bash
   npx [email protected] **/*.md -c md.config.js
   ```
 
-- `format` — Formats the codebase using Prettier. (line [92](./package.json#L92))
+- `format` — Formats the codebase using Prettier. (line [89](./package.json#L89))
 
   ```bash
   prettier --write .
   ```
 
-- `lint` — Lints the codebase for potential errors and style violations. (line [90](./package.json#L90))
+- `lint` — Lints the codebase for potential errors and style violations. (line [87](./package.json#L87))
 
   ```bash
   eslint src/ **/*.js **/*.json
   ```
 
-- `lint:fix` — Lints the codebase and automatically fixes fixable issues. (line [91](./package.json#L91))
+- `lint:fix` — Lints the codebase and automatically fixes fixable issues. (line [88](./package.json#L88))
 
   ```bash
   eslint --fix src/ **/*.js **/*.json
   ```
 
-- `prep` — Prepares the codebase by generating documentation, linting, and formatting. (line [93](./package.json#L93))
+- `prep` — Prepares the codebase by generating documentation, linting, and formatting. (line [90](./package.json#L90))
 
   ```bash
   npm run docs && npm run lint:fix && npm run format
   ```
 
-- `test` — Runs the test suite using Jest. (line [88](./package.json#L88))
+- `test` — Runs the test suite using Jest. (line [85](./package.json#L85))
 
   ```bash
   jest --passWithNoTests
@@ -242,6 +266,9 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ```
 repo-description/
+├── __tests__
+│   ├── .gitkeep
+│   └── cli.test.js
 ├── .qodo
 │   ├── agents
 │   └── workflows
@@ -255,11 +282,14 @@ repo-description/
 ├── .gitignore
 ├── .prettierrc.json
 ├── babel.config.js
+├── CONTRIBUTING.md
 ├── eslint.config.js
+├── LICENSE
 ├── md.config.js
 ├── package-lock.json
 ├── package.json
-└── README.md
+├── README.md
+└── RULES_OF_CONDUCT.md
 ```
 
 <!-- end-doc-gen -->

RULES_OF_CONDUCT.md

@@ -17,24 +17,24 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-*   Demonstrating empathy and kindness toward other people
-*   Being respectful of differing opinions, viewpoints, and experiences
-*   Giving and gracefully accepting constructive feedback
-*   Accepting responsibility and apologizing to those affected by our mistakes,
-    and learning from the experience
-*   Focusing on what is best not just for us as individuals, but for the
-    overall community
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
 
 Examples of unacceptable behavior include:
 
-*   The use of sexualized language or imagery, and sexual attention or
-    advances of any kind
-*   Trolling, insulting or derogatory comments, and personal or political attacks
-*   Public or private harassment
-*   Publishing others' private information, such as a physical or email
-    address, without their explicit permission
-*   Other conduct which could reasonably be considered inappropriate in a
-    professional setting
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
 ## Enforcement Responsibilities
 

__tests__/.gitkeep

@@ -0,0 +1 @@
+// This is a placeholder file to create the __tests__ directory.

__tests__/cli.test.js

@@ -0,0 +1,22 @@
+const { program } = require('../src/cli');
+
+describe('CLI Program', () => {
+  test('should have the correct name', () => {
+    expect(program.name()).toBe('repo-describer');
+  });
+
+  test('should have the correct version', () => {
+    expect(program.version()).toBe('1.0.0');
+  });
+
+  test.skip('should execute the action correctly for local repo', async () => {
+    // This test would require mocking fs, child_process, and the imported functions
+    // from index.js (describeRepo, saveOutput, updateMarkdownMagicConfig).
+    // It would also involve simulating command-line arguments.
+    // For now, it's skipped.
+  });
+
+  test.skip('should execute the action correctly for remote repo', async () => {
+    // Similar to the local repo test, but also involves mocking git clone.
+  });
+});

package.json

@@ -80,7 +80,6 @@
     "prettier-plugin-packagejson": "^2.5.19",
     "yaml-eslint-parser": "^1.3.0"
   },
-
   "scriptsMeta": {
     "test": "Runs the test suite using Jest.",
     "describe": "Generates AI-powered descriptions for repository files and outputs them in various formats.",