diff --git a/.husky/pre-commit b/.husky/pre-commit index 3742e44..a1d719d 100644 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,3 +1,3 @@ -npm run lint npm run format +npm run lint npm run test diff --git a/.prettierignore b/.prettierignore index e710a67..1b3d509 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,8 @@ +_examples/ +.git/ +.github/ +.husky/ +.vscode/ node_modules/ package.json package-lock.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..be55744 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,9 @@ +{ + "recommendations": [ + "esbenp.prettier-vscode", + "dbaeumer.vscode-eslint", + "streetsidesoftware.code-spell-checker", + "yzhang.markdown-all-in-one", + "DavidAnson.vscode-markdownlint" + ] +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..3f71608 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,70 @@ +# Code of Conduct - gimme_readme + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +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 + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances +- 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 + +## Our Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban +temporarily or permanently any contributor for other behaviors that they deem +inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at . +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/), version +[1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) and +[2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md), +and was generated by [contributing-gen](https://github.com/bttger/contributing-gen). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4b937aa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,284 @@ + + +# Contributing to gimme_readme + +First off, thanks for taking the time to contribute! ❤️ + +All contributions are encouraged and valued. Please see the [Table of Contents](#table-of-contents) for different ways to contribute and read the relevant sections before making your contribution. + +Following this guide will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉 + +> If you like the project, but don't have time to contribute, no worries! There are other easy ways to support the project which we would also be very happy about. Please consider: +> +> - Starring the project +> - Tweeting about it +> - Referring this project in your project's readme +> - Mentioning the project at local meetups and tell your friends/colleagues + + + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [I Have a Question](#i-have-a-question) +- [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Your First Code Contribution](#your-first-code-contribution) + - [Improving The Documentation](#improving-the-documentation) + +## Code of Conduct + +This project and everyone participating in it is governed by the [gimme_readme Code of Conduct](https://github.com/peterdanwan/gimme_readme/blob/main/CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. Please report unacceptable behavior to . + +## I Have a Question + +> If you want to ask a question, we assume that you have read the available [Documentation](https://github.com/peterdanwan/gimme_readme) and [Examples](https://github.com/peterdanwan/gimme_readme/blob/main/_examples/README.md). + +Before asking a question, please search for existing [Issues](https://github.com/peterdanwan/gimme_readme/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. + +If you still need to ask a question or require clarification, we recommend: + +1. Opening an [Issue](https://github.com/peterdanwan/gimme_readme/issues/new). +2. Providing as much context as you can about what you're running into. (Posting code snippets, screenshots, videos etc. are welcome!). +3. Providing project and platform versions (nodejs, npm, etc), depending on what seems relevant. + +We will then take care of the issue as soon as possible. + +## I Want To Contribute + +> ### Legal Notice +> +> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. + +### Reporting Bugs + + + +#### Before Submitting a Bug Report + +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g., using incompatible environment components/versions (ensure that you have read the [documentation](https://github.com/peterdanwan/gimme_readme). If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/peterdanwan/gimme_readme/issues?q=label%3Abug). +- Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have discussed the issue. +- Collect information about the bug: + - Stack trace (Traceback) + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) + - Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant. + - Possibly your input and the output + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? + + + +#### How Do I Submit a Good Bug Report? + +> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to . + + + +We use GitHub issues to track bugs and errors. If you run into an issue with the project: + +- Open an [Issue](https://github.com/peterdanwan/gimme_readme/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the _reproduction steps_ that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. +- Provide the information you collected in the previous section. + +Once it's filed: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced. +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution). + + + +### Suggesting Enhancements + +This section guides you through submitting an enhancement suggestion for gimme_readme, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions. + + + +#### Before Submitting an Enhancement + +- Ensure you are using the latest version of `gimme_readme` +- Read the [documentation](https://github.com/peterdanwan/gimme_readme) and [examples](https://github.com/peterdanwan/gimme_readme/blob/main/_examples/README.md) carefully to find out if a feature is already covered through an individual configuration. +- Search the [list of existing issues](https://github.com/peterdanwan/gimme_readme/issues?q=is%3Aissue+label%3Aenhancement) to see if an enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one and like the original issue's description. +- Determine if your idea fits with the scope of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library. + + + +#### How Do I Submit a Good Enhancement Suggestion? + +Enhancement suggestions are tracked using [GitHub issues](https://github.com/peterdanwan/gimme_readme/issues), just like [bugs](#reporting-bugs). + +To log a good issue, we suggest: + +- **Adding a clear and descriptive title** for the issue to identify the suggestion. +- **Providing a step-by-step description of the suggested enhancement** with as many details as possible. +- **Describing the current behavior** and **explaining the behavior you expect to see instead**, and why. You can also tell clarify which alternatives do not work for you. +- **Including code snippets, screenshots, videos, and/or animated GIFs** to help demonstrate the steps of possible solutions or end results. +- **Explain why this enhancement would be useful** to most gimme_readme users. You may also want to reference other projects that solved it better and which could serve as inspiration. + + + +### Your First Code Contribution + +We're excited to help you make your first code contribution! Here's a comprehensive guide to get you started: + +#### Prerequisite Tools + +- [Node.js (LTS version recommended)](https://nodejs.org/en/download/package-manager) +- [Git](https://git-scm.com/) +- [Visual Studio Code](https://code.visualstudio.com/) - we have some [recommended extensions](./.vscode/extensions.json) to install + +#### Development Setup + +1. Fork this repository, and clone your _forked_ repository to your local machine. Follow the guide [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) if you are unsure how to do this. +2. After [cloning your forked repository to your local machine](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository), navigate to the _root_ of the cloned repository and run the following: + + ```sh + # Remove the pre-existing, global installation of the gimme_readme repository. + npm uninstall -g gimme_readme + + # Install the necessary node_modules + npm i + + # Simulate the environment as if gimme_readme was installed globally via `npm i -g gimme_readme` + # You can now use the `gr-ai` executable, and changes to your source code should be reflected when you make changes to the repo + # If your changes aren't reflected after changing the source code, repeat the commands above in sequence. + npm link + ``` + +#### Making and Testing Changes + +1. Create a new branch for your feature/fix: + + ```sh + # Create a new branch, that is based off of your local main branch + git checkout -b main + ``` + + > We maintain that it's always a best practice to _never_ work off of your `main` branch, and instead, work on a separate branch. You should do your best to ensure that your `local main` branch, and your `downstream main branch` on GitHub, is in-sync with the [upstream main branch](https://github.com/peterdanwan/gimme_readme). + +2. After adding new code or modifying existing code, please try to add a `test` case for these changes (if applicable). Run the following commands to ensure your current changes are: formatted properly, have no code lint (i.e., potential for bugs), and don't break any new or existing test cases: + + ```sh + # To spot any formatting issues and automatically fix them + npm run format + + # To spot any code issues (performed after formatting) + npm run lint + + # To see if any of the existing tests are broken/need to be updated based on your update + npm run test + ``` + + > NOTE 1: with regards to linting, there may be an off chance that you want to _ignore_ a certain suggestion. We maintain that we normally don't suggest doing this, in favour of avoiding code that requires a linting rule to be ignored altogether. However, if it is _absolutely necessary_ for you to ignore a rule so that ESLint does not complain, please see this [guide](https://eslint.org/docs/latest/use/configure/rules). + > + > NOTE 2: All of these scripts are defined in [package.json](./package.json), under the "scripts" section. + +3. When you're ready to make a commit, this repository has been configured to run a [pre-commit hook](.husky/pre-commit) which _also_ runs the following _automatically_, just in case you haven't done so already: + + ```sh + # Formats all JavaScript files in src/ and tests/ directories using Prettier + # This will automatically fix formatting issues like indentation, spacing, and quotes + npm run format + + # Runs ESLint on all JavaScript files in src/ and tests/ directories (run deliberately after formatting). + # This checks for potential errors, bugs, and code style violations + npm run lint + + # To see if any of the existing tests are broken/need to be updated based on your update + npm run test + ``` + + > This pre-commit hook aims to ensure that your commit passes the [continuous integration tests](.github/workflows/ci.yml). If your code fails the `lint` or `test` commands, you'll notice that your commit will not go through. You'll need to address these issues _first_, and then redo your commit. + +#### Visual Studio Code Editor Integration + +As mentioned in [Prerequisite tools](#prerequisite-tools), part of developing `gimme_readme` involves using `Visual Studio Code` as your editor. When you open the `gimme_readme` repository with `Visual Studio Code`, it should suggest that you install several extensions if they haven't been installed already. `Visual Studio Code` specific configurations can be found in the `.vscode` folder. + +Here are some explanations of the file at the time of writing: + +1. Required Extensions: ([.vscode/extensions.json](.vscode/extensions.json)) + + ```json + { + "recommendations": [ + "esbenp.prettier-vscode", // Prettier formatter integration + "dbaeumer.vscode-eslint", // ESLint integration + "streetsidesoftware.code-spell-checker" // Spell checking + "yzhang.markdown-all-in-one", // Enhanced Markdown support (e.g., shortcuts to make text bold) + "DavidAnson.vscode-markdownlint" // Markdown linting + ] + } + ``` + + > If you don't have these extensions installed, Visual Studio Code will alert you to install these extensions. + +2. Workspace Settings: ([.vscode/settings.json](.vscode/settings.json)) + + ```json + { + "editor.insertSpaces": true, // Use spaces instead of tabs + "editor.tabSize": 2, // 2 spaces per tab + "editor.detectIndentation": false, // Don't auto-detect indentation + "editor.defaultFormatter": "esbenp.prettier-vscode", // Use Prettier as default formatter + "editor.formatOnSave": true, // Auto-format files when saving + "editor.codeActionsOnSave": { + "source.fixAll": "explicit" // Auto-fix linting issues on save + }, + "files.eol": "\n", // Use Unix-style line endings + "files.insertFinalNewline": true // Add newline at end of files + } + ``` + +3. JavaScript specific code snippet ([.vscode/javascript.code-snippets](.vscode/javascript.code-snippets)) + + ```json + { + "Insert Current File Path Comment": { + "prefix": "rpath", + "body": ["// ${RELATIVE_FILEPATH/[\\\\]/\\//g}"], + "description": "Inserts a comment with the relative path of the current file" + } + } + ``` + + > Type `rpath` and press `Enter` to insert the current file's path as a comment. + +Having these configuration files ensures that: + +- Code is automatically formatted on save using Prettier +- ESLint problems are highlighted as you type +- Common coding errors are caught early +- All developers use consistent editor settings +- Spell checking helps catch typos in comments and strings +- Markdown files are properly formatted and follow best practices + +NOTE: If the automatic formatting or linting isn't working: + +1. Make sure you've installed the recommended extensions +2. Try reloading VS Code +3. Verify that the file you're editing is included in the paths specified in your npm scripts + +### Improving The Documentation + +Documentation is crucial for our project's success. Consider updating: + +1. The [_main_ README.md](./README.md) +2. The [\_examples folder's README.md](./_examples/README.md) + +The following types of changes are welcome: + +- adding missing documentation +- clarifying existing documentation +- fixing grammatical and/or spelling mistakes + + + +## Attribution + +This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)! diff --git a/README.md b/README.md index f9f37f3..d70f440 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,9 @@ See our [0.1 Release Demo](https://youtu.be/S6v-u9o_Xx8)! 3. [Example Usage](#3-example-usage) 4. [Supported Models by Providers](#4-supported-models-by-providers) 5. [Contributing](#5-contributing) -6. [Testing Locally](#6-testing-locally) -7. [Author](#7-author) +6. [Code of Conduct](#6-code-of-conduct) +7. [License](#7-license) +8. [Author](#8-author) ## 1. Getting Started @@ -53,9 +54,10 @@ To get started with `gimme_readme`, follow these steps: | `-o`, `--outputFile ` | Specify the file to output the generated README to | | `-m`, `--model ` | Choose a free-tier AI model to use (e.g., gemini, openai, grok) | | `-p`, `--prompt ` | Provide a custom prompt to the AI | +| `-pf`, `--promptFile ` | Specify a prompt file | | `-c`, `--config` | Show the location of the configuration file and provide links to examples | | `-t`, `--temperature ` | Set the level of determinism for the AI (value between 0 and 1) | -| `-tkn`, `--token` | get information on the tokens consumed (i.e., prompt, completion, & total tokens) | +| `-tkn`, `--token` | Get information on the tokens consumed (i.e., prompt, completion, & total tokens) | | `-h`, `--help` | Display help for the command | ## 3. Example Usage @@ -103,53 +105,17 @@ gr-ai -f example.js anotherFile.py -o README.md -m llama3-8b-8192 --token ## 5. Contributing -We welcome contributions to improve `gimme_readme`! To contribute, please follow these steps: +We welcome contributions to improve `gimme_readme`! To get started with contributing, we ask that you read our [contributing guide](./CONTRIBUTING.md) -1. Check the [existing issues](https://github.com/peterdanwan/gimme_readme/issues) to see if your issue or feature request has already been logged. -2. If your issue or feature request is already listed, add your comments or create a pull request with your proposed changes. -3. If your issue or suggestion is not listed, feel free to create a new issue. If possible, provide a pull request that addresses the issue. -4. To test your local changes to `gimme_readme`, please read section [6. Testing Locally](#6-testing-locally) +## 6. Code of Conduct -When making a pull request, please ensure that your changes are well-documented and adhere to the coding standards of the project. +We are committed to providing a welcoming and inclusive experience for everyone. By participating in this project, you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md). -## 6. Testing Locally +## 7. License -If you are trying to contribute to the `gimme_readme` repository, please follow the following steps in sequence to test your changes locally: +This project is licensed under the MIT license. You are free to use, modify, and distribute this code, subject to the terms in the [LICENSE](./LICENSE) file. -1. Ensure you have [Node.js installed](https://nodejs.org/en/download/package-manager) -2. Fork this repository, and clone your _forked_ repository. -3. On your machine, after cloning your forked repository, navigate to the _root_ of the cloned repository and run the following: - - ```sh - # Remove the pre-existing, global installation of the gimme-readme repository. - npm uninstall -g gimme_readme - - # Install the necessary node_modules - npm i - - # Simulate the environment as if gimme-readme was installed globally via `npm i -g gimme_readme` - # You can now use the `gr-ai` executable, and changes to your source code should be reflected when you make changes to the repo - # If your changes aren't reflected after changing the source code, repeat the commands above in sequence. - npm link - ``` - -4. After adding any new code, please try to have a `test` case made for this code as well. -5. When you're ready to make a commit, this repository has been set-up to run a [pre-commit hook](.husky/pre-commit) that runs the following: - - ```sh - # To spot any code issues - npm run lint - - # To spot any formatting issues - npm run format - - # To see if any of the existing tests are broken/need to be updated based on your update - npm run test - ``` - - > This pre-commit hook aims to ensure that your commit passes the [continuous integration tests](.github/workflows/ci.yml). - -## 7. Author +## 8. Author Developed by [Peter Wan](https://github.com/peterdanwan). diff --git a/_examples/README.md b/_examples/README.md index d48d7a4..5bc283c 100644 --- a/_examples/README.md +++ b/_examples/README.md @@ -48,3 +48,19 @@ gr-ai -m gemini-1.5-flash -f tests/unit/_gr.test.js -o explanation.md -t 0.1 ``` ![explain-file](assets/images/explain-file.png) + +## Use the text from a custom prompt file, and send files within a particular folder + +```sh +gr-ai -pf prompt.md -f src/ -o explain.md +``` + +![send-a-prompt-file-and-folder](assets/images/send-a-prompt-file-and-folder.png) + +## Make a prompt directly from the command-line + +```sh +gr-ai -p "Can you provide your best explanation of a static analysis tool, with examples in JavaScript?" -o explanation.md +``` + +![prompt-from-command-line](assets/images/prompt-from-command-line.png) diff --git a/_examples/assets/images/prompt-from-command-line.png b/_examples/assets/images/prompt-from-command-line.png new file mode 100644 index 0000000..fa4cff4 Binary files /dev/null and b/_examples/assets/images/prompt-from-command-line.png differ diff --git a/_examples/assets/images/send-a-prompt-file-and-folder.png b/_examples/assets/images/send-a-prompt-file-and-folder.png new file mode 100644 index 0000000..5635670 Binary files /dev/null and b/_examples/assets/images/send-a-prompt-file-and-folder.png differ diff --git a/eslint.config.mjs b/eslint.config.mjs index 8c5b208..8f0adbd 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -16,10 +16,15 @@ export default [ }, }, { - // add for issue 31 - TOML configuration - files: ['*.gr.toml'], - languageOptions: { - parser: 'toml-eslint-parser', - }, + ignores: [ + '_examples/**', + '.git/**', + '.github/**', + '.husky/**', + '.vscode/**', + 'node_modules/**', + 'package.json', + 'package-lock.json', + ], }, ];