DOCSEARCHbyAlgolia
Submit Docs

xcsift

repository·master·Indexed 19 days ago

https://github.com/ldomaradzki/xcsift

A Swift command-line tool that transforms verbose Xcode and Swift Package Manager (SPM) build and test output into structured, machine-readable formats including JSON, TOON, and GitHub Actions annotations. It is optimized for coding agents and LLMs to improve token efficiency and error parsing, featuring a specialized TOON format that reduces token usage by 30-60%. The tool extracts compile errors, warnings, test failures, code coverage, and build timing.

Tokens
10.4K
Snippets
47
Records
60
Agent score
62%

What's inside xcsift

  1. Overview of xcsift output formats

    master

    xcsift supports three output formats tailored for different integration needs:

    • JSON: The default format. Provides a standard, structured schema for maximum compatibility with programmatic tools and JSON parsers.
    • TOON (Token-Oriented Object Notation): A compact, indentation-based format designed for LLMs and AI tools. It provides 30-60% fewer tokens compared to JSON, making it ideal for reducing API costs and context window usage.
    • GitHub Actions: Automatically appends workflow annotations (e.g., ::error, ::warning) when running in a GitHub Actions environment (GITHUB_ACTIONS=true), allowing build issues to appear directly in PR comments and the GitHub UI.
    Use Case | Recommended Format
----------|-------------------
LLM/AI tools | TOON (`-f toon`)
JSON tooling | JSON (default)
GitHub CI | Auto-detected
Debugging | JSON with `--warnings`
API cost optimization | TOON

  3. Interpreting TOON output format

    master

    The TOON format uses an indentation-based structure with tabular arrays. This format is designed to be highly token-efficient for LLMs.

    Key Fields:

    • status: Either succeeded or failed.
    • errors[N]{columns}:: A tabular array of errors with specified columns.
    • warnings[N]{columns}:: A tabular array of warnings. The type column can be compile, runtime, or swiftui.
    • failed_tests[N]{columns}:: A tabular array of test failures including file/line and duration.
    • null values indicate that specific data was unavailable during parsing (e.g., build_time: null).
    status: failed
summary:
  errors: 1
  warnings: 3
  failed_tests: 2
  passed_tests: 10
  build_time: 12.4s
  test_time: 5.2s
errors[1]{file,line,message}:
  main.swift,15,"use of undeclared identifier 'foo'"
warnings[3]{file,line,message,type}:
  Parser.swift,20,"unused variable 'result'",compile
  View.swift,42,"Publishing changes from background threads",swiftui
  Util.swift,10,"Custom warning message",runtime
failed_tests[2]{suite,test,file,line,message,duration}:
  MyTests,testExample,MyTests.swift,25,"XCTAssertEqual failed",0.123
  MyTests,testOther,MyTests.swift,30,"XCTAssertTrue failed",0.456

  4. Understand priority rules and boolean flag behavior

    master

    Priority

    CLI flags always take precedence over configuration file values.

    Boolean Flags (OR Semantics)

    Boolean flags (e.g., --warnings, --quiet, --coverage) use OR semantics. This means:

    • If a CLI flag is passed $\rightarrow$ it is enabled.
    • If the config value is true $\rightarrow$ it is enabled.
    • A flag is only disabled if the CLI flag is absent AND the config value is false (or unset).

    Note: You cannot disable a boolean flag via the CLI if it is enabled in the config file. To disable it, you must edit or remove the value from the configuration file.

    Example

    If .xcsift.toml contains:

    format = "toon"
warnings = true
    • xcsift $\rightarrow$ format=toon, warnings=true (from config)
    • xcsift -f json $\rightarrow$ format=json, warnings=true (CLI overrides format, but warnings remains true from config)

  5. Understand the TOON output format

    master

    TOON is an indentation-based, tabular structure designed for high density and low token usage. It provides a summary of the build status and detailed arrays for errors, warnings, and failed tests.

    Key Fields:

    • status: succeeded or failed.
    • errors[N]{columns}: A tabular array where N is the count and {columns} defines the schema (e.g., file,line,message).
    • warnings[N]{columns}: Includes a type field which can be compile, runtime, or swiftui.
    • failed_tests[N]{columns}: Includes suite, test, file, line, message, and duration.
    • null: Indicates data was unavailable.
    status: failed
summary:
  errors: 1
  warnings: 3
  failed_tests: 2
  passed_tests: 10
  build_time: 12.4s
  test_time: 5.2s
errors[1]{file,line,message}:
  main.swift,15,"use of undeclared identifier 'foo'"
warnings[3]{file,line,message,type}:
  Parser.swift,20,"unused variable 'result'",compile
  View.swift,42,"Publishing changes from background threads",swiftui
  Util.swift,10,"Custom warning message",runtime
failed_tests[2]{suite,test,file,line,message,duration}:
  MyTests,testExample,MyTests.swift,25,"XCTAssertEqual failed",0.123
  MyTests,testOther,MyTests.swift,30,"XCTAssertTrue failed",0.456

  6. Understand JSON status values and the 'incomplete' state

    master

    The status field in JSON output can be one of three values:

    • success: The build/test run completed with no errors, no failed tests, and produced positive evidence of completion (e.g., a terminal ** BUILD SUCCEEDED ** marker or passed tests).
    • failed: Errors, failed tests, linker errors, or a terminal ** … FAILED ** marker were detected.
    • incomplete: The stream ended without a terminal marker and without recognizable results. This typically indicates a truncated or killed build (e.g., Killed: 9 due to memory pressure).

    Important for automation: Do not check only for status == "failed". A truncated run will report incomplete, which is also a non-success state. To ensure pipelines fail on truncated runs, use the --exit-on-failure flag.

  8. Use xcsift to format Swift and Xcode build output

    master

    xcsift is a formatter that parses xcodebuild and swift output into a token-efficient TOON format optimized for LLM consumption. It extracts compile errors, warnings, test failures, code coverage, and build timing.

    Crucial Requirement: You must always redirect stderr to stdout using 2>&1 because compiler errors and warnings are sent to stderr. Without this, xcsift will not receive the data it needs to parse.

    xcodebuild build 2>&1 | xcsift -f toon

  9. Process build and test output with xcsift

    master

    To use xcsift, pipe the output of xcodebuild or swift build into the command.

    Important: You must use 2>&1 to redirect stderr to stdout, as build tools typically output logs to stderr.

    Basic Build Output

    xcodebuild build 2>&1 | xcsift
# or
swift build 2>&1 | xcsift

    Test Output with Coverage

    To parse test results along with code coverage data, use the --coverage flag:

    # SPM with coverage
swift test --enable-code-coverage 2>&1 | xcsift --coverage

# xcodebuild with coverage
xcodebuild test -enableCodeCoverage YES 2>&1 | xcsift --coverage

    TOON Format for LLMs

    To reduce token usage by 30-60% when passing output to LLMs, use the --format toon flag:

    xcodebuild build 2>&1 | xcsift --format toon
    xcodebuild build 2>&1 | xcsift

  11. Install the Codex skill

    master

    Install the xcsift skill for Codex to provide command documentation and usage examples directly within the Codex interface.

    Requirements:

    • The Codex skills directory must be accessible.

    Installation: Run the following command to create a global skill file at ~/.codex/skills/xcsift/SKILL.md:

    xcsift install-codex

    Verification:

    1. Check the directory: ls -la ~/.codex/skills/xcsift/
    2. Use the skill in Codex by typing: /xcsift

    Troubleshooting: If you encounter a "Failed to create skill directory" error, manually create the directory:

    mkdir -p ~/.codex/skills/

  12. Install xcsift

    master

    You can install xcsift using Homebrew, mise, Mint, or by building from source.

    Homebrew (Recommended)

    brew install xcsift

    mise

    To install globally via the mise registry:

    mise use -g xcsift

    Or via the GitHub backend:

    mise use -g github:ldomaradzki/xcsift

    To install for a specific project (adds to .mise.toml):

    mise use xcsift

    Mint

    mint install ldomaradzki/xcsift

    Build from Source

    git clone https://github.com/ldomaradzki/xcsift.git
cd xcsift
swift build -c release
cp .build/release/xcsift /usr/local/bin/