Telescope

Telescope is a powerful OpenAPI linting tool with real-time VS Code integration. It provides comprehensive validation, custom rule support, and multi-file project awareness.

Features

Validation & Diagnostics

• Real-time Diagnostics - See linting issues as you type in VS Code
• 52 Built-in Rules - Covering OpenAPI best practices and SailPoint standards
• Multi-file Support - Full $ref resolution across your API project
• Custom Rules - Extend with your own TypeScript rules and TypeBox schemas
• Pattern Matching - Glob-based file inclusion/exclusion

Code Intelligence

• Go to Definition - Navigate to $ref targets, operationId definitions, security schemes
• Find All References - Find all usages of schemas, components, and operationIds
• Hover Information - Preview referenced content inline
• Completions - Smart suggestions for $ref values, status codes, media types, tags
• Rename Symbol - Safely rename operationIds and components across your workspace
• Call Hierarchy - Visualize component reference relationships

Editor Features

• Code Lens - Reference counts, response summaries, security indicators
• Inlay Hints - Type hints for $ref targets, required property markers
• Semantic Highlighting - Enhanced syntax highlighting for OpenAPI elements
• Quick Fixes - Auto-add descriptions, summaries, operationIds; convert to kebab-case
• Document Links - Clickable $ref links with precise navigation
• Workspace Symbols - Search operations and components across all files

Embedded Language Support

• Markdown in Descriptions - Full language support with link validation
• Code Block Highlighting - Syntax highlighting for 21+ languages in fenced blocks
• Format Conversion - Convert between JSON and YAML with a single command

See docs/LSP-FEATURES.md for the complete feature reference.

Quick Start

Install the VS Code Extension

Search for "Telescope" in the VS Code marketplace, or install from the command line:

code --install-extension sailpoint.telescope

Configuration

Create .telescope/config.yaml in your project root:

openapi:
  patterns:
    - "**/*.yaml"
    - "**/*.yml"
    - "**/*.json"
    - "!**/node_modules/**"

  # Enable SailPoint-specific rules
  sailpoint: true

  # Override rule severities
  rulesOverrides:
    operation-summary: warn
    parameter-description: error

See docs/CONFIGURATION.md for the full configuration reference.

Architecture

Telescope uses a unified pipeline for consistent diagnostics:

Document → Loader → Indexer → Engine → Diagnostics

flowchart LR
    subgraph Entry["Entry"]
        Client[VS Code Extension]
    end

    subgraph Server["Language Server"]
        LSP[Volar LSP]
        Engine[Linting Engine]
    end

    subgraph Output["Output"]
        Diag[Diagnostics]
        Fixes[Quick Fixes]
    end

    Client --> LSP --> Engine --> Diag --> Client
    Engine --> Fixes --> Client

Loading

For detailed architecture documentation, see ARCHITECTURE.md.

Monorepo Structure

Package	Description
telescope-client	VS Code extension client
telescope-server	Volar language server + linting engine
test-files	Test fixtures and custom rule examples

Built-in Rules

Telescope includes 30 OpenAPI best practice rules and 22 SailPoint-specific rules:

Category	Rules
Core	$ref cycle detection, unresolved reference checking
Operations	operationId, summary, tags, descriptions, responses
Parameters	required fields, examples, descriptions, formats
Schemas	structure validation, allOf, required arrays, defaults
Components	naming conventions

See RULES.md for the complete rule reference.

Custom Rules

Create custom rules in .telescope/rules/:

// .telescope/rules/require-contact.ts
import { defineRule } from "telescope-server";

export default defineRule({
  meta: {
    id: "require-contact",
    number: 1000,
    description: "API must include contact information",
    type: "problem",
    fileFormats: ["yaml", "yml", "json"],
  },
  check(ctx) {
    return {
      Info(info) {
        if (!info.contact) {
          ctx.report({
            message: "Info section must include contact details",
            severity: "error",
            uri: info.uri,
            range: ctx.locate(info.uri, info.pointer),
          });
        }
      },
    };
  },
});

See docs/CUSTOM-RULES.md for the full custom rules guide.

Development

# Install dependencies
pnpm install

# Run tests
bun test

# Build all packages
pnpm build

# Run the extension locally (VS Code)
# Press F5 to launch Extension Development Host

See CONTRIBUTING.md for development guidelines.

Documentation

• LSP Features Reference
• Configuration Reference
• Custom Rules Guide
• Publishing Guide
• Architecture
• Built-in Rules
• Contributing

License

MIT - Copyright (c) 2024 SailPoint Technologies