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: about 1 month ago
JSON representation

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

Awesome Lists containing this project

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.



  See More



  * 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