contract-detection

Contract Detection Methodology

Extract behavioral intelligence from machine-readable API contracts. These are formal, published definitions of system interfaces -- the strongest possible specification source. A contract file is an explicit promise about what the system accepts and returns.

When to Use This Mode

Contract detection activates when:

• The target repository or documentation contains API specification files
• The discovery inventory identifies machine-readable contract files
• Other modes discover machine-readable contracts during analysis

This mode runs independently of all other intelligence sources. All output is PUBLIC -- machine-readable contracts are published definitions intended for external consumption. Output goes to workspace/public/contracts/.

Why Contracts Are the Strongest Source

Machine-readable contracts are unique among intelligence sources because they are:

• Formal -- they use standardized schemas with unambiguous semantics
• Published -- they are intended for external consumers to rely on
• Machine-verifiable -- they can be validated against implementations automatically
• Versioned -- they explicitly track breaking changes through version fields

A single OpenAPI specification can contain more behavioral intelligence than the entire official documentation site, because every endpoint, parameter, response schema, and error code is defined with machine precision.

OpenAPI / Swagger

Detection

# Find OpenAPI/Swagger files
find . -maxdepth 5 -type f \( \
  -name "openapi.*" -o -name "swagger.*" -o \
  -name "api-spec.*" -o -name "api-docs.*" \
  \) \( -name "*.json" -o -name "*.yaml" -o -name "*.yml" \) 2>/dev/null

# Check for OpenAPI version markers in YAML/JSON files
grep -rl '"openapi":\|openapi:' --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | head -20
grep -rl '"swagger":\|swagger:' --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | head -20

# Check for hosted spec endpoints (common locations)
# /api-docs, /swagger.json, /openapi.json, /v2/api-docs, /v3/api-docs