tessl/npm-autorest--configuration

Configuration management system for AutoRest's REST API client library generator

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Directive Processing

Name: tessl/npm-autorest--configuration
Author: tessl

Configuration directive system for custom transformations, suppressions, and rules processing with support for conditional execution.

Core Types

Directive

interface Directive {
  from?: string[] | string;
  where?: string[] | string;
  reason?: string[];
  suppress?: string[] | string;
  set?: string[] | string;
  transform?: string[] | string;
  "text-transform"?: string[] | string;
  test?: string[] | string;
  debug?: boolean;
}

Configuration directive interface for specifying transformations and rules to apply to specifications.

Properties:

from?: string[] | string - Source specification or document to operate on
where?: string[] | string - JSONPath or selector for target location
reason?: string[] - Reasons or comments explaining the directive
suppress?: string[] | string - Validation rules or warnings to suppress
set?: string[] | string - Values to set at target location
transform?: string[] | string - JavaScript transformation expressions
"text-transform"?: string[] | string - Text transformation expressions
test?: string[] | string - Test conditions for applying the directive
debug?: boolean - Enable debug output for this directive

ResolvedDirective

class ResolvedDirective {
  constructor(directive: Directive);
  
  from: string[];
  where: string[];
  reason?: string[];
  suppress: string[];
  transform: string[];
  test: string[];
  debug: boolean;
  
  get name(): string;
}

Processed and normalized directive with array-normalized properties.

Constructor:

constructor(directive: Directive) - Creates resolved directive from raw directive

Properties:

from: string[] - Normalized source specifications
where: string[] - Normalized target selectors
reason?: string[] - Optional reasons for the directive
suppress: string[] - Normalized suppression rules
transform: string[] - Normalized transformation expressions (includes text-transform)
test: string[] - Normalized test conditions
debug: boolean - Debug flag for detailed output

Methods:

get name(): string - Returns a descriptive name combining from and where properties

Core Functions

resolveDirectives

function resolveDirectives(
  config: AutorestConfiguration,
  predicate?: (each: ResolvedDirective) => boolean
): ResolvedDirective[];

Resolves and expands all directives from configuration, including macro expansion and conditional filtering.

Parameters:

config: AutorestConfiguration - Configuration containing directives and macro declarations
predicate?: (each: ResolvedDirective) => boolean - Optional filter condition for directives

Returns:

ResolvedDirective[] - Array of resolved and expanded directive objects

Example:

import { resolveDirectives } from "@autorest/configuration";

// Resolve all directives
const allDirectives = resolveDirectives(config);

// Resolve only transform directives
const transformDirectives = resolveDirectives(config, 
  directive => directive.transform.length > 0
);

// Resolve only suppression directives
const suppressDirectives = resolveDirectives(config,
  directive => directive.suppress.length > 0
);

Methods:

get name(): string - Returns descriptive name combining from and where properties

Directive Types

Suppression Directives

Suppress validation warnings or errors for specific scenarios:

const suppressDirective: Directive = {
  from: "swagger-document",
  where: "$.paths.*.*.responses",
  suppress: ["R3016"], // Suppress specific validation rule
  reason: ["Legacy API maintains this pattern for backward compatibility"]
};

Transformation Directives

Apply JavaScript transformations to modify specifications:

const transformDirective: Directive = {
  from: "swagger-document", 
  where: "$.paths.*.*",
  transform: [
    "return $.operationId = $.operationId || `${$.method}_${$.path.replace(/[^a-zA-Z0-9]/g, '_')}`"
  ],
  reason: ["Generate operation IDs for operations missing them"]
};

Text Transformation Directives

Apply text-based transformations:

const textTransformDirective: Directive = {
  from: "code-model-v4",
  where: "$.operationGroups[*].operations[*].language.default.name",
  "text-transform": [
    "return $.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase()"
  ]
};

Set Directives

Set specific values at target locations:

const setDirective: Directive = {
  from: "swagger-document",
  where: "$.info.version", 
  set: ["1.0.0"],
  reason: ["Override version for consistency"]
};

Test Directives

Apply test conditions for directive execution:

const conditionalDirective: Directive = {
  from: "swagger-document",
  where: "$.paths.*.*",
  test: ["$.operationId === undefined"],
  transform: ["return $.operationId = 'GeneratedOperation'"],
  reason: ["Add operation ID only if missing"]
};

Directive Processing Functions

processDirectives

function processDirectives(
  directives: Directive[],
  context: any
): ResolvedDirective[];

Processes an array of directives and returns resolved directives for execution.

Parameters:

directives: Directive[] - Array of raw directives to process
context: any - Context object for directive evaluation

Returns:

ResolvedDirective[] - Array of processed and normalized directives

Usage Examples

Basic Directive Usage

import { Directive, ResolvedDirective } from "@autorest/configuration";

const directives: Directive[] = [
  {
    from: "swagger-document",
    where: "$.info.title",
    set: "My API v2",
    reason: ["Update API title for new version"]
  },
  {
    suppress: ["R2029"],
    reason: ["Suppress parameter description requirement"]
  }
];

// Process directives
const resolvedDirectives = directives.map(d => new ResolvedDirective(d));

// Access resolved properties
resolvedDirectives.forEach(directive => {
  console.log(`Directive: ${directive.name}`);
  console.log(`Suppresses: ${directive.suppress}`);
  console.log(`Transforms: ${directive.transform}`);
});

Complex Transformation

const complexDirective: Directive = {
  from: "swagger-document",
  where: "$.paths.*.*",
  transform: [
    `
    // Add standard error responses if missing
    if (!$.responses['400']) {
      $.responses['400'] = {
        description: "Bad Request",
        schema: { $ref: "#/definitions/Error" }
      };
    }
    if (!$.responses['500']) {
      $.responses['500'] = {
        description: "Internal Server Error", 
        schema: { $ref: "#/definitions/Error" }
      };
    }
    return $;
    `
  ],
  reason: ["Ensure all operations have standard error responses"]
};

Conditional Processing

const conditionalDirectives: Directive[] = [
  {
    from: "swagger-document",
    where: "$.paths.*.*",
    test: ["$.deprecated === true"],
    transform: ["$.summary = '[DEPRECATED] ' + ($.summary || '')"],
    reason: ["Mark deprecated operations in summary"]
  },
  {
    from: "swagger-document", 
    where: "$.definitions.*",
    test: ["$.required && $.required.length === 0"],
    transform: ["delete $.required; return $"],
    reason: ["Remove empty required arrays"]
  }
];

Directive Execution Context

Directives are executed within a controlled context that provides:

Safe Evaluation

Sandboxed execution - Directives run in a secure sandbox
Limited API surface - Only safe operations are available
Timeout protection - Long-running directives are terminated

Context Variables

Current document - Access to the document being processed
Configuration - Access to current AutoRest configuration
Metadata - Information about the processing pipeline
Utility functions - Helper functions for common operations

Error Handling

Syntax errors - Clear error messages for invalid JavaScript
Runtime errors - Detailed error information with context
Validation errors - Schema validation for directive results

Advanced Features

Multiple Document Processing

Directives can operate across multiple specification documents:

const crossDocDirective: Directive = {
  from: ["swagger-document", "openapi-document"],
  where: "$.info",
  transform: [
    "$.contact = { email: 'api-support@company.com' }; return $"
  ]
};

Debug Mode

Enable detailed debugging information:

const debugDirective: Directive = {
  from: "swagger-document",
  where: "$.paths.*.*", 
  transform: ["console.log('Processing:', $.operationId); return $"],
  debug: true
};

Directive Chaining

Directives are processed in order and can build upon each other:

const chainedDirectives: Directive[] = [
  // First, normalize operation IDs
  {
    from: "swagger-document",
    where: "$.paths.*.*",
    transform: ["return $.operationId = $.operationId || 'operation'"]
  },
  // Then, ensure they're unique
  {
    from: "swagger-document", 
    where: "$.paths.*.*",
    transform: [
      "const existing = globalThis.operationIds = globalThis.operationIds || new Set();" +
      "let id = $.operationId; let counter = 1;" +
      "while (existing.has(id)) { id = $.operationId + counter++; }" +
      "existing.add(id); return $.operationId = id;"
    ]
  }
];