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

• Install globally, making repo-describer available as a CLI on any path on your system:

  npm install -g repo-description

  yarn add -g repo-description

• Install locally in your repository, ready to use in your code.

  npm install repo-description

  yarn add 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:

1. Obtain an API Key: Visit 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

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

Name	Type	Description	Default
-c, --clone-dir	string	Directory to clone remote repos into	./tmp
-f, --format	string	Output format: json or markdown	json
-i, --ignore	string[]	Ignore patterns	['node_modules', '.git']
-o, --output	string	Output file (e.g., descriptions.json or descriptions.md)	N/A
-s, --summary	boolean	Include summary at top (markdown only)	false
--table	boolean	Use table format for markdown output	false
--transform-name	string	Transform name inside config	descriptions
--update-config	string	Path to markdown-magic.config.js to update	N/A
-V, --version	boolean	output the current version	false

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 markdown-magic@3.7.0 **/*.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)             # preserve empty test directory structure in version control.
│   └── cli.test.js (807 B)         # test CLI functionality to ensure correct behavior.
├── .qodo
│   ├── agents
│   └── workflows
├── src
│   ├── cli.js (2.7 KB)             # implement command-line interface logic for running the tool.
│   ├── describe.js (8.3 KB)        # handle repository file analysis and description generation.
│   ├── index.js (308 B)            # export main module entry point for external usage.
│   └── utils.js (0 B)              # provide utility functions to support core operations.
├── _descriptions.json (1.5 KB)
├── .env (69 B)
├── .gitignore (2.1 KB)             # define files and directories to be ignored by Git version control.
├── .prettierrc.json (563 B)        # configure Prettier code formatting rules for consistent style.
├── babel.config.js (92 B)          # set up Babel configuration for JavaScript transpilation.
├── CHANGELOG.md (2.6 KB)
├── CONTRIBUTING.md (2.9 KB)        # outline contribution guidelines for developers working on the project.
├── eslint.config.js (1.1 KB)       # configure ESLint rules for linting JavaScript and JSON files.
├── LICENSE (1.0 KB)                # declare project licensing terms under the MIT License.
├── md.config.js (438 B)            # configure markdown-magic settings for automated documentation updates.
├── package-lock.json (297.6 KB)    # lock exact versions of installed npm dependencies.
├── package.json (3.1 KB)           # define project metadata, dependencies, and npm scripts.
├── README.md (17.7 KB)             # introduce the project, its purpose, features, and usage instructions.
└── RULES_OF_CONDUCT.md (4.9 KB)    # establish community standards and expected behavior for contributors.