↓Skip to main content

IntentGuard: Elevating Code Quality with Natural Language Assertions

·4 mins
Table of Contents

Hey there! đź‘‹ In a world moving fast, it’s crucial to build technology that truly serves us. That’s why I’m excited to introduce you to IntentGuard. It’s a Python library I’ve created to bring a more human way to check your code quality – using simple, natural language. If you feel current code analysis tools miss the bigger picture, let’s explore how IntentGuard can help.

Why IntentGuard? #

Current static analysis tools are helpful for catching basic errors. But they often miss deeper, more meaningful aspects of code quality. Think about the unwritten rules in your projects – specific ways to handle errors, consistent documentation, or certain design principles you want to follow. These are vital, but hard to check with standard tools.

IntentGuard steps in to fill this gap. It’s a Python library that uses AI to understand and check your code against plain English assertions. This lets you express and verify complex code qualities that were previously too hard to automate. It’s about making code quality checks more intuitive and aligned with human intent.

How IntentGuard Works #

IntentGuard uses AI to perform code checks based on natural language, keeping it straightforward:

  1. State Your Intent: You write an assertion in plain English, describing what your code should do or be like.
  2. IntentGuard Analyzes: The library looks at your code and your assertion.
  3. AI Evaluates: A local AI model checks if your code matches your description. It runs directly on your machine, respecting privacy.
  4. Get Clear Results: You get a clear “pass” or “fail.” IntentGuard is designed to be reliable, using voting and careful prompting for consistent results. If it fails, you get a clear explanation in natural language.

IntentGuard is built to be dependable and efficient. It re-checks assertions multiple times to ensure accuracy and saves results to run faster.

Practical Examples #

Here are a few simple examples of how IntentGuard can be practically useful:

1. Consistent Error Handling #

def test_error_handling():
    ig.assert_code(
        "All methods in {module} should use the custom ErrorHandler class for exception management, and log errors before re-raising them",
        {"module": my_critical_module}
    )

IntentGuard checks if error handling is consistent across your module, based on your plain English rule.

2. Complete API Documentation #

def test_docstring_completeness():
    ig.assert_code(
        "All public methods in {module} should have docstrings that include Parameters, Returns, and Examples sections",
        {"module": my_api_module}
    )

It verifies if your API documentation meets your standards, ensuring important sections are present.

3. Code Structure Principles #

def test_code_organization():
    ig.assert_code(
        "Classes in {module} should follow the Single Responsibility Principle",
        {"module": my_module}
    )

IntentGuard can even check higher-level principles like Single Responsibility, helping maintain good code design.

4. Secure Database Practices #

def test_security_practices():
    ig.assert_code(
        "All database queries in {module} should be parameterized to prevent SQL injection",
        {"module": db_module}
    )

It helps confirm essential security practices are in place, like parameterized database queries.

These examples show how IntentGuard can simplify checks for complex code qualities, saving you from writing lengthy, complicated tests.

Customization #

IntentGuard is adaptable to your needs with IntentGuardOptions:

options = ig.IntentGuardOptions(
    num_evaluations=7,
    temperature=0.1,
)

guard = ig.IntentGuard(options)

You can adjust settings like num_evaluations for more thorough checks or temperature for more focused AI interpretation.

Impact on Development #

IntentGuard offers a new way to think about code quality. It can:

  1. Make Checks More Expressive: Verify complex code ideas in simple language.
  2. Connect Requirements to Code: Easier to confirm code matches your intended purpose.
  3. Improve Code Reviews: Automate checks for design and intent in CI/CD.
  4. Document Code Expectations: Assertions become clear, living documentation of code rules.

Important Points to Consider #

Keep in mind these limitations:

  1. Resource Use: AI checks use more resources than basic static analysis. Use it where it adds the most value.
  2. Natural Language Interpretation: Plain English can be slightly open to interpretation. Write assertions clearly.
  3. AI Model Limits: IntentGuard relies on AI, which has its limits.
  4. Complement to Other Tests: It works best alongside unit tests and other testing methods.

Explore IntentGuard #

IntentGuard is about making code quality checks more human-centered. It’s an experiment in bringing intention into our development process.

If you’re interested in trying it out, the code is open-source on GitHub. It’s designed for privacy and efficiency, running locally. Your feedback and contributions are very welcome as we improve this approach together.

↑