Check

The Check class provides a fluent interface for making assertions about policy data. The object keeps track of accessed data within the component JSON and records that for traceability purposes. The final result of a check will have not just the status (pass, fail, no-data or error), but complete information about which JSON paths were used to reach this conclusion. Designed to be used as a context manager with Python's with statement, the Check class automatically handles NoDataError, tracks result statuses, and provides isolation between different policy checks on "no-data" outcomes.

Constructor

Check(name, description=None, component_data=None)

• name (str): A unique identifier for this check

• description (str, optional): A human-readable description of what this check validates

• component_data (ComponentData, optional): A ComponentData instance to use for this check

Context Manager

The Check class is designed to be used as a context manager with Python's with statement. This is the recommended way to use the class as it ensures proper setup, teardown, and error handling.

with Check("check-name", "Check description") as check:
    # Make assertions using check methods
    check.assert_true(Path(".path.to.data"))

When used as a context manager, the Check class:

1. On enter: Sets up the check context and automatically loads component data if not provided

2. On exit: Records the check result with its status and all accessed data paths

3. Exception handling:

   • Catches NoDataError and sets the check status to "no-data" instead of "fail"

   • Records other exceptions as "error" status with the exception message

   • Prevents exceptions from propagating, allowing subsequent checks to execute

This means you can have multiple checks in sequence, and if one fails with a NoDataError, the others will still execute:

# Both checks will execute even if the first raises NoDataError
with Check("check-1") as check:
    raise NoDataError()

with Check("check-2") as check:
    check.assert_contains(Path(".tags"), "api")  # Will still execute

Note, however that other exceptions will still propagate, so you should still handle those appropriately.

with Check("check-1") as check:
    raise Exception("This is a test exception")
with Check("check-2") as check:
    check.assert_contains(Path(".tags"), "api") # This will not execute

Data Access Methods

get

get(path)

Retrieves data from the component JSON using a JSONPath expression.

• path (str): JSONPath expression to query the component data

• Returns: The value at the specified path, or raises NoDataError if not found

Example:

# Get the number of lines in the README
lines = check.get(".readme.lines")

get_all

get_all(path)

Retrieves data from all metadata instances using a JSONPath expression. This method is useful if there are path collisions in the component JSON.

• path (str): JSONPath expression to query the component data

• Returns: A list of values matching the path across all metadata instances, or raises NoDataError if not found

Example:

# Get all API endpoints across all instances
all_endpoints = check.get_all(".api.endpoints")

Assertion Methods

All assertion methods have these common parameters:

• value: Can be a direct value, or a Path object

• failure_message (str, optional): Custom message to display if the assertion fails

• all_instances (bool, optional): If True, checks all metadata instances, not just the merged blob

Additionally, all assertion methods raise NoDataError if the path doesn't exist in the component data.

assert_true

assert_true(value, failure_message=None, all_instances=False)

Asserts that a value is True.

Example:

# Assert that authentication is required
check.assert_true(Path(".api.auth_required"), "API should require authentication")

assert_false

assert_false(value, failure_message=None, all_instances=False)

Asserts that a value is False.

Example:

# Assert that the README.md file is not missing
check.assert_false(Path(".readme.missing"), "README.md file should exist")

assert_equals

assert_equals(value, expected, failure_message=None, all_instances=False)

Asserts that a value equals the expected value.

• expected: The expected value to compare against

Example:

# Assert that the API endpoint uses GET method
check.assert_equals(Path(".api.endpoints[0].method"), "GET", "Endpoint should use GET method")

assert_contains

assert_contains(value, expected, failure_message=None, all_instances=False)

Asserts that a value contains the expected value (works for strings, lists, etc.).

• expected: The value that should be contained

Example:

# Assert that the endpoint path contains a specific substring
check.assert_contains(Path(".api.endpoints[0].path"), "/users")

# Assert that the tags list contains a specific tag
check.assert_contains(Path(".tags"), "api")

assert_greater

assert_greater(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is greater than the expected value.

• expected: The threshold value to compare against

Example:

# Assert that the code coverage is greater than 80%
check.assert_greater(Path(".coverage.percentage"), 80, "Code coverage should be greater than 80%")

assert_greater_or_equal

assert_greater_or_equal(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is greater than or equal to the expected value.

• expected: The threshold value to compare against

Example:

# Assert that README has at least 50 lines
check.assert_greater_or_equal(Path(".readme.lines"), 50, "README should have at least 50 lines")

assert_less

assert_less(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is less than the expected value.

• expected: The threshold value to compare against

Example:

# Assert that cyclomatic complexity is less than 15
check.assert_less(Path(".complexity.cyclomatic"), 15, "Cyclomatic complexity should be less than 15")

assert_less_or_equal

assert_less_or_equal(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is less than or equal to the expected value.

• expected: The threshold value to compare against

Example:

# Assert that build time is at most 5 minutes
check.assert_less_or_equal(Path(".build.duration_minutes"), 5, "Build should take at most 5 minutes")

assert_match

assert_match(value, pattern, failure_message=None, all_instances=False)

Asserts that a string value matches a regular expression pattern.

• pattern (str): A regular expression pattern to match against

Example:

# Assert that version follows semantic versioning
check.assert_match(Path(".version"), r"^\d+\.\d+\.\d+$", "Version should follow semantic versioning")

fail

fail(message)

Unconditionally fails the check with a given message.

• message (str): The message to display when the check fails

Example:

check.fail("This is a policy failure")

Result Methods

get_assertions

get_assertions()

Retrieves the list of assertions made in this check.

• Returns: A list of all assertions made in this check

Each assertion object contains information about the assertion:

• passed (bool): Whether the assertion passed

• message (str): The assertion message

• expected: The expected value (if applicable)

• actual: The actual value (if applicable)