repo-description

v1.0.5

Published

6 months ago

AI-powered CLI that automatically generates clear, natural-language descriptions of every file in a repository.

Downloads

repo-description

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.

Getting Started

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.

Installation

npm install -g repo-description

yarn add -g repo-description

Usage

As a JavaScript Module

You can use repo-description directly in your JavaScript or Node.js projects:

require('dotenv/config'); // Load environment variables

const { describeRepo, saveOutput } = require('repo-description');

async function runDescription() {
  const repoPath = './'; // Current repository or path to a local folder

  // Scenario 1: Generate JSON descriptions for the current repository
  const jsonOptions = {
    ignore: ['node_modules', '.git', 'tmp'],
    format: 'json',
    output: 'descriptions.json',
  };

  console.log('Generating JSON descriptions...');
  const jsonDescriptions = await describeRepo(repoPath, jsonOptions);
  saveOutput(jsonDescriptions, jsonOptions.output, jsonOptions.format);
  console.log(`JSON descriptions saved to ${jsonOptions.output}`);

  // Scenario 2: Generate Markdown descriptions with a summary and table format
  const markdownOptions = {
    format: 'markdown',
    output: 'descriptions.md',
    summary: true,
    table: true,
    ignore: ['node_modules', '.git'], // You can specify ignore patterns here too
  };

  console.log('Generating Markdown descriptions...');
  const markdownDescriptions = await describeRepo(repoPath, markdownOptions);
  saveOutput(
    markdownDescriptions,
    markdownOptions.output,
    markdownOptions.format,
    markdownOptions.summary
  );
  console.log(`Markdown descriptions saved to ${markdownOptions.output}`);

  // Scenario 3: Generate descriptions for a remote GitHub repository
  const remoteRepoPath = 'https://github.com/ioncakephper/repo-description';
  const remoteOptions = {
    cloneDir: './cloned_repos', // Directory to clone the remote repo into
    format: 'json',
    output: 'remote-repo-descriptions.json',
  };

  console.log(`Generating descriptions for ${remoteRepoPath}...`);
  const remoteDescriptions = await describeRepo(remoteRepoPath, remoteOptions);
  saveOutput(remoteDescriptions, remoteOptions.output, remoteOptions.format);
  console.log(
    `Remote repository descriptions saved to ${remoteOptions.output}`
  );
}

runDescription();

As a Command-Line Interface (CLI)

Use the repo-describer command directly in your terminal:

# Generate JSON descriptions for the current repository and output to descriptions.json
repo-describer . -o descriptions.json -f json

# Generate Markdown descriptions for a remote GitHub repository, clone it to a specific directory, and include a summary and table format
repo-describer https://github.com/ioncakephper/repo-description -c ./cloned_repos -o repo-descriptions.md -f markdown --summary --table

# Generate descriptions for the current repository, ignoring specific patterns, and update a markdown-magic config file
repo-describer . -i "dist" "build" --update-config ./md.config.js --transform-name myDescriptions

# Display help information
repo-describer --help

Configuration

repo-description requires an API key from Groq to function. Follow these steps to configure your API key:

Obtain an API Key: Visit https://console.groq.com/keys and create a new API key.
Create .env file: In the root directory of your project (or where you run repo-describer), create a file named .env.
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

Usage: repo-describer [options] <repo>

Generate AI-based descriptions for repository files

Arguments:
  repo                  Path to local folder or remote GitHub repo URL

Options:
  -c, --clone-dir <dir>   Directory to clone remote repos into (default: "./tmp")
  -f, --format <type>   Output format: json or markdown (default: "json")
  -h, --help            display help for command
  -i, --ignore <patterns...>  Ignore patterns (default: ["node_modules",".git"])
  -o, --output <file>   Output file (e.g., descriptions.json or descriptions.md)
  -s, --summary         Include summary at top (markdown only) (default: false)
  --table               Use table format for markdown output (default: false)
  --transform-name <name> Transform name inside config (default: "descriptions")
  --update-config <path> Path to markdown-magic.config.js to update
  -V, --version         output the current version

Arguments

| Name | Type | Description | Default | | :----- | :------- | :--------------------------------------------- | :------ | | repo | string | Path to local folder or remote GitHub repo URL | N/A |

Options

Helpful Scripts

describe — Update repository descriptions in md.config.js transformDefaults for fileTreeExtended. (line 92)
```
node src/cli.js . --update-config md.config.js --transform-name fileTreeExtended
```
describe:file — Generates AI-powered descriptions for repository files and outputs them in various formats. (line 86)
```
node src/cli.js . --output _descriptions.json
```
docs — Generates documentation by processing Markdown files with markdown-magic. (line 91)
```
npx [email protected] **/*.md -c md.config.js
```
format — Formats the codebase using Prettier. (line 89)
```
prettier --write .
```
lint — Lints the codebase for potential errors and style violations. (line 87)
```
eslint src/ **/*.js **/*.json
```
lint:fix — Lints the codebase and automatically fixes fixable issues. (line 88)
```
eslint --fix src/ **/*.js **/*.json
```
prep — Prepares the codebase by generating documentation, linting, and formatting. (line 90)
```
npm run describe:file && npm run docs && npm run lint:fix && npm run format
```
test — Runs the test suite using Jest. (line 85)
```
jest --passWithNoTests
```

Contributing

We welcome contributions to repo-description! Please see our CONTRIBUTING.md for guidelines on how to contribute, including reporting bugs, suggesting enhancements, and making code contributions.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

@babel/preset-env — A Babel preset for each environment.
@eslint/js — ESLint JavaScript language implementation
babel-jest — Jest plugin to use babel for transformation.
commander — the complete solution for node.js command-line programs
dotenv — Loads environment variables from .env file
eslint — An AST-based pattern checker for JavaScript.
eslint-config-prettier — Turns off all rules that are unnecessary or might conflict with Prettier.
eslint-plugin-jsonc — ESLint plugin for JSON, JSONC and JSON5 files.
eslint-plugin-yaml — Lint YAML files
globals — Global identifiers from different JavaScript environments
groq-sdk — The official TypeScript library for the Groq API
jest — Delightful JavaScript Testing.
jsonc-eslint-parser — JSON, JSONC and JSON5 parser for use with ESLint plugins
markdown-magic-install-extended — Extended INSTALL transform for markdown-magic that generates install instructions from package.json with flexible options
markdown-magic-scripts — Automatically generate a dynamic, customizable dashboard of your npm scripts in your README.md using this markdown-magic transform. Keep your project documentation in sync with your package.json.
markdown-magic-transform-acknowledgements — A markdown-magic transform that auto-generates an Acknowledgements section for contributors, dependencies, and custom entries.
markdown-magic-transform-badges — No description available
markdown-magic-transform-treefile-extended — A markdown-magic transform to generate a dynamic file tree in your markdown files. This extended version provides additional options for customizing the output.
prettier — Prettier is an opinionated code formatter
prettier-plugin-packagejson — Prettier package.json plugin to make the order of properties nice.
yaml-eslint-parser — A YAML parser that produces output compatible with ESLint

Project Structure

repo-description/
├── __tests__
│   ├── .gitkeep (66 B)
│   └── cli.test.js (792 B)
├── .qodo
│   ├── agents
│   └── workflows
├── src
│   ├── cli.js (2.7 KB)             # Handles command-line interface parsing and execution.
│   ├── describe.js (8.3 KB)
│   ├── index.js (308 B)
│   └── utils.js (0 B)
├── _descriptions.json (221 B)
├── .env (69 B)
├── .gitignore (2.1 KB)
├── .prettierrc.json (563 B)
├── babel.config.js (92 B)
├── CHANGELOG.md (2.3 KB)
├── CONTRIBUTING.md (2.9 KB)
├── eslint.config.js (1.1 KB)
├── LICENSE (1.0 KB)
├── md.config.js (438 B)
├── package-lock.json (297.6 KB)
├── package.json (3.1 KB)           # Defines project metadata, scripts, and dependencies.
├── README.md (16.6 KB)             # Provides an overview of the repository and its usage.
└── RULES_OF_CONDUCT.md (4.9 KB)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

repo-description

Features

Getting Started

Installation

Usage

As a JavaScript Module

As a Command-Line Interface (CLI)

Configuration

CLI API

Help Output

Arguments

Options

Helpful Scripts

Contributing

License

Acknowledgments

Project Structure