Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jpsim/SourceKitten

An adorable little framework and command line tool for interacting with SourceKit.
https://github.com/jpsim/SourceKitten

Last synced: 3 months ago
JSON representation

An adorable little framework and command line tool for interacting with SourceKit.

Host: GitHub
URL: https://github.com/jpsim/SourceKitten
Owner: jpsim
License: mit
Created: 2014-08-17T20:07:25.000Z (about 10 years ago)
Default Branch: main
Last Pushed: 2024-05-16T21:57:30.000Z (6 months ago)
Last Synced: 2024-05-18T13:41:23.927Z (6 months ago)
Language: Swift
Homepage:
Size: 9.19 MB
Stars: 2,280
Watchers: 40
Forks: 221
Open Issues: 98
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

awesome-ios - SourceKitten - An adorable little framework and command line tool for interacting with SourceKit. (Tools / Web View)
awesome-ios-star - SourceKitten - An adorable little framework and command line tool for interacting with SourceKit. (Tools / Web View)
awesome-system-swift - SourceKitten - line tool for interacting with **SourceKit**. (The Index / System Libraries)

README

# SourceKitten

An adorable little framework and command line tool for interacting with [SourceKit][uncovering-sourcekit].

SourceKitten links and communicates with `sourcekitd.framework` to parse the Swift AST, extract comment docs for Swift or Objective-C projects, get syntax data for a Swift file and lots more!

![SwiftPM](https://github.com/jpsim/SourceKitten/workflows/SwiftPM/badge.svg)

## Installation

Building SourceKitten requires Xcode 13.3 or later or a Swift 5.6
toolchain or later with the Swift Package Manager.

SourceKitten typically supports previous versions of SourceKit.

### Homebrew

Run `brew install sourcekitten`.

### Swift Package Manager

Run `swift build` in the root directory of this project.

### Bazel

Add the following to your `WORKSPACE` file:

```python
SOURCEKITTEN_VERSION = "SOME_VERSION"
SOURCEKITTEN_SHA = "SOME_SHA"
http_archive(
name = "com_github_jpsim_sourcekitten",
url = "https://github.com/jpsim/SourceKitten/archive/refs/tags/%s.tar.gz" % (SOURCEKITTEN_VERSION),
sha256 = SOURCEKITTEN_SHA,
strip_prefix = "SourceKitten-%s" % SOURCEKITTEN_VERSION
)
```

Then run: `bazel run @com_github_jpsim_sourcekitten//:sourcekitten -- -h`

### Xcode (via Make)

Run `make install` in the root directory of this project.

### Package

Download and open SourceKitten.pkg from the [releases tab](https://github.com/jpsim/SourceKitten/releases).

## Command Line Usage

Once SourceKitten is installed, you may use it from the command line.

```
$ sourcekitten help
OVERVIEW: An adorable little command line tool for interacting with SourceKit

USAGE: sourcekitten

OPTIONS:
--version Show the version.
-h, --help Show help information.

SUBCOMMANDS:
complete Generate code completion options
doc Print Swift or Objective-C docs as JSON
format Format Swift file
index Index Swift file and print as JSON
module-info Obtain information about a Swift module and print as JSON
request Run a raw SourceKit request
structure Print Swift structure information as JSON
syntax Print Swift syntax information as JSON
version Display the current version of SourceKitten

See 'sourcekitten help ' for detailed help.
```

## How is SourceKit resolved?

SourceKitten searches for SourceKit in the following order:

* `$XCODE_DEFAULT_TOOLCHAIN_OVERRIDE`
* `$TOOLCHAIN_DIR`
* `xcrun -find swift`
* `/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
* `/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
* `~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`
* `~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain`

On Linux, SourceKit is expected to be located in
`/usr/lib/libsourcekitdInProc.so` or specified by the `LINUX_SOURCEKIT_LIB_PATH`
environment variable.

## Projects Built With SourceKitten

* [SwiftLint](https://github.com/realm/SwiftLint):
A tool to enforce Swift style and conventions.
* [Jazzy](https://github.com/realm/Jazzy):
Soulful docs for Swift & Objective-C.
* [Sourcery](https://github.com/krzysztofzablocki/Sourcery):
Meta-programming for Swift, stop writing boilerplate code.
* [SwiftyMocky](https://github.com/MakeAWishFoundation/SwiftyMocky):
Framework for mock generation.
* [SourceKittenDaemon](https://github.com/terhechte/SourceKittenDaemon):
Swift Auto Completions for any Text Editor.
* [SourceDocs](https://github.com/eneko/SourceDocs):
Command Line Tool that generates Markdown documentation from inline source
code comments.
* [Cuckoo](https://github.com/Brightify/Cuckoo):
First boilerplate-free mocking framework for Swift.
* [IBAnalyzer](https://github.com/fastred/IBAnalyzer): Find common xib and
storyboard-related problems without running your app or writing unit tests.
* [Taylor](https://github.com/yopeso/Taylor): Measure Swift code metrics and
get reports in Xcode, Jenkins and other CI platforms.

* https://github.com/appsquickly/TyphoonSwift
* https://github.com/banjun/bansan
* https://github.com/Beaver/BeaverCodeGen
* https://github.com/Ben-G/Meet
* https://github.com/dfreemanRIIS/ETAMock
* https://github.com/dostu/SwiftMetric
* https://github.com/draven-archive/MetaKit
* https://github.com/geosor/SwiftVisualizer
* https://github.com/godfreynolan/AgileSwiftTst
* https://github.com/godfreynolan/CodeCraftsman
* https://github.com/ilyapuchka/dipgen
* https://github.com/ilyapuchka/SourceKittenEditorExtension
* https://github.com/interstateone/Unused
* https://github.com/ishkawa/DIKit
* https://github.com/IvanovGeorge/FBAuth
* https://github.com/jmpg93/NavigatorSwift
* https://github.com/jpmartha/Pancake
* https://github.com/jpweber/Kontext
* https://github.com/KenichiroSato/CatDogTube
* https://github.com/klundberg/grift
* https://github.com/kovtun1/DependenciesGraph
* https://github.com/lvsti/Bridgecraft
* https://github.com/maralla/completor-swift
* https://github.com/marcsnts/Shopify-Winter18-Technical
* https://github.com/momentumworks/Formula
* https://github.com/nevil/UNClassDiagram
* https://github.com/norio-nomura/LinuxSupportForXcode
* https://github.com/paulofaria/swift-package-crawler-data
* https://github.com/rajat-explorer/Github-Profiler
* https://github.com/rockbruno/swiftshield
* https://github.com/S2dentik/Enlight
* https://github.com/seanhenry/SwiftMockGeneratorForXcode
* https://github.com/sharplet/swiftags
* https://github.com/siejkowski/Croupier
* https://github.com/SwiftKit/CuckooGenerator
* https://github.com/SwiftKit/Torch
* https://github.com/SwiftTools/SwiftFelisCatus
* https://github.com/swizzlr/lux
* https://github.com/tid-kijyun/XcodeSourceEditorExtension-ProtocolImplementation
* https://github.com/tjarratt/fake4swift
* https://github.com/tkohout/Genie
* https://github.com/tomquist/MagicMirror
* https://github.com/TurfDb/TurfGen
* https://github.com/vadimue/AwesomeWeather
* https://github.com/yonaskolb/Beak
* https://github.com/zenzz/vs-swifter-server
* https://github.com/zenzz/zxxswifter-server
* https://github.com/scribd/Weaver
* https://github.com/Nonchalant/FactoryProvider

## Complete

Running `sourcekitten complete --file file.swift --offset 123` or
`sourcekitten complete --text "0." --offset 2` will print out code completion
options for the offset in the file/text provided:

```json
[{
"descriptionKey" : "advancedBy(n: Distance)",
"associatedUSRs" : "s:FSi10advancedByFSiFSiSi s:FPSs21RandomAccessIndexType10advancedByuRq_S__Fq_Fqq_Ss16ForwardIndexType8Distanceq_ s:FPSs16ForwardIndexType10advancedByuRq_S__Fq_Fqq_S_8Distanceq_ s:FPSs10Strideable10advancedByuRq_S__Fq_Fqq_S_6Strideq_ s:FPSs11_Strideable10advancedByuRq_S__Fq_Fqq_S_6Strideq_",
"kind" : "source.lang.swift.decl.function.method.instance",
"sourcetext" : "advancedBy(<#T##n: Distance##Distance#>)",
"context" : "source.codecompletion.context.thisclass",
"typeName" : "Int",
"moduleName" : "Swift",
"name" : "advancedBy(n: Distance)"
},
{
"descriptionKey" : "advancedBy(n: Self.Distance, limit: Self)",
"associatedUSRs" : "s:FeRq_Ss21RandomAccessIndexType_SsS_10advancedByuRq_S__Fq_FTqq_Ss16ForwardIndexType8Distance5limitq__q_",
"kind" : "source.lang.swift.decl.function.method.instance",
"sourcetext" : "advancedBy(<#T##n: Self.Distance##Self.Distance#>, limit: <#T##Self#>)",
"context" : "source.codecompletion.context.superclass",
"typeName" : "Self",
"moduleName" : "Swift",
"name" : "advancedBy(n: Self.Distance, limit: Self)"
},
...
]
```

To use the iOS SDK, pass `-sdk` and `-target` arguments preceded by `--`:
```
sourcekitten complete --text "import UIKit ; UIColor." --offset 22 -- -target arm64-apple-ios9.0 -sdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS9.0.sdk
```

## Doc

Running `sourcekitten doc` will pass all arguments after what is parsed to
`xcodebuild` (or directly to the compiler, SourceKit/clang, in the
`--single-file` mode).

### Example usage

1. `sourcekitten doc -- -workspace SourceKitten.xcworkspace -scheme SourceKittenFramework`
2. `sourcekitten doc --single-file file.swift -- -j4 file.swift`
3. `sourcekitten doc --module-name Alamofire -- -project Alamofire.xcodeproj`
4. `sourcekitten doc -- -workspace Haneke.xcworkspace -scheme Haneke`
5. `sourcekitten doc --objc Realm/Realm.h -- -x objective-c -isysroot $(xcrun --show-sdk-path) -I $(pwd)`

## Structure

Running `sourcekitten structure --file file.swift` or `sourcekitten structure --text "struct A { func b() {} }"` will return a JSON array of structure information:

```json
{
"key.substructure" : [
{
"key.kind" : "source.lang.swift.decl.struct",
"key.offset" : 0,
"key.nameoffset" : 7,
"key.namelength" : 1,
"key.bodyoffset" : 10,
"key.bodylength" : 13,
"key.length" : 24,
"key.substructure" : [
{
"key.kind" : "source.lang.swift.decl.function.method.instance",
"key.offset" : 11,
"key.nameoffset" : 16,
"key.namelength" : 3,
"key.bodyoffset" : 21,
"key.bodylength" : 0,
"key.length" : 11,
"key.substructure" : [

],
"key.name" : "b()"
}
],
"key.name" : "A"
}
],
"key.offset" : 0,
"key.diagnostic_stage" : "source.diagnostic.stage.swift.parse",
"key.length" : 24
}
```

## Syntax

Running `sourcekitten syntax --file file.swift` or `sourcekitten syntax --text "import Foundation // Hello World"` will return a JSON array of syntax highlighting information:

```json
[
{
"offset" : 0,
"length" : 6,
"type" : "source.lang.swift.syntaxtype.keyword"
},
{
"offset" : 7,
"length" : 10,
"type" : "source.lang.swift.syntaxtype.identifier"
},
{
"offset" : 18,
"length" : 14,
"type" : "source.lang.swift.syntaxtype.comment"
}
]
```

## Request

Running `sourcekitten request --yaml [FILE|TEXT]` will execute a sourcekit request with the given yaml. For example:

```yaml
key.request: source.request.cursorinfo
key.sourcefile: "/tmp/foo.swift"
key.offset: 8
key.compilerargs:
- "/tmp/foo.swift"
```

## SourceKittenFramework

Most of the functionality of the `sourcekitten` command line tool is actually encapsulated in a framework named SourceKittenFramework.

If you’re interested in using SourceKitten as part of another tool, or perhaps extending its functionality, take a look at the SourceKittenFramework source code to see if the API fits your needs.

*Note: SourceKitten is written entirely in Swift, and the SourceKittenFramework API is not designed to interface with Objective-C.*

## License

MIT licensed.

[uncovering-sourcekit]: http://jpsim.com/uncovering-sourcekit