thumbtack/star

Generate reports on how frequently specified Swift types are being used in your iOS codebase

Swift Type Adoption Reporter (STAR)

Generate reports on how frequently specified Swift types are being used in your iOS codebase with a simple command-line interface.

Install

$ cd star
$ make install

Usage

$ star --types Avatar Button Color Pill --files ./

Avatar used 27 times.
Button used 167 times.
Color used 2711 times.
Pill used 9 times.

To report on types which are in a separate module, specify a --moduleName. This will ensure that references like Thumbprint.Button() are captured too.

$ star --types Avatar Button Color Pill --files ./ --module Thumbprint

Avatar used 30 times.
Button used 182 times.
Color used 2786 times.
Pill used 11 times.

Options

USAGE: star [--types <types> ...] [--module <module>] [--format <format>] [--files <files> ...] [--includeTypeInheritance] [--verbose]

OPTIONS:
  -t, --types <types>     List of types on which to report
  -m, --module <module>   Name of module containing types, to ensure types referenced by <module name>.<type name> are counted
  -f, --format <format>   Output format (humanReadable|json) (default: humanReadable)
  --files <files>         Paths in which to look for Swift source
  --includeTypeInheritance
                          Include subclass and protocol conformance declarations in usage counts
  -v, --verbose           Print additional information about source as it is parsed
  -h, --help              Show help information.

How it Works

STAR uses SwiftSyntax to traverse the AST and find references to the specified identifiers. Since STAR operates on the untyped AST, usage reports may contain imperfect information when linking a reference to its identifier would require full type checking.

The reporter attempts to provide as useful information as possible, so some types of references are intentionally filtered out. For example, the line of code

let foo: UIView = UIView()

technically includes two nodes in the AST for the UIView identifier: one in the type annotation, and one in the constructor call. For most business uses, though, it is preferable to only count this line as a single use of UIView. Therefore, type annotations are ignored by STAR.

Some other examples of intentionally ignored references are code comments, class/struct/extension/etc. declarations, and inner classes within components (e.g., MyComponent.SomeInnerClass will match neither MyComponent, nor SomeInnerClass).

Uninstall

$ cd star
$ make uninstall

Importing into another Swift package

In addition to the command-line executable star, STAR's core functionality is also available through Swift Package Manager as the static library STARLib. To use STARLib in your Swift package, add the following to your Package.swift:

let package = Package(
    ...
    dependencies: [
        ...
        .package(name: "SwiftTypeAdoptionReporter", url: "https://github.com/thumbtack/star.git", <version (e.g., `.upToNextMinor(from: "3.0.0")`)>),
    ],
    targets: [
        .target(
            ...
            dependencies: [
                ...
                .product(name: "STARLib", package: "SwiftTypeAdoptionReporter"),
            ]
        ),
    ]
)

Contributing

If you have ideas to make STAR more useful, open an issue or submit a pull request! See below for instructions on building/testing locally.

$ git clone [email protected]/thumbtack/star.git
$ cd star
$ open -a Xcode .

To build & run locally:

$ swift run star ...

Passing in the --verbose argument will print out additional information which can be useful for debugging.

To run test suite:

From command line:

$ swift test

With Xcode:

1. Create Xcode project:

   $ swift package generate-xcodeproj
   

2. Open SwiftTypeAdoptionReporter.xcodeproj

3. In Xcode, Product -> Test

star's Issues

Add option to output JSON

When using these metrics as input to a longer process, it would be useful to return the data in a standard, parseable format.

Run tests on PRs & master

Set up some sort of CI to run swift test on PRs and when new commits are merged into master, to ensure breaking changes are found.

Update JSON format schema

When --format json argument is passed in, update the output JSON to match the following format:

[
    {
        name: "Button",
        fileCount: 87,
        usageCount: 166,
    },
    {
        name: "Label",
        fileCount: 112,
        usageCount: 209,
    },
]

where name is the type name (with module name, if any, omitted), fileCount is the number of files using that type, and usageCount is the total number of usages of that type (should always be greater than or equal to fileCount).