This week, as part of my class on Open Source Development, I worked together with my classmate Mayank to contribute to each other's projects. Mayank's project, dev-mate-cli, is a command line (CLI) tool that reads source code files using AI and generates comments to make it easier to understand. For reference, my project, codeshift, is also a CLI tool that uses AI, except to translate source code files to other programming languages. Our task was to add an option to each other's tool that displays the number of tokens used to transform the source files. Tokens, in this context, refer to the chunks of text processed by AI to generate meaningful output.
mayank-Pareek
/
dev-mate-cli
A command line tool to quickly document your code
dev-mate-cli
A command-line tool that leverages OpenAI's Chat Completion API to document code with the assistance of AI models Watch this Demo video to view features.
Features
- Source Code Documentation: Automatically generate comments and documentation for your source code.
- Multiple File Processing: Handle one or multiple files in a single command.
-
Model Selection: Choose which AI model to use with the
--modelflag. -
Custom Output: Output the results to a file with the
--outputflag, or display them in the console.
Installation
-
Clone the repository:
git clone https://github.com/mayank-Pareek/dev-mate-cli.git cd dev-mate-cli -
Install dependencies:
npm install
-
Set up environment variables:
Create a
.envfile in the project’s root directory with the following configuration, getAPI_KEYandBASE_URLfrom model provider of your choice:API_KEY=your_api_key BASE_URL=base_url
-
Set up LLM configuration:
Open
config.jsonfile from the project’s root directory and edit default configuration to customize LLM. Visit your API Key…
In order to contribute to each other's projects, we were asked to file issues and pull requests. I had some prior experience with creating issues and pull requests, but this week, I became very familiar with the process.
Table of Contents
My Contributions
The contributions I made to Mayank's project were:
- Implementing the
--token-usagefeature - Importing program metadata for
--versionand--helpfrompackage.json - Filing issues for potential improvements
Reading Mayank’s Code
Before creating an issue for the feature, I began by reading Mayank's code. Mayank used TypeScript for his project, which I'm not overly accustomed to, but have used a little bit of here and there. His code was also split into several modules, a paradigm I found intimidating at first. I figured a good starting point would be to find the file where the API call to the AI was made, since I'd need the data returned from it. Aside from the feature I had to add, I noticed a few improvements that could be made to the project, and noted them down to create issues later.
Adding --token-usage to dev-mate-cli
To create his CLI tool, Mayank used the same npm module as me - commander.js. commander.js is a module for creating CLI tools with features like option and argument parsing. This made it easy for me to jump in and identify exactly where I needed to add my code. I had to register the -u/--token-usage option, check if it was passed, and if it was, print the token usage property returned by the API. Simple enough. I also made sure to stick as closely as possible to the project's code style.
I created the issue on GitHub and felt satisfied, but after seeing how detailed some of the issues other people created were, I feel like I should have gone into more detail. My pull request's description could have included additional context to explain the changes better.
In the future, I’ll ensure to add more detail explaining the context, expected behavior, and test cases for the changes, so collaborators can better understand the purpose of the pull request.
Add token info feature
#6
Add a new command-line flag: --token-usage or -t. When the program is run with the --token-usage/-t flag set, extra information will be reported to stderr about the number of tokens that were sent in the prompt and returned in the completion.
I'd like to work on this feature. Please let me know if you have any specific implementation guidelines.
Add support for `--token-usage`/`-u` flag
#12
Fixes #6.
Some considerations:
- I used the
-ushort flag since-twas in use. - This implementation does not print token usage if the
-oflag is used.
Another Improvement
After submitting my pull request, Mayank approved it quickly, but since the lab required practicing requesting changes to pull requests, I submitted another pull request based on one of the potential improvements I noted earlier, which was importing the program name and version from the package.json file for printing when using the --version flag. This way, when updating them you wouldn't have to do it across multiple files. I turned in the pull request, being unsure what I'd be asked to change, and Mayank made the excellent observation that the program description used in the help message could also be imported from the same file, and asked me to add the change to the pull request, which I did.
Import program version and name from package.json
#13
- Updated
tsconfig.jsonto allow importing JSON files as modules - Replaced name and version strings with variables imported from
package.json - Added name to
-voutput
Closes #7, Closes #9
For this change I had to edit the TypeScript configuration file tsconfig.json to allow importing .json files. It was fun learning a little bit more about how TypeScript works and how it can be configured.
Results
I was satisfied with my work on the --token-usage feature, but I realized later that it wasn't working as intended. Instead of printing the total tokens used for the entire command at the very end, it would print the tokens used after each input file was processed. This implementation works, but it's not quite what I envisioned. I let Mayank know, and thankfully, he seemed okay with the implementation.
Filing More Issues
I also filed a few other issues on the project:
- Suggested adding a
.env.examplefile with placeholder environment variables for easier setup. - Proposed moving the list of future enhancements from the
READMEto GitHub issues. - Noted that the project's
--versioncommand didn’t print the program name, which I fixed in my second pull request.
Create `.env.example` for easy setup
#10
Create a .env.example file containing placeholder key/value pairs to make project setup easier.
# .env.example
API_KEY=your_api_key
BASE_URL=https://openrouter.ai/api/v1
Move Future Enhancements from `README.md` to GitHub issues
#11
Consider removing Future Enhancements section from README.md and instead creating issues to document them.
`--version` and `-v` do not print program name
#9
--version and -v are supposed to print the program name but do not.
The output could look something like:
dev-mate-cli v0.1.0
Mayank's Contributions
Having integrated the --token-usage feature in Mayank's project, it was time to have him contribute to my project. He helped out by contributing the following:
- Added the
--token-usage feature. - Fixed code style inconsistencies based on my feedback.
- Addressed major bug with output file overwriting.
Adding --token-usage to codeshift
Mayank's changes for the most part were pretty good, barring some code style inconsistencies, which I asked him to change when reviewing the pull request. His implementation of --token-usage was similar to mine, meaning the output was logged after each file. Since this was unintentional on my part, I ended up changing the code to work as I originally intended. Mayank was kind enough to also work on a couple other issues I had open.
Issue 10 - Add Token Usage Option
#11
This pull request adds a new --token-usage flag (with a shorthand -t option) to the program, allowing users to see the token usage information when making requests to the API. This flag enables the program to display the number of prompt tokens, completion tokens, and total tokens used by the request.
- Added both a long flag
--token-usageand a short flag-tto the program for reporting token usage. - Added logic to check for the
--token-usageflag in the program. If the flag is present and the response contains token usage data, the program will now extract and display it in the console usingconsole.error. - The relevant data is extracted from
chunk?.x_groq?.usagein the response, following GROQ API's response structure. - Updated the README.md file to document the new
--token-usage (-t)option.
- No breaking changes were introduced in this pull request.
- This PR closes #10 by adding the requested token usage option.
Please let me know if any there are any additional changes required.
Replace writeFile with appendFile for file output
#13
This pull request modifies the program to append data to the output file when multiple input files are provided and the --output flag is used. Previously, the program would overwrite the output file with each input file’s data. Now, it appends the results from each input to the specified output file.
- Updated the logic to use
fs.appendFileinstead offs.writeFilewhen multiple input files are passed along with the--outputflag. This ensures that data from all input files is written sequentially to the same output file, rather than overwriting previous content. - Added logic to output a warning message if the output file is not empty. File is checked using
fs.readFilefor empty check.
This fixes #12 , let me know if further changes are required.
Remove logging output if output file flag passed
#14
If --output flag is passed the program will write only to output file, these changes resolve #8.
You can read his blog post about them here:
Mayank's Pull Requests were clear and straightforward. It was easy to understand the intentions behind the changes he made.
Fixing Output File Overwriting Bug
I was glad Mayank decided to help out and take on additional issues. He helped me identify a major bug in my program: When specifying a file to output to, the output from the last input file would overwrite that of the previous files. He fixed this by making it append to the specified output file, and also added a console warning message.
When creating my project, I aimed for the tool to behave like Unix commands (mv and cp), which remain silent unless errors occur. While Mayank’s fix improved usability by adding feedback, I felt it diverged from the tool’s overall intended behavior. After reflecting on both approaches, I modified the program to preserve my original goal of overwriting content while incorporating Mayank’s fix.
Conclusion
Despite the challenges I faced, I’m proud of the experience I gained and the contributions I was able to make. These lessons will undoubtedly help me become a more effective open-source contributor in the future.
In summary, this experience gave me not only a deeper understanding of creating and reviewing pull requests, but also a better appreciation for the importance of careful code reviews and testing. I feel much more confident in reading and working with other people's code, but I need to be more critical of both the changes I make, and the changes I accept. I look forward to applying these lessons to future contributions, as I continue to grow both as a developer and a collaborator.
Top comments (0)