tailor

Wiki • Installation • Usage • Features • Developers • License

[Tailor][] is a cross-platform [static analysis][] and [lint][] tool for source code written in Apple's [Swift][] programming language. It analyzes your code to ensure consistent styling and help avoid bugs. [static analysis]: https://en.wikipedia.org/wiki/Static_program_analysis [lint]: https://en.wikipedia.org/wiki/Lint_(software) ## [Tailor][]. Cross-platform static analyzer and linter for [Swift][]. [Tailor]: https://tailor.sh [Swift]: https://swift.org Tailor supports Swift 3.0.1 out of the box and helps enforce style guidelines outlined in the [The Swift Programming Language][], [GitHub][], [Ray Wenderlich][], and [Coursera][] style guides. It supports cross-platform usage and can be run on Mac OS X via your shell or integrated with Xcode, as well as on Linux and Windows. [The Swift Programming Language]: https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/ [GitHub]: https://github.com/github/swift-style-guide [Ray Wenderlich]: https://github.com/raywenderlich/swift-style-guide [Coursera]: https://github.com/coursera/swift-style-guide Tailor parses Swift source code using the primary Java target of [ANTLR](http://www.antlr.org): > ANTLR is a powerful parser generator [ . . . ] widely used in academia and industry to build all sorts of languages, tools, and frameworks. — [About the ANTLR Parser Generator](http://www.antlr.org/about.html) # Getting Started ## Installation Requires Java (JRE or JDK) Version 8 or above: [Java SE Downloads](http://www.oracle.com/technetwork/java/javase/downloads/index.html) ### [Homebrew](http://brew.sh), [Linuxbrew](http://linuxbrew.sh) ```bash brew install tailor ``` ### Mac OS X (10.10+), Linux ```bash curl -fsSL https://tailor.sh/install.sh | sh ``` ### Windows (10+) ```powershell iex (new-object net.webclient).downloadstring('https://tailor.sh/install.ps1') ``` ### Manually You may also download Tailor via [GitHub Releases](https://github.com/sleekbyte/tailor/releases), extract the archive, and symlink the `tailor/bin/tailor` shell script to a location in your `$PATH`. ### Continuous Integration If your continuous integration server supports [Homebrew](http://brew.sh) installation, you may use the following snippet: ```yaml before_install: - brew update - brew install tailor ``` In other cases, use this snippet: Replace `${TAILOR_RELEASE_ARCHIVE}` with the URL of the release you would like to install, e.g. `https://github.com/sleekbyte/tailor/releases/download/v0.1.0/tailor.tar`. ```yaml before_script: - wget ${TAILOR_RELEASE_ARCHIVE} -O /tmp/tailor.tar - tar -xvf /tmp/tailor.tar - export PATH=$PATH:$PWD/tailor/bin/ ``` ## Usage Run Tailor with a list of files and directories to analyze, or via Xcode. ```bash $ tailor [options] [--] [[file|directory] ...] ``` Help for Tailor is accessible via the `[-h|--help]` option. ``` … ``` # Features * [Enabling and Disabling Rules](#enabling-and-disabling-rules) * [Cross-Platform](#cross-platform) * [Automatic Xcode Integration](#automatic-xcode-integration) * [Colorized Output](#colorized-output) * [Warnings, Errors, and Failing the Build](#warnings-errors-and-failing-the-build) * [Disable Violations within Source Code](#disable-violations-within-source-code) * [Configuration](#configuration) * [Formatters](#formatters) ## Enabling and Disabling Rules Rule identifiers and "preferred/not preferred" code samples may be found on the [Rules](https://github.com/sleekbyte/tailor/wiki/Rules) page. Rules may be individually disabled (blacklist) or enabled (whitelist) via the `--except` and `--only` command-line flags. ### Except ```bash tailor --except=brace-style,trailing-whitespace main.swift ``` ### Only ```bash tailor --only=redundant-parentheses,terminating-semicolon main.swift ``` ## Cross-Platform Tailor may be used on Mac OS X via your shell or integrated with Xcode, as well as on Linux and Windows. ### Linux ### Windows ## Automatic Xcode Integration Tailor can be integrated with Xcode projects using the `--xcode` option. ```bash tailor --xcode /path/to/demo.xcodeproj/ ``` This adds the following Build Phase Run Script to your project's default target. Tailor's output will be displayed inline within the Xcode Editor Area and as a list in the Log Navigator. ### Configure Xcode to Analyze Code Natively (⇧⌘B) 1. Add a new configuration, say `Analyze`, to the project 2. Modify the active scheme's `Analyze` phase to use the new build configuration created above 3. Tweak the build phase run script to run Tailor **only** when analyzing the project (⇧⌘B) ```bash if [ "${CONFIGURATION}" = "Analyze" ]; then if hash tailor 2>/dev/null; then tailor else echo "warning: Please install Tailor from https://tailor.sh" fi fi ``` ## Colorized Output Tailor uses the following color schemes to format CLI output: * **Dark theme** (enabled by default) * **Light theme** (enabled via `--invert-color` option) * **No color theme** (enabled via `--no-color` option) ## Warnings, Errors, and Failing the Build `--max-severity` can be used to control the maximum severity of violation messages. It can be set to `error` or `warning` (by default, it is set to `warning`). Setting it to `error` allows you to distinguish between lower and higher priority messages. It also fails the build in Xcode, if any errors are reported (similar to how a compiler error fails the build in Xcode). With `max-severity` set to `warning`, all violation messages are warnings and the Xcode build will never fail. This setting also affects Tailor's exit code on the command-line, a failing build will `exit 1` whereas having warnings only will `exit 0`, allowing Tailor to be easily integrated into pre-commit hooks. ## Disable Violations within Source Code Violations on a specific line may be disabled with a **trailing** single-line comment. ```swift import Foundation; // tailor:disable ``` Additionally, violations in a given block of code can be disabled by **enclosing the block** within `tailor:off` and `tailor:on` comments. ```swift // tailor:off import Foundation; import UIKit; import CoreData; // tailor:on class Demo() { // Define public members here } ``` ### Note * `// tailor:off` and `// tailor:on` comments must be paired ## Configuration The behavior of Tailor can be customized via the `.tailor.yml` configuration file. It enables you to * include/exclude certain files and directories from analysis * enable and disable specific analysis rules * specify output format * specify CLI output color scheme You can tell Tailor which configuration file to use by specifying its file path via the `--config` CLI option. By default, Tailor will look for the configuration file in the directory where you will run Tailor from. The file follows the [YAML 1.1](http://www.yaml.org/spec/1.1/) format. ### Including/Excluding files Tailor checks all files found by a recursive search starting from the directories given as command line arguments. However, it only analyzes Swift files that end in `.swift`. If you would like Tailor to analyze specific files and directories, you will have to add entries for them under `include`. Files and directories can also be ignored through `exclude`. Here is an example that might be used for an iOS project: ```yaml include: - Source # Inspect all Swift files under "Source/" exclude: - '**Tests.swift' # Ignore Swift files that end in "Tests" - Source/Carthage # Ignore Swift files under "Source/Carthage/" - Source/Pods # Ignore Swift files under "Source/Pods/" ``` #### Notes * Files and directories are specified relative to where `tailor` is run from * Paths to directories or Swift files provided explicitly via CLI will cause the `include`/`exclude` rules specified in `.tailor.yml` to be ignored * *Exclude* is given higher precedence than *Include* * Tailor recognizes the [Java Glob](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob) syntax ### Enabling/Disabling rules Tailor allows you to individually disable (blacklist) or enable (whitelist) rules via the `except` and `only` labels. Here is an example showcasing how to enable certain rules: ```yaml # Tailor will solely check for violations to the following rules only: - upper-camel-case - trailing-closure - forced-type-cast - redundant-parentheses ``` Here is an example showcasing how to disable certain rules: ```yaml # Tailor will check for violations to all rules except for the following ones except: - parenthesis-whitespace - lower-camel-case ``` #### Notes * *only* is given precedence over *except* * Rules that are explicitly included/excluded via CLI will cause the `only`/`except` rules specified in `.tailor.yml` to be ignored ### Specifying output format Tailor allows you to specify the output format (`xcode`/`json`) via the `format` label. Here is an example showcasing how to specify the output format: ```yaml # The output format will now be in JSON format: json ``` #### Note * The output format explicitly specified via CLI will cause the output format defined in `.tailor.yml` to be ignored ### Specifying CLI output color scheme Tailor allows you to specify the CLI output color schemes via the `color` label. To disable colored output, set `color` to `disable`. To invert the color scheme, set `color` to `invert`. Here is an example showcasing how to specify the CLI output color scheme: ```yaml # The CLI output will not be colored color: disable ``` #### Note * The CLI output color scheme explicitly specified via CLI will cause the output color scheme defined in `.tailor.yml` to be ignored ## Formatters Tailor's output format may be customized via the `-f`/`--format` option. The Xcode formatter is selected by default. ### Xcode Formatter (default) The default `xcode` formatter outputs violation messages according to the format expected by Xcode to be displayed inline within the Xcode Editor Area and as a list in the Log Navigator. This format is also as human-friendly as possible on the console. ``` … ``` ### [JSON](http://www.json.org) Formatter The `json` formatter outputs an array of violation messages for each file, and a `summary` object indicating the parsing results and the violation counts. ``` $ tailor -f json main.swift { "files": [ { "path": "/main.swift", "violations": [ { "severity": "warning", "rule": "constant-naming", "location": { "line": 1, "column": 5 }, "message": "Global Constant should be either lowerCamelCase or UpperCamelCase" } ], "parsed": true } ], "summary": { "violations": 1, "warnings": 1, "analyzed": 1, "errors": 0, "skipped": 0 } } ``` ### HTML Formatter The `html` formatter outputs a complete HTML document that should be written to a file. ``` tailor -f html main.swift > tailor.html ``` # Developers Please review the [guidelines for contributing](https://github.com/sleekbyte/tailor/blob/master/.github/CONTRIBUTING.md) to this repository. ## Development Environment * [Java Version 8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) * [Gradle](https://gradle.org) (optional, `./gradlew` may be used instead) * [Ruby 2.0.0+](https://www.ruby-lang.org/en/) * [Bundler](http://bundler.io)