@rbleattler/omp-ts-typegen 0.2025.0

package/schema-explained.md

@@ -0,0 +1,192 @@
+# Understanding Oh My Posh Schema.json
+
+This document explains the structure and purpose of the Oh My Posh `schema.json` file, which defines the configuration format for Oh My Posh themes.
+
+## Overview
+
+Oh My Posh uses a JSON schema (following the JSON Schema Draft-07 specification) to:
+
+1. Validate theme configuration files
+2. Provide auto-completion in editors with JSON schema support
+3. Define the structure of themes in a standardized way
+4. Document available options for theme creators
+
+## Schema Structure
+
+### Root Schema Properties
+
+The schema's root properties define the high-level configuration options:
+
+- **`final_space`**: Whether to add a space at the end of the prompt
+- **`enable_cursor_positioning`**: Enables precise cursor positioning features
+- **`shell_integration`**: Adds FTCS command marks for shell integration
+- **`pwd`**: Controls OSC99/7/51 working directory communication
+- **`upgrade`**: Configuration for upgrade notifications
+- **`patch_pwsh_bleed`**: Fixes PowerShell color bleeding issues
+- **`console_title_template`**: Template for the terminal window title
+- **`terminal_background`**: Background color of the terminal
+- **`blocks`**: The main array of prompt blocks (core structure of the prompt)
+- **`tooltips`**: Custom tooltips for specific commands
+- **`transient_prompt`**: Configuration for simplified repeated prompts
+- **`valid_line`**, **`error_line`**: PowerShell-specific prompt variants
+- **`secondary_prompt`**: Configuration for multi-line input continuation
+- **`debug_prompt`**: PowerShell debugging prompt configuration
+- **`palette`**, **`palettes`**: Color palette definitions
+- **`cycle`**: Color cycling configuration
+- **`accent_color`**: Theme accent color
+- **`var`**: Custom variables for use in templates
+
+### Definitions Section
+
+The `definitions` section contains reusable schema components:
+
+#### Color Definitions
+
+```json
+"color": {
+  "anyOf": [
+    {
+      "$ref": "#/definitions/color_string"
+    },
+    {
+      "$ref": "#/definitions/palette_reference"
+    }
+  ]
+}
+```
+
+Colors can be specified as direct color strings or as palette references (e.g., `p:blue`).
+
+#### Block Definition
+
+Blocks are the main structural elements of the prompt:
+
+```json
+"block": {
+  "type": "object",
+  "description": "https://ohmyposh.dev/docs/configuration/block",
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["prompt", "rprompt"],
+      "default": "prompt"
+    },
+    "alignment": {
+      "type": "string",
+      "enum": ["left", "right"],
+      "default": "left"
+    },
+    "segments": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/segment"
+      }
+    },
+    // ...other properties
+  }
+}
+```
+
+#### Segment Definition
+
+Segments are the individual components within blocks that display information:
+
+```json
+"segment": {
+  "type": "object",
+  "required": ["type", "style"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["git", "node", "python", /* many other segment types */]
+    },
+    "style": {
+      "anyOf": [
+        {
+          "enum": ["plain", "powerline", "diamond", "accordion"]
+        },
+        {
+          "type": "string"
+        }
+      ]
+    },
+    // ...many other properties
+  }
+}
+```
+
+The schema then uses conditional validation (`if`/`then`) to define specific properties for each segment type.
+
+## Segment Types
+
+Oh My Posh includes a wide variety of segment types, each with specific functionality:
+
+### SCM Segments
+
+- **`git`**: Git repository information
+- **`mercurial`**: Mercurial repository information
+- **`fossil`**: Fossil repository information
+- **`sapling`**: Sapling repository information
+- **`plastic`**: Plastic SCM information
+- **`svn`**: SVN repository information
+
+### Language/Runtime Segments
+
+- **`node`**: Node.js version and environment
+- **`python`**: Python version and virtual environment
+- **`ruby`**: Ruby version
+- **`java`**: Java version
+- **`go`**: Go version
+- **`rust`**: Rust version
+- **`dotnet`**: .NET version
+- **`php`**: PHP version
+- And many more language-specific segments
+
+### Cloud/Service Segments
+
+- **`aws`**: AWS profile and region
+- **`az`**: Azure information
+- **`gcp`**: Google Cloud Platform information
+- **`kubernetes`**: Kubernetes context
+
+### System Segments
+
+- **`os`**: Operating system information
+- **`path`**: Current directory path
+- **`time`**: Current time
+- **`session`**: SSH session indicator
+- **`battery`**: Battery status
+
+### CLI Tool Segments
+
+- **`npm`**: NPM information
+- **`yarn`**: Yarn information
+- **`pnpm`**: PNPM information
+- **`terraform`**: Terraform workspace
+
+## How Validation Works
+
+The schema uses several validation techniques:
+
+1. **Required properties**: Ensures essential properties are present
+2. **Enum validation**: Restricts values to specific options
+3. **Pattern validation**: Validates string format (like colors)
+4. **Conditional validation**: Different validation rules based on segment type
+5. **Default values**: Provides sensible defaults where applicable
+
+## Example Configuration Flow
+
+When a user creates an Oh My Posh theme:
+
+1. The theme defines one or more blocks
+2. Each block contains one or more segments
+3. Each segment has a type, style, and segment-specific properties
+4. Colors can be defined directly or through palettes
+5. Templates within segments define how information is displayed
+
+## References
+
+- [Oh My Posh Documentation](https://ohmyposh.dev/docs)
+- [JSON Schema Specification](https://json-schema.org/specification.html)
+
+This schema enables the rich, customizable prompts that Oh My Posh is known for, while providing clear validation and documentation for theme creators.

package/scripts/generate-types.ts

@@ -0,0 +1,184 @@
+import fs from 'fs/promises';
+import path from 'path';
+import axios from 'axios';
+import {
+  quicktype,
+  InputData,
+  jsonInputForTargetLanguage,
+  JSONSchemaInput,
+  FetchingJSONSchemaStore
+} from "quicktype-core";
+
+const SCHEMA_URL = 'https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/refs/heads/main/themes/schema.json';
+const OUTPUT_DIR = path.join(process.cwd(), 'src', 'types');
+const OUTPUT_FILE = path.join(OUTPUT_DIR, 'omp.ts');
+const SCHEMA_CACHE_FILE = path.join(process.cwd(), 'cache', 'schema.json');
+
+async function main() {
+  // Dynamically import chalk (ESM module)
+  const { default: chalk } = await import('chalk');
+
+  console.log(chalk.blue('Starting TypeScript type generation...'));
+
+  try {
+    // Ensure output directories exist
+    await fs.mkdir(path.join(process.cwd(), 'cache'), { recursive: true });
+    await fs.mkdir(OUTPUT_DIR, { recursive: true });
+
+    // Fetch the latest schema from the Oh My Posh repository
+    console.log(chalk.yellow('Fetching schema from Oh My Posh repository...'));
+    const response = await axios.get(SCHEMA_URL);
+    const schema = response.data;
+
+    // This is a dumb workaround but maybe someday I can get the schema file to not have this title...
+    // Remove the title property from definitions.segment to avoid dumb naming
+    //TODO: Create an issue on the Oh My Posh repository to remove the title property from the segment definition in the schema file... or fix it myself with a PR
+    // PR pending: [fix: update segment title in schema.json #6244](https://github.com/JanDeDobbeleer/oh-my-posh/pull/6244)
+    if (schema.definitions && schema.definitions.segment) {
+      delete schema.definitions.segment.title;
+    }
+
+    // Cache the schema for future comparisons
+    await fs.writeFile(SCHEMA_CACHE_FILE, JSON.stringify(schema, null, 2), { flag: 'w' });
+
+
+    console.log(chalk.green('Schema fetched and cached successfully.'));
+
+    // Generate TypeScript types using quicktype with the provided options
+    console.log(chalk.yellow('Generating TypeScript types...'));
+
+
+
+    // Set up quicktype options based on the available options in quicktype-core
+    const quicktypeOptions = {
+      // if debug add debugPrintGraph: true
+      // This will print the type graph to the console at every processing step
+      debugPrintGraph: process.features.debug ? true : false,
+
+      // Check Provenance:
+      // Check that we're propagating all type attributes (unless we actually can't)
+      //! Experimenting with this
+      checkProvenance: true,
+
+      inferMaps: true,
+      inferEnums: true,
+      inferDateTimes: true,
+      inferIntegerStrings: true,
+      inferBooleanStrings: true,
+      inferUUIDStrings: true, // Renamed from inferUuids to match quicktype's API
+      combineClasses: true,
+      allPropertiesOptional: false,
+      alphabetizeProperties: true, // Sort properties for better readability
+      rendererOptions: {
+        "explicit-unions": true,
+        "runtime-typecheck": true,
+        "acronym-style": "original",
+        "converters": "top-level",
+        "raw-type": "json",
+        "prefer-unions": true,
+        "prefer-types": true
+      },
+      // Additional options from Options interface
+      fixedTopLevels: true,
+      leadingComments: undefined,
+      density: "normal" as const, // Available options: 'normal', 'dense'
+      useStructuralFeatures: true
+    };
+
+    // Generate the types using quicktype API
+    const { lines } = await quicktypeJSONSchema("typescript", "OhMyPosh", JSON.stringify(schema), quicktypeOptions);
+
+    // Add a header to the generated file
+    const header = `/**
+ * Oh My Posh TypeScript definitions
+ *
+ * Generated from schema: ${SCHEMA_URL}
+ * Generated on: ${new Date().toISOString()}
+ *
+ * @see https://ohmyposh.dev/docs/
+ */
+
+/* eslint-disable */
+/* tslint:disable */
+
+`;
+
+    let typesContent = header + lines.join('\n');
+
+    // Ensure the OhMyPosh type is properly exported
+    // This adds an export statement if one isn't already present
+    if (!typesContent.includes('export interface OhMyPosh')) {
+      typesContent = typesContent.replace(
+        'interface OhMyPosh',
+        'export interface OhMyPosh'
+      );
+    }
+
+    // Write the generated TypeScript types to the output file
+    await fs.writeFile(OUTPUT_FILE, typesContent, { flag: 'w' });
+    console.log(chalk.green(`TypeScript types generated successfully at ${OUTPUT_FILE}`));
+
+  } catch (error) {
+    // Dynamically import chalk again to ensure it's available in the catch block
+    const { default: chalk } = await import('chalk');
+    console.error(chalk.red('Error generating TypeScript types:'), error);
+    process.exit(1);
+  }
+}
+
+
+// This function is not currently used. But it can be used to generate types from JSON input.
+// We'll keep it here for reference / future use.
+async function quicktypeJSON(
+  targetLanguage: string,
+  typeName: string,
+  jsonString: string
+) {
+  const jsonInput = jsonInputForTargetLanguage(targetLanguage);
+
+  // We could add multiple samples for the same desired
+  // type, or many sources for other types. Here we're
+  // just making one type from one piece of sample JSON.
+  await jsonInput.addSource({
+    name: typeName,
+    samples: [jsonString]
+  });
+
+  const inputData = new InputData();
+  inputData.addInput(jsonInput);
+
+  return await quicktype({
+    inputData,
+    lang: targetLanguage
+  });
+}
+
+async function quicktypeJSONSchema(
+  targetLanguage: string,
+  typeName: string,
+  jsonSchemaString: string,
+  options: any = {}
+) {
+  const schemaInput = new JSONSchemaInput(new FetchingJSONSchemaStore());
+
+  // We could add multiple schemas for multiple types,
+  // but here we're just making one type from JSON schema.
+  await schemaInput.addSource({ name: typeName, schema: jsonSchemaString });
+
+  const inputData = new InputData();
+  inputData.addInput(schemaInput);
+
+  // Pass all options to quicktype along with the required inputData and lang
+  return await quicktype({
+    ...options,
+    inputData,
+    lang: targetLanguage
+  });
+}
+
+main().catch(async error => {
+  // Dynamically import chalk in catch block
+  const { default: chalk } = await import('chalk');
+  console.error(chalk.red('Unhandled error:'), error);
+  process.exit(1);
+});