Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
@@ -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 '....'
Expand All @@ -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]
Expand Down
5 changes: 2 additions & 3 deletions .github/ISSUE_TEMPLATE/documentation_issue.md
Original file line number Diff line number Diff line change
@@ -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**
Expand Down
5 changes: 2 additions & 3 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
@@ -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.**
Expand Down
5 changes: 2 additions & 3 deletions .github/ISSUE_TEMPLATE/general_question.md
Original file line number Diff line number Diff line change
@@ -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?**
Expand Down
16 changes: 8 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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!
60 changes: 45 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -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).
:::
Comment on lines +22 to +24

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The :::note syntax is not standard GitHub Flavored Markdown and will not render as a special admonition block. It will likely be displayed as a plain code block. For better compatibility and readability on GitHub, consider using a blockquote (>) for important notes.

Suggested change
:::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).
:::
> **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 -->

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 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
Expand Down Expand Up @@ -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
Expand All @@ -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 -->
30 changes: 15 additions & 15 deletions RULES_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions __tests__/.gitkeep
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
// This is a placeholder file to create the __tests__ directory.
22 changes: 22 additions & 0 deletions __tests__/cli.test.js
Original file line number Diff line number Diff line change
@@ -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');

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The version number is hardcoded. To avoid it getting out of sync with your project's version, it's better to import it directly from package.json. This will make your tests more robust to version changes. A similar change should be applied in src/cli.js where the version is also hardcoded.

Suggested change
expect(program.version()).toBe('1.0.0');
expect(program.version()).toBe(require('../package.json').version);

});

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.
});
});
1 change: 0 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Expand Down
3 changes: 3 additions & 0 deletions src/describe.js
Original file line number Diff line number Diff line change
Expand Up @@ -207,4 +207,7 @@ module.exports = {
describeRepo,
updateMarkdownMagicConfig,
saveOutput,
getAllFiles,
queryGroq,
sleep,
};