@apistudio/apim-cli/node_modules/@apic/smith-inventory/src/resources/spectral-rulesets/README.md

CLI for API Management Products

# Spectral Rulesets for Schema Components

This directory contains Spectral rulesets for validating schema components in the OpenAPI specification.

## Overview

The rulesets are organized as follows:

- Individual ruleset files for each schema component (e.g., `api.ruleset.js`, `cors.ruleset.js`, etc.)
- A combined ruleset file (`combined-ruleset.js`) that imports all individual rulesets
- Utility scripts for generating and testing rulesets

## Components

The rulesets cover the following schema components:

- API
- CORS
- CountLimit
- CountLimitDef
- Quota
- Product
- Plan
- StagedPolicySequence
- Scope
- ValidateAPISpecification
- Project
- URISchemes
- Telemetry
- Properties
- LoadBalancer
- AWSLambda
- SetAuthorization
- Invoke
- GlobalPolicy
- IAM
- ServiceResultCache
- OutboundAlias
- OutboundAnonymous
- DataMasking
- Route
- HTTPEndpoint
- MockEndpoint
- MockResponse
- Set
- RateLimitDefinition
- RateLimit
- Redact
- Remove
- Transform
- DataPowerAssembly
- Switch
- If
- Try
- OperationSwitch
- FreeFlowPolicySequence
- JavaScript
- LuaScript
- EnforceCircuitBreaker
- TokenMediation
- Block
- Parse
- Cache
- Antivirus
- SQLInjectionFilter

## Enhanced Ruleset Features

The enhanced rulesets provide detailed validation for all properties inside the "spec" field of each schema component:

1. **Basic Field Validation**:
   - Existence checks for required fields
   - Type validation for all fields
   - Pattern validation for string fields

2. **Nested Object Validation**:
   - Validation for properties within nested objects
   - Required field checks at all levels
   - Type validation for nested properties

3. **Array Validation**:
   - Type checking for array items
   - Validation for objects within arrays
   - Required field checks for objects in arrays

4. **Enum Validation**:
   - Validation for fields with enumerated values
   - Ensures values match the allowed set

5. **Additional Properties Control**:
   - Prevents unexpected properties in objects
   - Enforces schema structure

## Statistics

- Total components: 49
- Total validation rules: 1256
- Rules specifically for spec field properties: 423

## Usage

To use the combined ruleset in your code:

```javascript
import { getCombinedRuleset } from './spectral-rulesets/combined-ruleset.js';

async function validateWithSpectral() {
  const combinedRuleset = await getCombinedRuleset();
  
  // Use the ruleset with Spectral
  // Example:
  // const spectral = new Spectral();
  // spectral.setRuleset(combinedRuleset["api.ibm.com_v1_api.ruleset.yaml"]);
  // const results = await spectral.run(yourApiDocument);
}
```

## Utility Scripts

- `generate-rulesets.js`: Generates basic ruleset files for all schema components
- `enhanced-generate-rulesets.js`: Generates detailed rulesets with comprehensive spec field validation
- `convert-to-esm.js`: Converts CommonJS ruleset files to ES modules
- `test-ruleset.js`: Tests the basic combined ruleset
- `test-enhanced-ruleset.js`: Tests the enhanced combined ruleset

## Sample Rules

Here are some examples of the detailed spec field rules generated for the API component:

```
spec-api-spec-required: The api-spec field is required in the spec
spec-api-spec-type: The api-spec field must be of type object
spec-api-spec-$path-required: The $path field is required in api-spec
spec-api-spec-$path-type: The $path field in api-spec must be of type string
spec-uriSchemes-type: The uriSchemes field must be of type object
```

## Development

To add a new ruleset:

1. Create a new file named `[component-name].ruleset.js`
2. Define the rules following the Spectral ruleset format
3. Export the ruleset as the default export
4. Update the combined ruleset to include the new component

To regenerate all enhanced rulesets:

```bash
cd packages/inventory/src/resources/spectral-rulesets
node enhanced-generate-rulesets.js

// Made with Bob