diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 491daed..790d687 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,10 +1,9 @@ --- name: Bug Report about: Report a reproducible bug -title: "[BUG] " -labels: ["bug", "triage"] +title: '[BUG] ' +labels: ['bug', 'triage'] assignees: '' - --- **Describe the bug** @@ -12,6 +11,7 @@ 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] diff --git a/.github/ISSUE_TEMPLATE/documentation_issue.md b/.github/ISSUE_TEMPLATE/documentation_issue.md index 77f773e..1b94296 100644 --- a/.github/ISSUE_TEMPLATE/documentation_issue.md +++ b/.github/ISSUE_TEMPLATE/documentation_issue.md @@ -1,10 +1,9 @@ --- name: Documentation Issue about: Report an issue with the documentation -title: "[DOCS] " -labels: ["documentation", "triage"] +title: '[DOCS] ' +labels: ['documentation', 'triage'] assignees: '' - --- **Describe the documentation issue** diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 7031120..9b8c15c 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,10 +1,9 @@ --- name: Feature Request about: Suggest an idea for this project -title: "[FEATURE] " -labels: ["enhancement", "triage"] +title: '[FEATURE] ' +labels: ['enhancement', 'triage'] assignees: '' - --- **Is your feature request related to a problem? Please describe.** diff --git a/.github/ISSUE_TEMPLATE/general_question.md b/.github/ISSUE_TEMPLATE/general_question.md index 52a7e50..79d79c1 100644 --- a/.github/ISSUE_TEMPLATE/general_question.md +++ b/.github/ISSUE_TEMPLATE/general_question.md @@ -1,10 +1,9 @@ --- name: General Question about: Ask a general question about the project -title: "[QUESTION] " -labels: ["question", "triage"] +title: '[QUESTION] ' +labels: ['question', 'triage'] assignees: '' - --- **What is your question?** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c672c42..39e0dfd 100644 --- a/CONTRIBUTING.md +++ b/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! diff --git a/README.md b/README.md index 2007fd7..e621de6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,15 @@ # 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. @@ -8,7 +17,13 @@ -## 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 @@ -22,11 +37,7 @@ yarn add -g repo-description -## 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: -- `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 markdown-magic@3.7.0 **/*.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 ``` diff --git a/RULES_OF_CONDUCT.md b/RULES_OF_CONDUCT.md index c1f4440..08783c6 100644 --- a/RULES_OF_CONDUCT.md +++ b/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 diff --git a/__tests__/.gitkeep b/__tests__/.gitkeep new file mode 100644 index 0000000..449b6df --- /dev/null +++ b/__tests__/.gitkeep @@ -0,0 +1 @@ +// This is a placeholder file to create the __tests__ directory. diff --git a/__tests__/cli.test.js b/__tests__/cli.test.js new file mode 100644 index 0000000..9ae5d66 --- /dev/null +++ b/__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. + }); +}); diff --git a/package.json b/package.json index 9b69830..47f5c07 100644 --- a/package.json +++ b/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.", diff --git a/src/describe.js b/src/describe.js index 85e2756..49a3d68 100644 --- a/src/describe.js +++ b/src/describe.js @@ -207,4 +207,7 @@ module.exports = { describeRepo, updateMarkdownMagicConfig, saveOutput, + getAllFiles, + queryGroq, + sleep, };