Sitrep: a source code analyzer that gives a Swift project a census

A census of the project rather than a critique of it

Sitrep answers questions about the shape of a Swift project. The documented output includes a count of classes, structs, enums, protocols and extensions, the total lines of code alongside source lines of code with comments and whitespace removed, which file and which type are the longest together with their source line counts, which imports the project uses and how often, and how many UIViews, UIViewControllers and SwiftUI views exist. Read that list carefully, because it defines the ceiling of the tool. Sitrep measures. It does not judge, flag or fix. The project describes itself as a source code analyzer for Swift projects giving a high-level overview, and the contributions it invites are about turning more collected data into reported data rather than about adding rules.

Three installation routes, all ending in a sitrep command

The command line tool can be installed in three ways. Homebrew is the shortest, and gives you the `sitrep` command directly.

brew install twostraws/brew/sitrep

Mint is the second option, and works from the repository's main branch.

mint install twostraws/Sitrep@main
mint run sitrep@main

The third is to build it yourself from a clone, which also ends with a `sitrep` command available on the command line.

git clone https://github.com/twostraws/Sitrep
cd Sitrep
make install

There is also a plain Swift Package Manager route for people who just want to build and run it in place rather than install it, using `swift build` and then `swift run sitrep` with a path to the project you want scanned. The executable is left in the `.debug` directory after the build if you want to keep a copy of it.

Flags decide the path, the format and the dry run

With no flags at all, Sitrep scans the current directory and prints its findings as text. The flags adjust that. `-p` sets the path to scan and defaults to the current working directory, `-f` sets the output format, with `-f json` for JSON and text as the equivalent of the default, `-c` points at a configuration file if you have one, `-i` prints the settings Sitrep would use if a real scan were requested and then exits, and `-h` prints the help. The `-i` flag is the one worth remembering, because it is a dry run of the configuration and the path resolution without the cost of a full parse. When a scan is not picking up the files you expected, running with `-i` first is faster than guessing.

The .sitrep.yml file can only exclude directories

Configuration for a path lives in a `.sitrep.yml` file in the directory you want scanned, and the documentation is upfront that this is currently limited to one thing, an array of directory names to exclude from the scan.

excluded:
  - .build
  - Tests

You can point the tool at a configuration file elsewhere with the `-c` parameter, which is how you would apply one file to several projects, for example `sitrep -c /path/to/.sitrep.yml -p /path/to/swift/project`. The `-i` parameter prints the configuration options that would be used in a real run and then exits, which is the fastest way to confirm that your exclusions were picked up. There is no configuration for thresholds, rules or reporting in this file, so anyone expecting a linting configuration here will not find one.

SitrepCore is the reusable half of the project

The architecture is a library that does the scanning and reporting work, plus a small front end that handles reading and writing on the command line. That library is called SitrepCore, and you can use it from your own Swift code by adding the package as a dependency.

let package = Package(
    //...
    dependencies: [
        .package(url: "https://github.com/twostraws/Sitrep", .branch("main"))
    ],
    //...
)

Then you import SitrepCore wherever you want to use it. The practical value is for a tool that needs the same numbers for its own reasons, such as a dashboard or a build report, without shelling out to the executable and parsing its text output. The caveat is visible in the snippet above, because the dependency is pinned to the main branch rather than to a version, so a library consumer tracks the head of the repository.

SwiftSyntax does the parsing, and the version has to match

Sitrep is built on Apple's SwiftSyntax, and the documentation explains why that matters: it parses Swift code accurately and efficiently. The note attached to it is a warning rather than a nicety. You must make sure the SwiftSyntax version specified in Package.swift matches your current Swift tools version, and a mismatch here produces parse behaviour you will spend an afternoon blaming on the analyzer. The project itself is written in Swift 5.8, and the repository carries a Package.swift, a Package.resolved, a makefile, a Sources directory, a Tests directory, a Working directory and a swiftlint configuration. The licence is Apache 2.0 with the Runtime Library Exception, and the credits name Paul Hudson as designer and author with copyright dated 2023.

Data is already collected for metrics it does not print yet

The most interesting admission in the documentation is what the tool gathers but does not report. Behind the scenes it captures a good deal more: how many functions there are, how many comments of both the regular and documentation kinds, how large the enums are, and more. None of that is currently reported, and the project says it could be in a future release. The contribution list makes the same point from the other direction, suggesting that more tracked data be turned into reported data, that cyclomatic complexity be calculated from what is already parsed, and that non-Swift data such as storyboard scenes, outlets and assets in asset catalogs be read as well. The repository is not archived and the last push was on 2026-09-11, but it has no tagged GitHub releases, so a library consumer tracking the main branch has no version marker to pin against.

Editorial conclusion

Reach for Sitrep when you want a fast, factual picture of the shape of a Swift codebase, for example when sizing a migration or arguing about how much of an app is UIViewController code, and it will not tell you anything about whether that code is good. It does not fit a project that needs style enforcement, since it reports counts rather than violations and its configuration can only exclude directories. Before relying on it, check that the SwiftSyntax version in Package.swift matches your tools version, then run it with `-i` to see the configuration it would use on your path.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. twostraws/Sitrep on GitHub