Forem: Cleo Buenaventura

A Final Challenge: Release

Cleo Buenaventura — Mon, 09 Dec 2024 22:38:06 +0000

The final week is here, which brings my issue to a conclusion. I think I did a pretty good job with achieving the goals I aimed for in the beginning of this challenge. This task focused on improving how Onlook detects and handles Tailwind class names, particularly in cases involving dynamic expressions or template literals. The goal was to provide better error detection, ensure static classes are correctly extracted, and allow users to navigate directly to the relevant code sections in their editor. Along the way, I tackled challenges, refined my technical skills, and interacted with the Onlook maintainer to ensure my contributions aligned with the project's goals.

onlook-dev / onlook

The open source, local-first Figma for React. Design directly in your live React app and publish your changes to code.

Onlook

The first browser-powered visual editor
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

The open-source visual editor for your React Apps

Seamlessly integrate with any website or web app running on React + TailwindCSS, and make live edits directly in the browser DOM. Customize your design, control your codebase, and push changes your changes without compromise.

Onlook.Studio.Component.Demo.for.GitHub.mp4

Built With

Stay up-to-date

Onlook officially launched our first version of Onlook on July 08, 2024 and we've shipped a ton since then. Watch releases of this repository to be notified of future updates, and you can follow along with us on LinkedIn or Substack where we write a weekly newsletter.

Getting Started

Installation

Visit onlook.dev to download the app.
Run locally following this guide

Usage

Onlook will run on any React project, bring your own React project…

View on GitHub

Achieving My Goals

The primary goal was to improve how Onlook detects and handles Tailwind class names within React components, particularly when dynamic expressions or template literals are used. I believe I achieved this effectively through:

Error Detection for Dynamic Classes: Implemented logic to detect and return errors when dynamic expressions are present in class names. This ensures users are informed and can take appropriate action.
Static Class Extraction: Ensured that static classes wrapped in TemplateLiteral constructs are parsed and returned when no dynamic variables are present.
Source Navigation: Added a button in the UI that lets users navigate directly to the relevant code when dynamic variables are detected.

By the end of this task, the feature was functional, user-friendly, and aligned with Onlook's architecture.

Methods

Pull Request: https://github.com/onlook-dev/onlook/pull/849

Class Parsing Logic

The main function at the core of this feature is getNodeClasses, which is responsible for traversing a JSX element's AST (Abstract Syntax Tree) and extracting the className attribute. The function handles multiple scenarios:

Missing className Attribute: If no className attribute exists in the JSX element, the function immediately returns an error, allowing the system to handle this case gracefully.
Static Classes: If the className is a simple string or part of a TemplateLiteral without any dynamic variables, the function extracts the classes and returns them as a list. For TemplateLiteral, the function parses its quasis (static portions) to ensure all classes are properly extracted.
Dynamic Classes: If a TemplateLiteral contains dynamic expressions (e.g., ${variable}), the function detects this and returns an error with a specific reason. This ensures users are notified of unsupported dynamic constructs in className.

Here’s the relevant portion of the function that handles TemplateLiteral cases which I was responsible for:

if (
    t.isJSXExpressionContainer(classNameAttr.value) &&
    t.isTemplateLiteral(classNameAttr.value.expression)
) {
    const templateLiteral = classNameAttr.value.expression;

    if (templateLiteral.expressions.length > 0) {
        return {
            type: 'error',
            reason: 'Dynamic classes detected. Dynamic variables in the className prevent extraction of Tailwind classes.',
        };
    }

    const quasis = templateLiteral.quasis.map((quasi) => quasi.value.raw.split(/\s+/));
    return {
        type: 'classes',
        value: quasis.flat().filter(Boolean),
    };
}

This logic ensures the function is robust enough to handle both valid and invalid class declarations while giving clear feedback for edge cases. This modular design not only simplifies testing but also allows for easy extensions if new requirements arise.

UI Integration

To integrate this functionality into the UI:

I updated the TailwindInput component where the textarea is implemented to handle and display warnings when dynamic classes were detected.
Added a button labeled "Go to source" that appears alongside the warning. Clicking this button navigates users to the exact location in their code where the dynamic class is defined.

What I learned

One of the most valuable lessons I gained from this experience was the importance of understanding code deeply and learning how to dig through layers of files in a codebase. Open-source projects can be intricate, with logic spread across multiple files and modules. Successfully implementing this feature required me to navigate the project's structure, understand its existing logic, and integrate my changes seamlessly. It was a constant process of reading, analyzing, and piecing together different parts of the system.

A key breakthrough for me was discovering the capabilities of @babel/types. Specifically, the isTemplateLiteral method allowed me to identify template literals within the JSX AST (Abstract Syntax Tree). This discovery greatly simplified my logic for handling className attributes. Without understanding how to leverage this utility, implementing a robust solution would have been significantly more challenging.

Another critical step was learning how to extract static classes from a TemplateLiteral. Using the quasis property of the TemplateLiteral node, I was able to parse the static portions of the string and filter out dynamic variables. This approach ensured that I could reliably return static classes while gracefully handling dynamic constructs.

More about Babel's AST documentation.

Conclusion

This task was a rewarding experience. I successfully improved Onlook's handling of dynamic Tailwind classes, providing users with better error detection and navigation tools. Along the way, I honed my skills in TypeScript and JSX parsing, while contributing meaningful enhancements to the project.

I’m proud of the work I’ve done and look forward to further contributions to Onlook and other open-source projects. This experience reaffirms my belief in the power of community-driven development to produce high-quality, user-friendly software.

A Final Challenge: The Progress

Cleo Buenaventura — Wed, 04 Dec 2024 02:13:09 +0000

It's been a week since I started working on this issue in the onlook repo.

onlook-dev / onlook

The open source, local-first Figma for React. Design directly in your live React app and publish your changes to code.

Onlook

The first browser-powered visual editor
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

The open-source visual editor for your React Apps

Onlook.Studio.Component.Demo.for.GitHub.mp4

Built With

Stay up-to-date

Getting Started

Installation

Visit onlook.dev to download the app.
Run locally following this guide

Usage

Onlook will run on any React project, bring your own React project…

View on GitHub

The Issue

The main issue is that when a className is using template literals, the textarea that should show the Tailwind Classes used in the div shows nothing. The textarea displays the Tailwind Classes used in the currently selected div in the application.

In these examples, I selected a div that uses a static string, and then a div that uses template literals to show what it looks like:

Using static string

Using template literals

The Approach

As I have mentioned from my previous post, I proceeded with understanding the code and the logic behind the parsing of these classNames from the project file. One of the maintainers of the repo also mentioned the function and which file it can be located as a good place to start, which helped a lot.

getTemplateNodeClass

export async function getTemplateNodeClass(templateNode: TemplateNode): Promise<string[]> {
    const codeBlock = await readCodeBlock(templateNode);
    const ast = parseJsxCodeBlock(codeBlock);
    if (!ast) {
        return [];
    }

    const classes = getNodeClasses(ast);
    return classes || [];
}

This is the main function that orchestrates the parsing process.

Calls readCodeBlock to retrieve the relevant section of the JSX/HTML code for the selected TemplateNode.
Converts the retrieved code into an AST using parseJsxCodeBlock.
Passes the AST to getNodeClasses to extract the class names.
Outputs an array of class names or an empty array if nothing is found.

readCodeBlock

export async function readCodeBlock(templateNode: TemplateNode): Promise<string> {
    try {
        const filePath = templateNode.path;

        const startTag = templateNode.startTag;
        const startRow = startTag.start.line;
        const startColumn = startTag.start.column;

        const endTag = templateNode.endTag || startTag;
        const endRow = endTag.end.line;
        const endColumn = endTag.end.column;

        const fileContent = await readFile(filePath);
        const lines = fileContent.split('\n');

        const selectedText = lines
            .slice(startRow - 1, endRow)
            .map((line: string, index: number, array: string[]) => {
                if (index === 0 && array.length === 1) {
                    // Only one line
                    return line.substring(startColumn - 1, endColumn);
                } else if (index === 0) {
                    // First line of multiple
                    return line.substring(startColumn - 1);
                } else if (index === array.length - 1) {
                    // Last line
                    return line.substring(0, endColumn);
                }
                // Full lines in between
                return line;
            })
            .join('\n');

        return selectedText;
    } catch (error: any) {
        console.error('Error reading range from file:', error);
        throw error;
    }
}

This function takes an AST node and attempts to extract the className attribute.

If the className is a plain string, it splits the string into individual classes.
If the className is wrapped in a JSX expression but is still a static string, it extracts the value similarly.
For anything else, it currently returns an empty array, which leads to the issue.

getNodeClasses

function getNodeClasses(node: t.JSXElement): string[] {
    const openingElement = node.openingElement;
    const classNameAttr = openingElement.attributes.find(
        (attr): attr is t.JSXAttribute => t.isJSXAttribute(attr) && attr.name.name === 'className',
    );

    if (!classNameAttr) {
        return [];
    }

    if (t.isStringLiteral(classNameAttr.value)) {
        return classNameAttr.value.value.split(/\s+/).filter(Boolean);
    }

    if (
        t.isJSXExpressionContainer(classNameAttr.value) &&
        t.isStringLiteral(classNameAttr.value.expression)
    ) {
        return classNameAttr.value.expression.value.split(/\s+/).filter(Boolean);
    }

    return [];
}

This function is responsible for:

Reading the source file where the selected div resides.
Extracts the specific range of code based on the start and end positions of the TemplateNode.
Returns the extracted code block as a string.

Understanding these methods are crucial as this will be the foundation for this issue.

Progress

So within a week, I can say that I was able to make some progress with the issue. I now understand what I am working with, and where the issue stems from.

Based on my plans from last week, it was actually more simpler than I thought. I mentioned that I will need to figure out how to determine whether a className is using template literals or static strings. To my surprise, the code uses a method called isStringLiteral, which is a function from the @babel/types library. So I figured, searching through the methods, and I found that a method called isTemplateLiteral exists. This method easily allows me to determine whether a className uses a template literal or not, and then build the logic from there.

With that said, I have made my modifications with the code to achieve something like this:

Currently, I made it so that when a div has a className that uses template literals, a readOnly warning is shown in the textarea instead of the Tailwind Classes.

Problems Encountered

There was only one problem I encountered so far, which is not really concerned with the code I was working on (which I initially thought it was).

After working on the code, I realized that I have not pulled the latest main from the repo. So I have been working on an older version of the app. After pulling main and updating my branch, the feature I am working on suddenly stopped working.

The textarea suddenly stopped getting displayed. I had to reach out to the maintainers and had to confirm whether this was a new bug in the newer version or it was just an issue on my end.

Thankfully, there was just a new feature implemented that requires running the project through the built-in terminal in the app rather than running the project in another IDE separately.

The next step

So I have now reached out to the maintainers of the repo and showed what I have so far, and they have made a few suggestions.
So for finalizing this issue, the important changes I will have to implement are:

The warning should only appear when a user cannot edit the text. Meaning, this should only happen when dynamic variables are involved. This means, that other than determining whether a className uses template literals or not, I should also make a logic whether that template literal contains a dynamic variable or not. If there are no dynamic variables, then it should still be able to display the Tailwind Classes as if it is a static string.
A button should be displayed for the user along with the warning. This button when clicked, should bring the user to that specific templateNode. Basically bringing the user to the specific className in the source code the warning is referring to.

Next week, will be the final update of this issue hopfully having it done and merged.

A Final Challenge: The Planning Phase

Cleo Buenaventura — Wed, 27 Nov 2024 02:48:36 +0000

The end of the semester is drawing near, which also means the conclusion of the open source course. For the final assignment, I will be tackling an issue that will be outside of my comfort zone as a little push for myself to grow as a developer.

I have the remaining weeks of the semester to work on an issue that is not too difficult that I wouldn't be able to succeed, but also not too easy that I won't really be learning anything.

For this week, I will be choosing an issue and layout the plans on how I will be taking on this issue. For starters, I have decided to look for issues again from Onlook.

onlook-dev / onlook

The open source, local-first Figma for React. Design directly in your live React app and publish your changes to code.

Onlook

The first browser-powered visual editor
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

The open-source, local-first visual editor for your React Apps

Seamlessly integrate with any website or webapp running on React + TailwindCSS, and make live edits directly in the browser DOM. Customize your design, control your codebase, and push changes your changes without compromise.

Onlook.Studio.Component.Demo.for.GitHub.mp4

Built With

Stay up-to-date

Getting Started

Installation

Option 1: Download from website

Visit onlook.dev to download the pre-built app.

Optione 2: Run locally

Important

We require the Bun.sh runtime. You can…

View on GitHub

As a quick recap, I contributed to this project previously during the Hacktoberfest. This is important as this is one of the main reasons why I decided to contribute to this project again. I really liked the concept of the project. It is something that would prove to be helpful to both developers AND aspiring developers.

So with that being said, I dont think I would want to end the course any other way than getting an opportunity to improve and contributing to a project that interests me.

Issues

Here are a couple of issues that I've been looking at and planning to take on:

Issue #1: https://github.com/onlook-dev/onlook/issues/479
Issue #2: https://github.com/onlook-dev/onlook/issues/799

After looking at the issues and doing some quick research, I am leaning more towards Issue #2 as it seems more doable at my current level within the remaining time.

I have been looking at Issue #1 since Hacktoberfest, and technically even tried to solve it without asking for the task just because I was curious, and it seemed more complicated than I thought. Then weeks later, Issue #2 appeared, and the issues have some similarity which is handling dynamic variables. The part that differentiates the difficulty between the two issues is that Issue #1 deals with how dynamic variables should be handled in the DOM, while Issue #2 is about detecting and providing meaningful feedback when dynamic variables are used in Tailwind class names, improving the developer experience.

Plans

So far these are the first few steps I will be taking:

1. Find the relevant code and files.
For a big project with an already existing huge code base, it is important that I figure out which files and code I will most likely be working on. I think that dealing with this first hand will save me time once I actually start putting in some work.

2. Understanding the code and the flow.
This one should be a no brainer. But it is still worth mentioning because I may have contributed to the project twice during Hacktoberfest, the issues from then and now are two different things and are completely different areas of the app. So this would require some time again to understand this specific segment of the code.

3. Define the approach for detecting dynamic variables.
Once I have identified and understood the relevant code, the next step will be to figure out how to detect dynamic className values effectively. This will involve analyzing patterns in the className property, such as template literals, concatenated strings, or computed functions. I will then implement logic to handle these cases by displaying warnings or feedback in the UI and ensuring the changes integrate smoothly with the existing functionality.

Releasing GENEREADME

Cleo Buenaventura — Sun, 24 Nov 2024 07:53:04 +0000

For this week's lab, I am now to release GENEREADME.

cleobnvntra / genereadme

GENEREADME is a command-line tool that takes in a source code file and generates a README.md file that explains the code in the file by utilizing an LLM.

Contrubutions

Contributions to GENEREADME are welcome! Please checkout CONTRIBUTING.md for guidelines on setting up the environment, how to run and test the tool, and submitting changes.

GENEREADME

GENEREADME is a command-line tool that takes in a file, processes it, and generates a README file with an explanation or documentation of the contents of the file. The tool utilizes OpenAI chat completion to analyze the file and generate content.

Usage

Install the tool by running the following command:

npm i -g genereadme

The tool currently supports Groq and OpenRouter, which uses Groq by default. A valid API key for the appropriate provider must be provided.

Provide a valid API key either by creating a .env file or through the -a or --api-key flag when using the command:

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Run the tool with the existing sample files or start using your own:

…

View on GitHub

The Process

Publishing the tool itself was no trouble at all however, there were some extra steps I had to take to ensure a proper release.

Research

Before I focused on the release process, I took some time to research best practices and steps for publishing a package to the npm registry. Here's what I learned:

1. How to publish a package to npm
To understand the basic process, I referred to the official npm documentation. This guide provided an overview of essential steps, including setting up a package.json, running npm publish, and managing versions.

2. Using Semantic Versioning
Versioning plays a crucial role in signaling changes to users. I looked at the principles of Semantic Versioning, which uses the MAJOR.MINOR.PATCH format to describe breaking changes, new features, and bug fixes. This ensured my tool would have a meaningful version number for each release.

3. Managing .npmignore
I researched how to effectively use the .npmignore file to ensure my npm package includes only the necessary files for end-users. By carefully creating this file, I was able to exclude development-specific files like configuration files, tests, and documentation that aren't required in the published package. This not only reduced the size of the package but also made it more professional by focusing solely on what the users actually need to run the tool. Properly managing .npmignore is a critical step in preparing a polished release.

Release

After doing my research, I double checked any requirements, any possible bugs, and any failing tests.
After everything looked all good to me, I proceeded to publish the package by running:

npm publish

NOTE: Running this command will require the user to be logged in to their npm account by running the command:

npm login

Testing

Now that I have publish v1.0.0 of GENEREADME, it was time to ask some end-users to test if the package works.
As expected, there were a couple of bugs that made it through. One which does not affect how the tool performs, and one that actually breaks it.

Adjustment

Version command bug

The simple bug that was found is about using the command genereadme -v. This command should print the tool's name and the current version. However, the way I coded this part is that I retrieve the project name and version from the package.json in the current directory. This means that if an end-user runs this command, it will display the name and version of THEIR project instead of mine. So this was a simple fix to just make sure that it will always retrieve it from the correct project.

Outputs directory bug

Now this one is a bug that breaks the tool which technically worked in my local testing, but I forgot a simple test case.
The folder structure of the project only had developers and contributors in mind, so having the outputs folder in the project is expected, which I also pushed to the main repo containing a sample result of an output.

Now, I had to keep in mind that it will be slightly different for the end-user.
Previously, the code was written to just write to the outputs/ directory without checking for its existence, and to make one if it doesn't. This caused the manual testing of the published package fail since the end-user did not have a outputs/ directory, the tool will just fail instead of making one if it doesn't exist.

After this discovery, I thought pretty simple, right?
Until I tried pushing the changes thinking "Okay, that fixes it!" but to my surprise, my CI failed!

The culprit:

if (!fs.existsSync("./outputs")) {
  fs.mkdirSync("./outputs");
}

So this is how I check and create the outputs/ directory. However, in my end-to-end testing, I was mocking the fs.existsSync() to return a value of false for this reason:

export function readConfigFile() {
  const homeDir = os.homedir();
  const configFilePath = path.join(homeDir, "./genereadme-config.toml");

  if (fs.existsSync(configFilePath)) {
    try {
      const configFileContent = fs.readFileSync(configFilePath, "utf-8");

      return toml.parse(configFileContent);
    } catch (error) {
      console.error("Error parsing the config file:", error.message);
      process.exit(1);
    }
  }
  return {};
}

This function checks for a toml config file which uses fs.existsSync(), and I did not want to use a toml config file for my end-to-end testing, I mocked this method to return false, which is now conflicting with the bugfix I did.

I am yet to master mocking and find out ways to possibly make different mock values for the same method for different conditions. So until I learn that procedure, I made the temporary fix to ensure that the outputs/ directory gets removed before every test case.

const outputsPath = path.resolve("./outputs");
if (fs.existsSync(outputsPath)) {
  fs.rmdirSync(outputsPath);
}

GENEREADME v1.0.4

And that concludes the important patches I made! GENEREADME is now available for use!

Learning and Growing Through Open Source Contributions

Cleo Buenaventura — Wed, 20 Nov 2024 03:54:51 +0000

Contributing to open-source projects is always an opportunity to refine skills and face new challenges. This time, I worked on improving unit test coverage for two components ,LoadingSpinner and FileAttachmentButton, in the React project react-chatbotify. These contributions allowed me to explore more advanced testing techniques, particularly mocking, and ensured robust functionality and styling validation.

tjtanjin / react-chatbotify

A modern React library for creating flexible and extensible chatbots.

React ChatBotify

Introduction

Welcome to React ChatBotify, an intuitive and versatile library that allows you to build responsive chatbots with ease. Whether you're aiming to create a simple FAQ bot or a sophisticated conversational interface integrated with Large Language Models (LLMs), React ChatBotify provides the tools and flexibility you need to bring your vision to life.

Designed with developers in mind, React ChatBotify simplifies the chatbot development process without compromising on functionality. Its intuitive API and comprehensive customization options allow you to tailor your chatbot to meet specific project requirements seamlessly. From handling basic interactions to managing complex and advanced conversational flows, our library empowers you to deliver engaging user experiences. Head over to our community showcases or join our discord to get inspired and start crafting your chatbot today!

React ChatBotify is currently compatible with React versions…

View on GitHub

Issues and PR

LoadingSpinner Component

Issue: Add unit test cases for LoadingSpinner.
PR: Validating the rendering and styling of the LoadingSpinner component.

The goal of this contribution was to ensure that the LoadingSpinner component behaves as expected across various contexts, including:

Rendering Verification: Ensuring that all spinner elements are correctly rendered in the DOM.
Primary Color Application: Validating that the spinner's border color aligns with the primary color set in the settings context.
Custom Style Application: Verifying that additional styles passed via the styles context are correctly applied, including properties like border-radius, width, and height.

This approach guaranteed that the spinner maintains visual and functional consistency within the app's design system.

FileAttachmentButton Component

Issue: Add unit test cases for FileAttachmentButton.
PR: Testing the behavior and rendering of the FileAttachmentButton component.

The complexity of the FileAttachmentButton component required testing various states and functionalities, such as:

State-Dependent Icon Rendering: Validating different icons for enabled and disabled states based on context.
File Upload Handling: Ensuring the handleUpload function processes files correctly and calls necessary callbacks.
Preventing Invalid Actions: Ensuring that file uploads do not proceed if preconditions (e.g., valid file path) are not met.

The testing strategy ensured reliability in user interaction and maintained robust support for various configurations and edge cases.

Learning and Challenges

Unit testing is an area I have been aiming to improve, especially in mocking dependencies and isolating components effectively. These contributions were a great chance to apply my newfound knowledge from a recent lab task.

A significant challenge was understanding how the existing components functioned to write meaningful tests without altering the code being tested. This required delving into the codebase and determining how to simulate scenarios accurately. Another challenge was achieving comprehensive test coverage while avoiding redundant tests, which required identifying edge cases and state-specific behavior.

Mocking dependencies, such as contexts and hooks, played a pivotal role in testing these components efficiently. Through this experience, I developed a deeper appreciation for the design of testable code and the importance of clear boundaries between logic and presentation.

Conclusion

This contribution emphasized the value of testing in maintaining and scaling open-source projects. By thoroughly validating the LoadingSpinner and FileAttachmentButton components, I ensured they remain reliable across different use cases. The challenges I faced in mocking and achieving good coverage further honed my testing skills, preparing me for future contributions and projects.

Implementing CI with GitHub Actions Workflow

Cleo Buenaventura — Sun, 17 Nov 2024 01:14:08 +0000

For this week's activity, I am tasked to further improve my project GENEREADME, by adding unit tests and implementing Continuous Integration through GitHub Actions workflow.

cleobnvntra / genereadme

GENEREADME is a command-line tool that takes in a source code file and generates a README.md file that explains the code in the file by utilizing an LLM.

Contrubutions

Contributions to GENEREADME are welcome! Please checkout CONTRIBUTING.md for guidelines on setting up the environment, how to run and test the tool, and submitting changes.

GENEREADME

Usage

The tool currently supports Groq and OpenRouter, which uses Groq by default. A valid API key for the appropriate provider must be provided.

Provide a valid API key either by creating a .env file or through the -a or --api-key flag when using the command:

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Install the dependencies:

npm install -g

Run the tool with the existing sample files or start using your own:

genereadme <files&gt
genereadme examples/sum.js
genereadme examples/createUser.js

…

View on GitHub

GitHub Actions Workflow

I primarily used the Node.js setup for my GitHub Actions, which generates a .yml.

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x, 22.x]

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm run test:silent

This will run the test whenever changes are either pushed or merged by pull requests to the main branch.

Contributing to OptimizeIt

For this task, I am also required to make a contribution to another project by adding more possible tests. I chose to contribute to OptimizeIt.
Since this project also uses jest for unit testing, and nock for mocking, it wasn't as difficult adding another test. However, the main challenge is that my partner has already written A LOT of test cases, having a 98% overall coverage. So I had to look for something that is either not tested or any lines that weren't covered, to which I ended up going for the latter.

The impact of Continuous Integration

Setting up CI for GENEREADME has been transformative. By automating tests for every push or pull request, it ensures that new changes don’t break existing functionality. For GENEREADME, this means maintaining stability across multiple Node.js versions and saving time on manual testing. CI enhances collaboration, enforces best practices, and builds confidence in the project’s quality, making it an essential addition for sustainable development.

Formatting and Linting for consistency

Cleo Buenaventura — Wed, 06 Nov 2024 14:58:43 +0000

This activity involves implementing statistic analysis tools into my open source project GENEREADME to improve code quality and consistency.

cleobnvntra / genereadme

GENEREADME is a command-line tool that takes in a source code file and generates a README.md file that explains the code in the file by utilizing an LLM.

Contrubutions

Contributions to GENEREADME are welcome! Please checkout CONTRIBUTING.md for guidelines on setting up the environment, how to run and test the tool, and submitting changes.

GENEREADME

Usage

The tool currently supports Groq and OpenRouter, which uses Groq by default. A valid API key for the appropriate provider must be provided.

Provide a valid API key either by creating a .env file or through the -a or --api-key flag when using the command:

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Install the dependencies:

npm install -g

Run the tool with the existing sample files or start using your own:

genereadme <files&gt
genereadme examples/sum.js
genereadme examples/createUser.js

…

View on GitHub

Formatter

For my formatter, I chose to use Prettier. For simple reasons, I chose this because I have simply used its basic features before, and I plan to learn more of it.

Technically, I already setup my IDE to use prettier by default so I already had my formatter from the beginning. However, now with the prettier setup in the project itself, this will allow contributors to also use the formatter, keeping the project's code consistent in terms of formatting.

I simply added the rules on how I want the code to be formatted in my .prettierrc file, and some settings in settings.json under .vscode/ for options like formatting on save.

Linter

For my linter, I chose to use ESLint. Since I am using JavaScript, I used one of the popular linters, which I have also had experience using before, but not really setup myself. So because of that, I went with ESLinter.

Setting up ESLinter wasn't really complicated. A simple install and setting up the rules in eslint.config.js is enough to get the linter working. However, since I am both using a formatter and a linter at the same time, I have to make sure that both of them can work together properly. Which basically includes additional rules to ensure that there won't be any conflicts with the linter and formatter.

How to use the tools

There are many ways the tools can be used in the project, and I personally prefer these specific configurations: format on save for prettier and run on type for eslint. This way, the linter will always check for linting issues as the developer types, and then the formatter will auto format the changes when a save is triggered.

For this week's task however, I also added scripts to allow the user to run the formatter and linter manually through the CLI. A pre-commit hook is also implemented to ensure that any code committed to the repository meets the project’s formatting and linting standards. By adding this hook, I can automatically run Prettier and ESLint before each commit, catching any issues early and maintaining code consistency across contributions. This setup helps reduce the chances of minor formatting issues slipping through and improves code readability for anyone working on the project.

Reflecting on Hacktoberfest 2024

Cleo Buenaventura — Sun, 03 Nov 2024 16:55:22 +0000

Joining Hacktoberfest 2024 has been a great learning experience. As a first-time contributor, I was both excited and a bit nervous about working on open-source projects. I chose issues that helped me gradually build up my skills in different areas of web development. Each project came with its own set of challenges and showed me just how valuable it is to work together in the open-source community.

Issue and PR Recap

Week 1 - Food Data Scrapper:

Issue: Create requirements.txt

PR: DOCS: Create requirements.txt

My first contribution involved creating a requirements.txt file for the Food Data Scrapper project, which was straightforward but introduced me to uv, a package manager I hadn’t encountered before. I learned the importance of project-specific formatting standards after receiving feedback on my pull request regarding an unintended change from Prettier. This experience underscored the need to be cautious with auto-formatters and adapt to each project’s standards.

Week 2 - Q-Vote:

Issue: Bug: No error message on Wrong credentials at Login page.

PR: added error messages to login page

My next issue was a bug fix on the Q-Vote project’s sign-in page, where error messages weren’t displaying for invalid login attempts. Working with Flask templates to render these messages was new to me and aligned with my goal to deepen my web development skills. This task allowed me to explore the back-end and front-end aspects of user interaction, enhancing the usability of the sign-in page.

Week 3 - Onlook:

Issue: feat: Add existing functionalities to right click menu

PR: feat: Added existing functionalities to right click menu

For my third contribution, I tackled a feature request on the Onlook project, implementing a functioning right-click menu. Navigating this TypeScript and object-oriented codebase was a significant step up in complexity, and understanding the structure of a large project was both challenging and rewarding. I learned to work with classes and existing functionalities, and after a suggestion from the repo owner, I went the extra mile to make additional modifications within the same PR.

Week 4 - Onlook:

Issue: Bug: Need minimum values for numeric style inputs that can't be negative

PR: Enforce min/max values in editor

Returning to Onlook for my final contribution, I addressed a bug that required implementing validation logic to prevent invalid inputs in styling properties. Enforcing min and max attributes within a centralized component reduced code repetition and ensured consistent behavior across the app. This contribution deepened my understanding of modular code practices and the importance of clean, maintainable solutions.

Conclusion

Hacktoberfest provided a great opportunity to work with a variety of technologies and projects. I started with simpler issues, gaining confidence in interacting with repo owners and handling basic PRs, and progressed to more complex tasks that challenged me to read, understand, and modify large codebases effectively. This journey has reinforced my passion for web development and prepared me to approach future projects with greater insight and confidence.

Hacktoberfest 2024 - Part 4

Cleo Buenaventura — Sat, 26 Oct 2024 00:59:02 +0000

For this week's and final contribution for Hacktoberfest 2024, I decided to contribute in the same project, onlook. As a Software Developer that is in the process of improving my skills in Web Development, I found this project interesting and also helpful to anyone in the field.

onlook-dev / onlook

The open source, local-first Figma for React. Design directly in your live React app and publish your changes to code.

Onlook

The first browser-powered visual editor
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

The open-source, local-first visual editor for your React Apps

Seamlessly integrate with any website or webapp running on React + TailwindCSS, and make live edits directly in the browser DOM. Customize your design, control your codebase, and push changes your changes without compromise.

Onlook.Studio.Component.Demo.for.GitHub.mp4

Built With

Stay up-to-date

Getting Started

Installation

Run locally

Clone the repo

git clone https://github.com/onlook-dev/onlook.git

Navigate to app folder inside the project
```
cd onlook/app
```
Install NPM packages
```
npm install
```
Run the…

View on GitHub

Issue #4

This time, I worked with a bugfix issue. The task requires implementing a validation logic to prevent users from inputting invalid values to some of the styling properties.

It is important to not allow users to input invalid values in styling such as negative values especially in styling properties where it doesn't make sense to have them. However, there are still styling properties where negative values have their own effect, to which this functionality should be kept available.

PR #4

For my pull request, is the solution I made to fix this bug. The repo owner has given me a tip that they already have implemented the necessary interfaces for the styles which contains the min and max attributes. They also already have the appropriate initialization of the classes of the styles, with the exception of enforcing the min/max attributes.

So the process is to figure out how the classes for the styles work, how I can enforce the min and max attributes, and where to put the validation logic.

It was easy to implement once I found where the classes are initialized since I just had to enforce the min and max values, which I will be able to use for the validation logic since these attributes are public attributes of the class.

Initially, I just added the validation logic directly in the handlers of the input. However, I noticed the amount of code repetition since I had to implement the validation to every handler for the different styles properties. So I tracked the main input component used by these styles properties and implemented the validation logic there instead. This prevents the code repetition for the validation. One of my concerns was that this solution wouldn't work if this input component is used somewhere else other than the styles properties, to which I made sure that it wasn't before implementing this solution.

Hacktoberfest 2024 - part 3

Cleo Buenaventura — Fri, 25 Oct 2024 23:43:30 +0000

For this week's hacktoberfest contribution, I had the privilege of working with onlook, a Figma-like visual editor for React applications. For my contribution, I was able to work on an issue to add a new feature to the project.

onlook-dev / onlook

The open source, local-first Figma for React. Design directly in your live React app and publish your changes to code.

Onlook

The first browser-powered visual editor
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

The open-source, local-first visual editor for your React Apps

Seamlessly integrate with any website or webapp running on React + TailwindCSS, and make live edits directly in the browser DOM. Customize your design, control your codebase, and push changes your changes without compromise.

Onlook.Studio.Component.Demo.for.GitHub.mp4

Built With

Stay up-to-date

Getting Started

Installation

Run locally

Clone the repo

git clone https://github.com/onlook-dev/onlook.git

Navigate to app folder inside the project
```
cd onlook/app
```
Install NPM packages
```
npm install
```
Run the…

View on GitHub

Issue #3

The issue I had to work with requires implementing a new feature which includes using existing functionalities in the project.

The feature is to implement a functioning right-click menu with the appropriate functionalities. Even though the project can still be considered in the early stages of development, there is already a lot of functionalities implemented. Which is where the challenge arises from.
Reading and understanding the structure of the project and the code, which is utilizing object-oriented programming and taking advantage of TypeScript to which I'm still learning.

PR #3

My pull request contains the solution to implementing the requested feature. Since the functionalities of the actions are already implemented, the solution to implementing the feature was simple.

So the main process is to figure out the classes that has the necessary methods and how to use them appropriately. Next is where to implement the existing methods. Luckily, the project already has an existing right-click menu feature, so I just had to add the new options required in the feature with their respective methods to do the action.

In the end, one of the repo owners made a suggestion as a review to which he suggested I could make it as a separate issue. But since I think that it would be a minor modification, I took on the task and completed it in the same issue and just made another commit in the same PR.

Hacktoberfest 2024 - part 2

Cleo Buenaventura — Wed, 16 Oct 2024 20:58:25 +0000

For this week's hacktoberfest contribution, I had the opportunity to make my first bug fix PR. Moving up from my previous PR, I chose another project written in python.

vigneshs-dev / Q-Vote

A quantum voting system utilizing quantum superposition and entanglement for secure and private voting

Q-Vote 🗳️

A quantum voting system utilizing quantum superposition and entanglement for secure and private voting

Quantum Voting meets Blockchain!

🚀 Project Overview

Q-Vote simulates a secure voting process using quantum computing, with future plans for blockchain integration and a user-friendly web interface. This project uses Qiskit to simulate quantum voting and lays the groundwork for secure, private voting systems of the future.

🏗️ Architecture

graph TD
    A[Client Browser] -->|Request| B[Flask Web Server]
    B -->|Render| C[index.html]
    B -->|Vote| D[Voting Simulation]
    D --> E[Classical Voting]
    D --> F[Quantum Voting]
    E --> G[Collect Votes]
    G --> H[Identify Winner]
    F --> I[Quantum Circuit]
    I --> J[Amplitude Encoding]
    J --> K[Apply Gates]
    K --> L[Measurement]
    L --> M[Interpret Results]
    
    H --> N[Check Ties]
    M --> N
    N --> O[Final Winner]
    
    O --> P[Generate Plot]
    P --> Q[Base64 Image]
    D --> R[JSON Response]
    Q --> R
    R -->|Response| A
    
    subgraph Classical Logic
    E
    G
    H

…

View on GitHub

Issue #2

This will be the second issue that I work on for hacktoberfest. This issue simply requires a bug fix on the sign in page.
Before the fix, the sign in page of the web app does not display any error messages. This means that when a user inputs invalid credentials, they wouldn't know what happened as it does not provide any feedback.
The repo owner uses Flask, so I had to familiarize myself with Flask's templates to be able to display the appropriate messages.

PR #2

In this Pull Request, I only needed to work mostly with the html file where the sign in page is rendered. Since the logic behind the sign in page was already implemented, all I had to do was implement the code needed to display the error messages.

Overall

It was a great learning experience as this kind of issue aligns with my goals for taking the open source course, which is to improve my web development skills and knowledge.
It may be a simple task of writing an html code to render messages, but slowly expanding my knowledge with different languages and frameworks will surely help me in the long run.

Refactoring GENEREADME

Cleo Buenaventura — Tue, 08 Oct 2024 04:08:52 +0000

For this week's lab, I was tasked to refactor my code, genereadme with the opportunity to learn rebasing, squashing, and amending commits. I am tasked to refactor at least 3 things in my code, which in a normal case shouldn't be an issue. However, before someone asked to contribute to my project last week for last week's lab, I did a major refactoring since all the code was only in a single index.js file. The task for last week was to add another feature, which means the project is going to get even bigger. So with that in mind, I decided to refactor it.
Because of this, I struggled a little bit to find more things to refactor in my code as I have refactored it to as much as I think I can, leaving me a bit surprised as I did not expect refactoring to be a part of the labs.

What to look for

Well, there are many ways to refactor code. It could be renaming variables, extracting functions, creating classes, splitting code, or optimization. My code isn't really that complex, I am confident that the variable names were self explanatory. So I focused in trying to look for any remaining code duplication or shared functions that I could refactor.

Refactoring

I was able to find 2 files to refactor, which I extracted more functions and split them into separate files. Since I just did a major refactoring a week ago, my goal here is to improve readability and maintainability.

First, I had a file setup.js which contains the initialization of Commander that also includes adding the basic settings, added options, added arguments, and any custom error handling. By looking at it, this file will end up getting bigger as more possible option flags can be added, possibly more custom error handling for new features, or accept an entirely new argument for a different feature.

  const program = new Command();

  program
    .name(packageJson.name)
    .usage("<filename> [options]")
    .description(
      "CLI tool to generate a README file explaining a source code file"
    )
    .helpCommand(false)
    .addHelpText("after", "\nSupported providers: [Groq, OpenRouter]")
    .version(
      `${packageJson.name} ${packageJson.version}`,
      "-v, --version",
      "Outputs the tool name and current version"
    )    .option("-p, --provider <provider>", "Provider for the chat completions")
    .option("-o, --output <filename>", "output result to specified filename")
    .option("-a, --api-key <key>", "API key for the Groq API")
    .option(
      "-t, --temperature <temperature>",
      "Temperature for the chat completions"
    )
    .option("-tu, --token-usage", "Show prompt and completion token usage")
    .configureOutput({
      outputError: (str) => {
        if (str.includes("error: missing required argument")) {
          console.error(
            "Error: No source code file provided. Please provide a valid source code file to process.\n\nuse command: genereadme <files...>"
          );
          process.exit(1);
        } else {
          console.error(err);
          process.exit(1);
        }
      },
    })
    .argument("<file...>", "Source code file to process");

  return program;

So what I did, is separate them into different functions categorically. Mainly, I have a createProgram() function which contains the construction of the Command object and the basic settings, such as program name, version command, help command, and etc.
Then, I created the other functions by category to organize them, making the code readable and maintainable. For example, adding an additional option would require adding .option() to the Command object. Having them all in one function makes it readable as these methods are grouped into one function, which I then did the same to the remaining program settings.

Second, a simple change I made is I basically extracted a logic into a function.

  let baseURL;
  let model;

  if (provider.toLowerCase() === "groq") {
    baseURL = "https://api.groq.com/openai/v1";
    model = "llama-3.1-70b-versatile";
  } else if (provider.toLowerCase() === "openrouter") {
    baseURL = "https://openrouter.ai/api/v1";
    model = "meta-llama/llama-3.1-8b-instruct:free";
  } else {
    throw new Error(
      `${provider} is invalid or is currently unsupported. Please choose from the supported providers:\n` +
        "1. Groq\n" +
        "2. OpenRouter"
    );
  }

This is the logic I have which allows users to use different LLM providers, which I had included in the same file where I am constructing the OpenAI client object.

Merging

So far, through the use of git, source control, or github desktop, I would normally just make my commits, push the commits to my working branch, then either make a merge or PR. Now I know how to rebase and squash multiple commits into one, and using amend whenever I need to fix something from the last commit.