v1.5.1 — Accurate JSON report version, test suite hardening, and documentation review

[ericodx]

A patch release. The JSON report now carries the real tool version, the CLI integration tests are deterministic again, and every document was checked against the code and corrected.

---

What's new

Bug fix

• JSON report version reflects the tool version (JSON report hardcodes version as 1.0.0 instead of the tool version #42, fix: report the tool version in the JSON report #43, fix(tests): expect Version.current in the end-to-end JSON test #47): The top-level version field was hardcoded as "1.0.0" in every release. It is now the same string swift-cpd --version prints.

  "version": "swift-cpd 1.5.1 [arm64-macos15]"

  Note: The value changes format, from a bare semver (1.0.0) to swift-cpd <version> [<arch>-<os>]. Update any consumer that parsed this field as a plain version number.

Test suite hardening

• The swift-cpd executable is found reliably (fix(tests): resolve swift-cpd binary path independently of build architecture #37, fix(tests): resolve swift-cpd from the package root instead of Bundle.allBundles #40): CLI tests resolve the binary from the package root via #filePath, using an architecture-independent .build/debug path instead of Bundle.allBundles. A missing binary now fails with a clear MissingExecutableError.
• No more hangs or flaky results (fix(tests): make ignore-structural integration test deterministic and harden runSwiftCPD #38):
  • Child process output goes to files, which avoids pipe buffer deadlocks.
  • runSwiftCPD fails after a deadline (ProcessTimeoutError) instead of hanging the suite.
  • The ignore-structural integration test checks clone types instead of JSON byte length.

Documentation

• Full documentation review (docs: review all documentation against the current code #45): every document was checked against the source and tests, and the sample outputs come from real runs. Corrections:
  • README: the configuration example used an inline list (enabledCloneTypes: [1, 2, 3, 4]), which the YAML parser rejects. It now uses a block list.
  • Inline suppression: a trailing // swiftcpd:ignore comment has no effect. The tag must start its own comment line, and it suppresses the next non-blank line, or the whole {…} block when that line opens one.
  • Defaults: ignoreSameFile and ignoreStructural default to false. Only the swift-cpd init template sets them to true.
  • Baseline matching is exact: type, token count, line count, and each fragment's file and line range. Edits that shift line numbers count as new clones.
  • Output examples for text, JSON and xcode match the current reporters.
  • SonarQube: removed a sonar.swift.cpd.reportPaths property and a baseline: YAML key that were documented but do not exist.
  • Xcode plugin guide:
    • Output goes to stdout.
    • The Xcode entry point analyzes the whole project directory.
    • The cache lives in the plugin work directory.
    • .swift-cpd.yml is read from the build's working directory.
  • Requirements: Xcode 26, needed for Swift 6.2.
  • Architecture and CodeBase references: corrected for the per-file pipeline order, the tokenizers, the Type 3 and Type 4 algorithms and weights, glob semantics, and git-ref IO.
• New content:
  • the init template, the supported YAML syntax, the exceptions to config precedence, and a cache section in Docs/USAGE.md
  • make targets in Docs/BUILDING.md
  • development setup and commit rules in CONTRIBUTING.md
  • reference entries for ArgumentParsingError, ConfigurationError, the YAML loader and parser, CTokenizerScanner, CLanguageVocabulary, CompiledPattern and FileTokens

Chore

• Package.resolved is now tracked, and .gitignore entries were updated.

---

Requirements

• macOS 15+
• Swift 6.2+ (Xcode 26+)
• git on PATH when using --source-ref

---

Installation

See the Installation Guide for Homebrew, pre-built binary, SPM plugin, and pre-commit hook setup.

---

Quality bar

• 947 tests in 92 suites
• 100% line coverage

---

What's Changed

• fix(tests): resolve swift-cpd binary path independently of build architecture by @ericodx in fix(tests): resolve swift-cpd binary path independently of build architecture #37
• fix(tests): make ignore-structural integration test deterministic and harden runSwiftCPD by @ericodx in fix(tests): make ignore-structural integration test deterministic and harden runSwiftCPD #38
• fix(tests): resolve swift-cpd from the package root instead of Bundle.allBundles by @ericodx in fix(tests): resolve swift-cpd from the package root instead of Bundle.allBundles #40
• fix: report the tool version in the JSON report by @ericodx in fix: report the tool version in the JSON report #43
• docs: review all documentation against the current code by @ericodx in docs: review all documentation against the current code #45

Full Changelog: v1.5.0...v1.5.1

---

This discussion was created from the release v1.5.1 — Accurate JSON report version, test suite hardening, and documentation review.