Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate JSON Schema and Markdown doc for .sourcekit-lsp/config.json #1849

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

kateinoigakukun
Copy link
Member

@kateinoigakukun kateinoigakukun commented Dec 1, 2024

Providing a JSON schema for the configuration file should improve the developer experience thanks to better auto-completion and diagnostics support provided by some editors.

Additionally, we have been manually maintaining the configuration file format documentation in Documentation/Configuration File.md, but it's easy for the documentation to get out of sync with the actual schema.

This change introduces a new tool, ConfigSchemaGen, that generates a JSON schema and a Markdown document for the configuration file based on the Swift type definitions in the SKOptions module by using swift-syntax.

Plan for vscode-swift integration

VSCode exposes a way to feed a JSON Schema definition for an opening file based on file name:
https://code.visualstudio.com/api/references/contribution-points#contributes.jsonValidation

Contribute a validation schema for a specific type of json file. The url value can be either a local path to a schema file included in the extension or a > remote server URL such as a json schema store.

{
  "contributes": {
    "jsonValidation": [
      {
        "fileMatch": ".jshintrc",
        "url": "https://json.schemastore.org/jshintrc"
      }
    ]
  }
}

Since the schema URL can be a local path and the configuration field can be modified dynamically by extension, we can specify a schema file shipped in the selected Swift toolchain. Or to simplify packaging flow, we can embed the schema file within the sourcekit-lsp binary and provide a CLI interface to print it, then vscode-swift can write it out in its extension storage and feed the file to VSCode.

@kateinoigakukun kateinoigakukun force-pushed the katei/json-schema branch 2 times, most recently from c778056 to 80e9e9b Compare December 1, 2024 04:55
@kateinoigakukun
Copy link
Member Author

@swift-ci test

Providing a JSON schema for the configuration file should improve the
developer experience thanks to better auto-completion and diagnostics
support provided by some editors.

Additionally, we have been manually maintaining the configuration file
format documentation in `Documentation/Configuration File.md`, but it's
easy for the documentation to get out of sync with the actual schema.

This change introduces a new tool, `ConfigSchemaGen`, that generates a
JSON schema and a Markdown document for the configuration file based on
the Swift type definitions in the `SKOptions` module by using
swift-syntax.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant