{"id":34870579,"url":"https://github.com/ioncakephper/repo-description","last_synced_at":"2026-04-23T06:33:23.664Z","repository":{"id":322115185,"uuid":"1088231053","full_name":"ioncakephper/repo-description","owner":"ioncakephper","description":" An AI-powered CLI tool that automatically generates clear, natural-language descriptions for every file within a given repository, enhancing code understanding and documentation.","archived":false,"fork":false,"pushed_at":"2025-11-20T03:23:00.000Z","size":548,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-27T07:58:37.958Z","etag":null,"topics":["ai","automation","cli","code-analysis","code-understanding","developer-tools","documentation","groq-api","javascript","nodejs","repository-description"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ioncakephper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T15:17:08.000Z","updated_at":"2025-11-06T10:54:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"73f2c7d6-5993-495a-b366-d4c37655b94e","html_url":"https://github.com/ioncakephper/repo-description","commit_stats":null,"previous_names":["ioncakephper/repo-description"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ioncakephper/repo-description","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Frepo-description","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Frepo-description/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Frepo-description/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Frepo-description/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioncakephper","download_url":"https://codeload.github.com/ioncakephper/repo-description/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioncakephper%2Frepo-description/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32169657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cli","code-analysis","code-understanding","developer-tools","documentation","groq-api","javascript","nodejs","repository-description"],"created_at":"2025-12-25T23:16:35.504Z","updated_at":"2026-04-23T06:33:23.658Z","avatar_url":"https://github.com/ioncakephper.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# repo-description\n\n\u003e 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.\n\n\u003c!-- doc-gen BADGES --\u003e\n[![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/ioncakephper/repo-description/ci.yml?branch=main\u0026style=for-the-badge)](https://github.com/ioncakephper/repo-description/actions) [![codecov](https://img.shields.io/codecov/c/github/ioncakephper/repo-description?branch=main\u0026style=for-the-badge)](https://codecov.io/gh/ioncakephper/repo-description) [![release](https://img.shields.io/github/v/release/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/releases) [![maintained](https://img.shields.io/github/commit-activity/y/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/graphs/commit-activity) [![stars](https://img.shields.io/github/stars/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/stargazers) [![forks](https://img.shields.io/github/forks/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/network/members) [![watchers](https://img.shields.io/github/watchers/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/watchers) [![last commit](https://img.shields.io/github/last-commit/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/commits) [![contributors](https://img.shields.io/github/contributors/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/graphs/contributors) [![issues](https://img.shields.io/github/issues/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/issues) [![pull requests](https://img.shields.io/github/issues-pr/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/pulls) [![repo size](https://img.shields.io/github/repo-size/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description) [![top language](https://img.shields.io/github/languages/top/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description) [![languages](https://img.shields.io/github/languages/count/ioncakephper/repo-description?style=for-the-badge)](https://github.com/ioncakephper/repo-description/search?l=)\n\u003c!-- end-doc-gen --\u003e\n\n## Features\n\n- **AI-Powered Descriptions**: Generates concise, natural-language summaries for individual files using advanced AI models.\n- **Flexible Output Formats**: Supports output in JSON or Markdown, allowing for easy integration into various workflows.\n- **Repository Agnostic**: Works with both local directories and remote GitHub repositories (automatically clones them).\n- **Customizable Ignoring**: Exclude specific files or directories (e.g., `node_modules`, `.git`) from the description process.\n- **Markdown-Magic Integration**: Seamlessly updates `markdown-magic.config.js` files to embed descriptions directly into your documentation.\n- **CLI \u0026 Module Usage**: Can be used as a standalone command-line tool or integrated as a JavaScript module within other projects.\n\n## Getting Started\n\n**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).\n\n### Installation\n\n- Install _globally_, making `repo-describer` available as a CLI on any path on your system:\n\n    \u003c!-- doc-gen INSTALL global=true --\u003e\n  ```bash\n  npm install -g repo-description\n  ```\n\n  ```bash\n  yarn add -g repo-description\n  ```\n    \u003c!-- end-doc-gen --\u003e\n\n- Install _locally_ in your repository, ready to use in your code.\n\n    \u003c!-- doc-gen INSTALL --\u003e\n  ```bash\n  npm install repo-description\n  ```\n\n  ```bash\n  yarn add repo-description\n  ```\n    \u003c!-- end-doc-gen --\u003e\n\n### Usage\n\n#### As a JavaScript Module\n\nYou can use `repo-description` directly in your JavaScript or Node.js projects:\n\n```javascript\nrequire('dotenv/config'); // Load environment variables\n\nconst { describeRepo, saveOutput } = require('repo-description');\n\nasync function runDescription() {\n  const repoPath = './'; // Current repository or path to a local folder\n\n  // Scenario 1: Generate JSON descriptions for the current repository\n  const jsonOptions = {\n    ignore: ['node_modules', '.git', 'tmp'],\n    format: 'json',\n    output: 'descriptions.json',\n  };\n\n  console.log('Generating JSON descriptions...');\n  const jsonDescriptions = await describeRepo(repoPath, jsonOptions);\n  saveOutput(jsonDescriptions, jsonOptions.output, jsonOptions.format);\n  console.log(`JSON descriptions saved to ${jsonOptions.output}`);\n\n  // Scenario 2: Generate Markdown descriptions with a summary and table format\n  const markdownOptions = {\n    format: 'markdown',\n    output: 'descriptions.md',\n    summary: true,\n    table: true,\n    ignore: ['node_modules', '.git'], // You can specify ignore patterns here too\n  };\n\n  console.log('Generating Markdown descriptions...');\n  const markdownDescriptions = await describeRepo(repoPath, markdownOptions);\n  saveOutput(\n    markdownDescriptions,\n    markdownOptions.output,\n    markdownOptions.format,\n    markdownOptions.summary\n  );\n  console.log(`Markdown descriptions saved to ${markdownOptions.output}`);\n\n  // Scenario 3: Generate descriptions for a remote GitHub repository\n  const remoteRepoPath = 'https://github.com/ioncakephper/repo-description';\n  const remoteOptions = {\n    cloneDir: './cloned_repos', // Directory to clone the remote repo into\n    format: 'json',\n    output: 'remote-repo-descriptions.json',\n  };\n\n  console.log(`Generating descriptions for ${remoteRepoPath}...`);\n  const remoteDescriptions = await describeRepo(remoteRepoPath, remoteOptions);\n  saveOutput(remoteDescriptions, remoteOptions.output, remoteOptions.format);\n  console.log(\n    `Remote repository descriptions saved to ${remoteOptions.output}`\n  );\n}\n\nrunDescription();\n```\n\n#### As a Command-Line Interface (CLI)\n\nUse the `repo-describer` command directly in your terminal:\n\n```bash\n# Generate JSON descriptions for the current repository and output to descriptions.json\nrepo-describer . -o descriptions.json -f json\n\n# Generate Markdown descriptions for a remote GitHub repository, clone it to a specific directory, and include a summary and table format\nrepo-describer https://github.com/ioncakephper/repo-description -c ./cloned_repos -o repo-descriptions.md -f markdown --summary --table\n\n# Generate descriptions for the current repository, ignoring specific patterns, and update a markdown-magic config file\nrepo-describer . -i \"dist\" \"build\" --update-config ./md.config.js --transform-name myDescriptions\n\n# Display help information\nrepo-describer --help\n```\n\n## Configuration\n\n`repo-description` requires an API key from [Groq](https://groq.com) to function. Follow these steps to configure your API key:\n\n1.  **Obtain an API Key**: Visit [https://console.groq.com/keys](https://console.groq.com/keys) and create a new API key.\n2.  **Create `.env` file**: In the root directory of your project (or where you run `repo-describer`), create a file named `.env`.\n3.  **Add API Key**: Add your Groq API key to the `.env` file in the format:\n    ```\n    GROQ_API_KEY=your_groq_api_key_here\n    ```\n\nEnsure your `.env` file is included in your `.gitignore` to prevent your API key from being committed to version control.\n\n## CLI API\n\n### Help Output\n\n```\nUsage: repo-describer [options] \u003crepo\u003e\n\nGenerate AI-based descriptions for repository files\n\nArguments:\n  repo                  Path to local folder or remote GitHub repo URL\n\nOptions:\n  -c, --clone-dir \u003cdir\u003e   Directory to clone remote repos into (default: \"./tmp\")\n  -f, --format \u003ctype\u003e   Output format: json or markdown (default: \"json\")\n  -h, --help            display help for command\n  -i, --ignore \u003cpatterns...\u003e  Ignore patterns (default: [\"node_modules\",\".git\"])\n  -o, --output \u003cfile\u003e   Output file (e.g., descriptions.json or descriptions.md)\n  -s, --summary         Include summary at top (markdown only) (default: false)\n  --table               Use table format for markdown output (default: false)\n  --transform-name \u003cname\u003e Transform name inside config (default: \"descriptions\")\n  --update-config \u003cpath\u003e Path to markdown-magic.config.js to update\n  -V, --version         output the current version\n```\n\n### Arguments\n\n| Name   | Type     | Description                                    | Default |\n| :----- | :------- | :--------------------------------------------- | :------ |\n| `repo` | `string` | Path to local folder or remote GitHub repo URL | N/A     |\n\n### Options\n\n| Name               | Type       | Description                                              | Default                    |\n| :----------------- | :--------- | :------------------------------------------------------- | :------------------------- |\n| `-c, --clone-dir`  | `string`   | Directory to clone remote repos into                     | `./tmp`                    |\n| `-f, --format`     | `string`   | Output format: json or markdown                          | `json`                     |\n| `-i, --ignore`     | `string[]` | Ignore patterns                                          | `['node_modules', '.git']` |\n| `-o, --output`     | `string`   | Output file (e.g., descriptions.json or descriptions.md) | N/A                        |\n| `-s, --summary`    | `boolean`  | Include summary at top (markdown only)                   | `false`                    |\n| `--table`          | `boolean`  | Use table format for markdown output                     | `false`                    |\n| `--transform-name` | `string`   | Transform name inside config                             | `descriptions`             |\n| `--update-config`  | `string`   | Path to markdown-magic.config.js to update               | N/A                        |\n| `-V, --version`    | `boolean`  | output the current version                               | `false`                    |\n\n## Helpful Scripts\n\n\u003c!-- doc-gen COMMANDS format=list --\u003e\n- `describe` — Update repository descriptions in md.config.js transformDefaults for fileTreeExtended. (line [92](./package.json#L92))\n\n  ```bash\n  node src/cli.js . --update-config md.config.js --transform-name fileTreeExtended\n  ```\n\n- `describe:file` — Generates AI-powered descriptions for repository files and outputs them in various formats. (line [86](./package.json#L86))\n\n  ```bash\n  node src/cli.js . --output _descriptions.json\n  ```\n\n- `docs` — Generates documentation by processing Markdown files with markdown-magic. (line [91](./package.json#L91))\n\n  ```bash\n  npx markdown-magic@3.7.0 **/*.md -c md.config.js\n  ```\n\n- `format` — Formats the codebase using Prettier. (line [89](./package.json#L89))\n\n  ```bash\n  prettier --write .\n  ```\n\n- `lint` — Lints the codebase for potential errors and style violations. (line [87](./package.json#L87))\n\n  ```bash\n  eslint src/ **/*.js **/*.json\n  ```\n\n- `lint:fix` — Lints the codebase and automatically fixes fixable issues. (line [88](./package.json#L88))\n\n  ```bash\n  eslint --fix src/ **/*.js **/*.json\n  ```\n\n- `prep` — Prepares the codebase by generating documentation, linting, and formatting. (line [90](./package.json#L90))\n\n  ```bash\n  npm run describe:file \u0026\u0026 npm run docs \u0026\u0026 npm run lint:fix \u0026\u0026 npm run format\n  ```\n\n- `test` — Runs the test suite using Jest. (line [85](./package.json#L85))\n\n  ```bash\n  jest --passWithNoTests\n  ```\n  \u003c!-- end-doc-gen --\u003e\n\n## Contributing\n\nWe welcome contributions to `repo-description`! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute, including reporting bugs, suggesting enhancements, and making code contributions.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n\u003c!-- doc-gen ACKNOWLEDGEMENTS --\u003e\n- [@babel/preset-env](https://www.npmjs.com/package/%40babel%2Fpreset-env) — A Babel preset for each environment.\n- [@eslint/js](https://www.npmjs.com/package/%40eslint%2Fjs) — ESLint JavaScript language implementation\n- [babel-jest](https://www.npmjs.com/package/babel-jest) — Jest plugin to use babel for transformation.\n- [commander](https://www.npmjs.com/package/commander) — the complete solution for node.js command-line programs\n- [dotenv](https://www.npmjs.com/package/dotenv) — Loads environment variables from .env file\n- [eslint](https://www.npmjs.com/package/eslint) — An AST-based pattern checker for JavaScript.\n- [eslint-config-prettier](https://www.npmjs.com/package/eslint-config-prettier) — Turns off all rules that are unnecessary or might conflict with Prettier.\n- [eslint-plugin-jsonc](https://www.npmjs.com/package/eslint-plugin-jsonc) — ESLint plugin for JSON, JSONC and JSON5 files.\n- [eslint-plugin-yaml](https://www.npmjs.com/package/eslint-plugin-yaml) — Lint YAML files\n- [globals](https://www.npmjs.com/package/globals) — Global identifiers from different JavaScript environments\n- [groq-sdk](https://www.npmjs.com/package/groq-sdk) — The official TypeScript library for the Groq API\n- [jest](https://www.npmjs.com/package/jest) — Delightful JavaScript Testing.\n- [jsonc-eslint-parser](https://www.npmjs.com/package/jsonc-eslint-parser) — JSON, JSONC and JSON5 parser for use with ESLint plugins\n- [markdown-magic-install-extended](https://www.npmjs.com/package/markdown-magic-install-extended) — Extended INSTALL transform for markdown-magic that generates install instructions from package.json with flexible options\n- [markdown-magic-scripts](https://www.npmjs.com/package/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.\n- [markdown-magic-transform-acknowledgements](https://www.npmjs.com/package/markdown-magic-transform-acknowledgements) — A markdown-magic transform that auto-generates an Acknowledgements section for contributors, dependencies, and custom entries.\n- [markdown-magic-transform-badges](https://www.npmjs.com/package/markdown-magic-transform-badges) — No description available\n- [markdown-magic-transform-treefile-extended](https://www.npmjs.com/package/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.\n- [prettier](https://www.npmjs.com/package/prettier) — Prettier is an opinionated code formatter\n- [prettier-plugin-packagejson](https://www.npmjs.com/package/prettier-plugin-packagejson) — Prettier package.json plugin to make the order of properties nice.\n- [yaml-eslint-parser](https://www.npmjs.com/package/yaml-eslint-parser) — A YAML parser that produces output compatible with ESLint\n\u003c!-- end-doc-gen --\u003e\n\n## Project Structure\n\n\u003c!-- doc-gen fileTreeExtended showSize=true showDescriptions=true descriptionsFile=_descriptions.json --\u003e\n```\nrepo-description/\n├── __tests__\n│   └── .gitkeep (66 B)\n├── .qodo\n│   ├── agents\n│   └── workflows\n├── src\n│   ├── cli.js (2.7 KB)             # Sets up the `repo-describer` CLI with Commander, parses arguments and options, and orchestrates repository description generation, output saving, and optional config updates.\n│   ├── describe.js (8.3 KB)        # [Generate] AI‑powered descriptions of a Git repository’s files, persist those descriptions, and update markdown‑magic configuration accordingly.\n│   ├── index.js (308 B)            # Export... the `describeRepo`, `saveOutput`, and `updateMarkdownMagicConfig` functions as the public API of the `repo-describer` library.\n│   └── utils.js (0 B)              # I’m happy to help, but I need to see the actual contents of **src\\utils.js** in order to craft an accurate one‑sentence “[action]…” description. Could you paste the file’s code (or at least the relevant portion) here?\n├── _descriptions.json (2.9 KB)     # Map each repository file to a concise description of its purpose.\n├── .env (69 B)                     # Sets the GROQ_API_KEY environment variable for API authentication.\n├── .gitignore (2.1 KB)\n├── .prettierrc.json (563 B)        # Configure Prettier to use single quotes, trailing commas (es5), an 80‑character line width, and enforce a specific ordering of fields in package.json via the prettier-plugin-packagejson.\n├── babel.config.js (92 B)          # Configure Babel to use the `@babel/preset‑env` preset with the target set to the current Node version.\n├── CHANGELOG.md (2.5 KB)           # [record] a chronological list of version releases with dates and the associated bug‑fix entries for each version.\n├── CONTRIBUTING.md (2.9 KB)        # [Guide] contributors on reporting bugs, suggesting enhancements, and submitting code changes via pull requests.\n├── eslint.config.js (1.1 KB)       # Configure ESLint with base and Prettier settings, and add specialized parsers and recommended rules for JavaScript, JSON/JSONC, and YAML files.\n├── LICENSE (1.0 KB)                # Granting permission to use, copy, modify, merge, publish, distribute, sublicense, and sell the software under the terms of the MIT License.\n├── md.config.js (438 B)            # Exports a configuration object that sets default badge styling and registers multiple markdown‑magic transform plugins for file trees, badges, installation, acknowledgements, and command scripts.\n├── package-lock.json (289.8 KB)    # [Locks] exact versions of the project’s direct and transitive npm dependencies to ensure reproducible, deterministic installations.\n├── package.json (3.0 KB)           # Specify the package metadata, entry points, scripts, and distribution settings for the AI‑powered “repo‑describer” CLI tool.\n├── README.md (17.7 KB)             # Introduces the AI‑powered CLI tool `repo‑description`, its purpose and usage overview, and displays project status badges.\n└── RULES_OF_CONDUCT.md (4.9 KB)    # [Establish] a comprehensive, harassment‑free code of conduct that pledges inclusive, respectful behavior and outlines acceptable and unacceptable actions for contributors.\n```\n\u003c!-- end-doc-gen --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Frepo-description","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioncakephper%2Frepo-description","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioncakephper%2Frepo-description/lists"}