@skedulo/style-system

Skedulo Style System

A unified rules-as-code writing style system for Skedulo. This project enforces style guidelines via a CLI linter, auto-generates documentation, and provides AI-powered rewriting suggestions.

Features

• CLI Linter: Checks Markdown files against Skedulo's style rules.
• Documentation Generator: Builds a Markdown style guide from the rule definitions.
• CI Integration: GitHub Actions to enforce style on Pull Requests.
• AI Assistant: Uses Gemini to suggest rewrites for style violations.
• Rule Engine: TypeScript-based rule definitions for easy maintenance.

Installation

Using Devbox (Recommended for Development)

# Enter development environment (installs Node.js + dependencies automatically)
devbox shell

# Or run commands directly
devbox run test

See docs/ for complete documentation including devbox setup, commands, and usage guides.

Using npm

npm install

Usage

CLI Commands

style:lint - Check Markdown files for style violations

When installed as an npm package or oclif plugin, use:

# Standard usage
skedulo style:lint <file.md>

# With JSON output
skedulo style:lint <file.md> --format=json

# Examples
skedulo style:lint README.md
skedulo style:lint docs/user-guide.md --format=json

Arguments:

• file - Path to markdown file (required)

Flags:

• --format - Output format: text (default) or json

Output:

• Text format shows violations with ✅ ℹ️ ⚠️ ❌ indicators
• JSON format provides structured data for programmatic use

Development Testing

Run the linter during development:

# Using devbox (recommended)
devbox run test                    # Test on README.md
devbox run test:json               # Test with JSON output

# Using ts-node directly
npx ts-node src/commands/style/lint.ts path/to/file.md
npx ts-node src/commands/style/lint.ts path/to/file.md --format=json

# Using npm script
npm run lint path/to/file.md

Generate Documentation

Generate the docs/style-guide.generated.md file from the source rules:

# Using devbox
devbox run docs

# Using npm
npm run generate:style-docs

CI/CD Integration

This repository includes GitHub Actions workflows:

• Skeddy Style Bot (.github/workflows/style-pr-bot.yml): 🤖 Automated PR reviewer that posts inline suggestions directly on your PRs with one-click fixes using GitHub's suggestion feature.

Adding to Your Repository

See GitHub Actions Setup Guide for detailed instructions on adding the style linter to your own repository's CI/CD pipeline.

Configuration

To enable the AI features in the Style Bot, you must add the following secret to your GitHub repository:

• GEMINI_API_KEY: Your Google Gemini API key.

Documentation

Complete documentation is organized in the docs/ directory:

• Documentation Index - Complete guide to all documentation
• Skeddy Bot Guide - 🤖 Automated PR reviewer with inline suggestions
• Devbox Setup Guide - Local development environment
• Command Reference - All available commands
• Testing Gemini AI - Test AI integration
• GitHub Actions Setup - Add to your CI/CD pipeline
• Using as Plugin - oclif plugin integration
• Publishing Guide - How to publish to npm
• Style Guide - Auto-generated style rules

Development

Project Structure

• src/engine/: Core rule definitions and linter logic
• src/commands/: CLI command implementations (oclif)
• src/ai/: AI model interface and Gemini client
• scripts/: Helper scripts (docs generation, bot script)
• docs/: Complete project documentation

Adding a New Rule

• Open src/engine/rules.ts
• Add a new rule object to the rules array
• Specify the type (e.g., regex), severity, description, and suggestion
• Run npm run generate:style-docs to update the documentation

Building

npm run build

See docs/development/ for detailed development guides.