Sync workflows + lint configs from MistKit; fix all warnings

[leogdion]

Summary

• Sync .swift-format, .swiftlint.yml, Scripts/lint.sh, mise.toml, and GitHub workflows with MistKit's current state. Adds .github/actions/setup-tools/action.yml, check-unsafe-flags.yml, and swift-source-compat.yml; refactors SyntaxKit.yml matrix and codeql.yml Swift-on-macOS gating.
• Adopt stricter swift-format rules (NeverForceUnwrap, NeverUseForceTry, NeverUseImplicitlyUnwrappedOptionals, UseLetInEveryBoundCaseVariable, ValidateDocumentationComments) and SwiftLint additions (discouraged_optional_boolean, one_declaration_per_file, no_unchecked_sendable custom rule, type_name length config).
• Fix every warning surfaced after the rule tightening: missing doc comments, deprecated SwiftSyntax inits (TupleExprElementListSyntax/ForInStmtSyntax/RepeatWhileStmtSyntax/MemberAccessExprSyntax(name:)/DictionaryElementSyntax(keyExpression:)/FunctionEffectSpecifiersSyntax(throwsSpecifier:)/etc.), unused-public-import demotions, periphery dead-code annotations, #warning TODOs converted to plain comments, deprecated SyntaxKit test API migrations (PlusAssign → Infix("+="), Parameter(isUnnamed:) → Parameter(unlabeled:), Infix(_:_:) builder closure → Infix(_:lhs:rhs:)), and removal of unnecessary try cascades.
• Closes Optimize CI: concurrency, path filtering, dynamic matrix, and Windows gating #126, Update Github Workflow for New Filtered Approach #127, Workflow Updates for May 2026 #128, Fix CI so Cancelled Does Look like Failure #136, Switch from Mint to Mise #138, Update Copyright Year to 2026 #143, Update Docker Images #144 (work already merged via prior PRs into v0.0.5; this PR closes the tracking issues).

Test plan

• swift build --build-tests — 0 warnings, 0 errors
• swift test — 397 tests / 74 suites pass
• swift-format lint — clean
• swiftlint lint — clean
• periphery scan — clean
• CI: confirm the new check-unsafe-flags and swift-source-compat workflows pass
• CI: confirm lint job uses the cached setup-tools action (cache hit on rerun)
• CI: confirm full matrix fires (Windows, full macOS, Android API 33–36) on PR to v0.0.5

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 391a00c6-0146-4654-8c6b-bc0bab727822

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 128-workflow-updates-may-2026

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 77.63158% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.04%. Comparing base (475ae7c) to head (8456e3a).

Files with missing lines	Patch %	Lines
...es/SyntaxKit/CodeBlocks/CodeBlock+ExprSyntax.swift	0.00%	3 Missing ⚠️
...taxKit/Collections/CodeBlock+DictionaryValue.swift	0.00%	3 Missing ⚠️
Sources/SyntaxKit/Utilities/Group.swift	0.00%	3 Missing ⚠️
...rces/SyntaxKit/CodeBlocks/CommentedCodeBlock.swift	0.00%	2 Missing ⚠️
...es/SyntaxKit/Expressions/OptionalChainingExp.swift	0.00%	2 Missing ⚠️
Sources/SyntaxKit/ControlFlow/If+ElseBody.swift	0.00%	1 Missing ⚠️
Sources/SyntaxKit/ControlFlow/While.swift	0.00%	1 Missing ⚠️
Sources/SyntaxKit/Expressions/Infix.swift	0.00%	1 Missing ⚠️
Sources/SyntaxKit/Expressions/Return.swift	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           v0.0.5     #159      +/-   ##
==========================================
- Coverage   78.15%   78.04%   -0.12%     
==========================================
  Files         126      127       +1     
  Lines        4555     4491      -64     
==========================================
- Hits         3560     3505      -55     
+ Misses        995      986       -9     

Flag	Coverage Δ
spm	77.77% <73.68%> (-0.10%)	⬇️
swift-6.0	77.80% <73.68%> (-0.10%)	⬇️
swift-6.1	77.97% <77.63%> (+0.08%)	⬆️
swift-6.2	77.97% <77.63%> (-0.09%)	⬇️
swift-6.3	77.80% <73.68%> (-0.10%)	⬇️
ubuntu	78.04% <77.63%> (-0.09%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[claude]

Code Review: PR #159 — Sync workflows + lint configs from MistKit; fix all warnings

Summary

This PR syncs CI infrastructure and lint configuration from the MistKit companion project and eliminates all build-time warnings surfaced by now-stricter lint rules. Changes fall into five categories: new GitHub Actions workflows (check-unsafe-flags.yml, swift-source-compat.yml), a refactored CI matrix with a composite setup-tools action, stricter swift-format/SwiftLint rules, deprecated SwiftSyntax API fixes, and warning cleanup.

---

Code Quality and Best Practices ✅

Positive:

• The composite setup-tools action is well-designed. The description explains the cache-scope motivation, and the two-branch logic (install vs. configure-PATH) is clean and correct.
• Splitting the monolithic set-matrix step into check and matrix steps improves readability and makes semver-branch logic auditable.
• periphery:ignore comments all include a rationale clause (e.g. "retained for source compatibility"), which is better practice than bare suppression.
• #warning(...) → // TODO: conversions are correct: they preserve intent without emitting compiler warnings on every build.
• swiftlint:disable one_declaration_per_file brackets in ValidationError.swift are correctly scoped to the minimum range.

Issues:

• public import SwiftSyntax inconsistency. The PR converts two files (CodeBlock+Generate.swift, EmptyCodeBlock.swift) from public import to import. However, ~20 other files in Sources/SyntaxKit/ still use public import SwiftSyntax. This should be addressed consistently — either all files re-export SwiftSyntax publicly, or none do.

• lint.sh unquoted pushd. Line 43 reads pushd $PACKAGE_DIR (unquoted). If the path contains spaces this breaks. The adjacent cd invocation uses the quoted form. Fix: pushd "$PACKAGE_DIR".

• SWIFTFORMAT_OPTIONS duplicate flag. In STRICT mode the lint step passes --configuration .swift-format both via $SWIFTFORMAT_OPTIONS and explicitly in the command. Harmless but untidy.

---

Potential Bugs 🐛

• swift:latest in check-unsafe-flags.yml (line 14). Using swift:latest rather than a pinned version means the check silently drifts as new Swift releases ship — a future release could change the swift package dump-package JSON schema and break the jq query. Pin to a specific version (e.g. swift:6.3).

• swift-source-compat.yml PR trigger is too broad. The workflow triggers on all pull_request events with no branches: filter, meaning it fires on feature-to-feature PRs as well. Add branches: [main] to the pull_request trigger, consistent with other workflows in this repo.

• check-unsafe-flags.yml runs swift package dump-package twice. On the failure path, the dump is run again to print a sample — doubling the network/resolution cost and risking a different result on a flaky network. Cache the dump output in a shell variable:

  dump_output=$(swift package dump-package)
  unsafe_flags=$(echo "$dump_output" | jq ...)
  # on failure:
  echo "$dump_output" | head -200

• pattern_matching_keywords double-listed. This rule appears to have been removed from opt_in_rules but retained in disabled_rules. The disabled_rules entry is now redundant and should also be removed.

---

Performance Considerations ⚡

• swift build --build-tests added to lint.sh. This runs on every full lint invocation. Since lint runs after all build jobs in the workflow DAG, this re-compiles the package a second time. Consider removing it from lint.sh — it's already covered upstream.

• swift-source-compat.yml builds with --verbose. Verbose build output can produce very large CI logs and slow streaming. Remove --verbose or make it conditional on a debug flag.

---

Security Considerations 🔒

• swift:latest container (same as the bug note above) has supply-chain pinning concerns. Prefer swift:6.3 or a digest-pinned image.
• jdx/mise-action@v4 not SHA-pinned in setup-tools/action.yml. For actions used across all lint jobs, SHA pinning (e.g. jdx/mise-action@abc1234) provides stronger supply-chain guarantees.
• no_unchecked_sendable custom SwiftLint rule at error severity is a good addition — it correctly prevents suppression of Swift 6's concurrency checker.

---

Test Coverage

No new unit tests are needed for this infrastructure PR. The new workflows themselves serve as CI-level tests. The deprecated-API fixes are validated by the existing 397-test suite continuing to pass.

---

Actionable Suggestions

Priority	Location	Suggestion
High	check-unsafe-flags.yml:14	Pin swift:latest to swift:6.3 (or current stable)
High	swift-source-compat.yml:6-7	Add branches: [main] to the pull_request trigger
High	lint.sh:43	Quote pushd "$PACKAGE_DIR"
Medium	lint.sh:54	Remove swift build --build-tests — redundant with upstream build jobs
Medium	check-unsafe-flags.yml:28-35	Cache dump-package output in a variable to avoid double-run
Medium	.swiftlint.yml	Remove pattern_matching_keywords from disabled_rules (no longer in opt_in_rules)
Low	Sources/SyntaxKit/**/*.swift	Align public import SwiftSyntax usage consistently across all files
Low	lint.sh	Remove duplicate --configuration .swift-format flag in STRICT mode
Low	setup-tools/action.yml	SHA-pin jdx/mise-action@v4
Low	swift-source-compat.yml:30	Remove --verbose from swift build

Overall: Solid infrastructure and warning-cleanup PR. The SwiftSyntax API migration fixes are correct and necessary. The main items to address before merge are pinning swift:latest, tightening the swift-source-compat.yml PR trigger, and evaluating whether swift build --build-tests belongs in lint.sh.

🤖 Generated with Claude Code

[leogdion]

explain this change

[leogdion]

Two things bundled in this hunk:

1. MemberAccessExprSyntax(base:dot:name:) is deprecated in current SwiftSyntax; replaced by MemberAccessExprSyntax(base:period:declName: DeclReferenceExprSyntax(...)). That clears a deprecation warning the stricter build surfaced.
2. patternWithTuple and tuplePattern were dead code — assigned but never read. The catch pattern is actually built right below via patternSyntaxExpr + FunctionCallExprSyntax + nested LabeledExprSyntax (lines ~58–88 in the new file). The compiler was emitting "Initialization of immutable value … was never used" for both. Removing them eliminates two warnings; the produced syntax is unchanged.

[leogdion]

explain this change

[leogdion]

Three cleanups in this hunk:

1. FunctionEffectSpecifiersSyntax(asyncSpecifier:throwsSpecifier:) is deprecated; switched every branch to the throwsClause: variant.
2. Once both sides go through throwsClause, the if errorType != nil split inside each case is redundant. Widened buildThrowsClause(throwsSpecifier:errorType:) to accept String? and pushed the with/without typed-throws-parens logic into the helper (lines 63–77 of the new file). Each case arm now collapses to one return FunctionEffectSpecifiersSyntax(...).
3. case let .throws(isRethrows, errorType) → case .throws(let isRethrows, let errorType) to satisfy swift-format's newly-enabled UseLetInEveryBoundCaseVariable rule. Same semantics, style only.

[claude]

Code Review: PR #159 — Sync workflows + lint configs; fix all warnings

Overview

This PR synchronizes CI workflows, lint configs, and SwiftSyntax API migrations from a sibling project (MistKit). It's a maintenance/housekeeping PR that fixes deprecation warnings across 40+ source files and tightens code quality tooling.

---

✅ What's working well

CI / Workflow improvements

• The composite setup-tools action (setup-tools/action.yml) solves a real cache-scope problem cleanly. The explanation in the YAML comment is exactly the right level of detail.
• The matrix-scope expansion logic is now cleaner: explicit checks for main, semver branches, and PR target branches are much easier to reason about than the old single conditional.
• The new concurrency: block on the lint job is a good production best practice — prevents tool-cache races during mise.toml bumps.
• check-unsafe-flags.yml is a solid guard; piping dump-package through jq is more robust than grep-based approaches.
• swift-source-compat.yml testing across Swift 6.0–6.3 is exactly right for a library that advertises broad compatibility.

SwiftSyntax API migrations
All deprecation fixes look mechanically correct:

• ForInStmtSyntax → ForStmtSyntax, WhereClauseSyntax.guardResult → .condition
• RepeatWhileStmtSyntax → RepeatStmtSyntax
• TupleExprElementListSyntax / TupleExprElementSyntax → LabeledExprListSyntax / LabeledExprSyntax
• DictionaryElementSyntax(keyExpression:valueExpression:) → (key:value:)
• IntegerLiteralExprSyntax(digits:) → (literal:)
• MemberAccessExprSyntax — using .period + declName: DeclReferenceExprSyntax(baseName:) instead of .dot + name: is the correct new API

Lint config tightening
Enabling NeverForceUnwrap, NeverUseForceTry, NeverUseImplicitlyUnwrappedOptionals, UseLetInEveryBoundCaseVariable, and ValidateDocumentationComments are all appropriate for a library codebase. The custom no_unchecked_sendable SwiftLint rule is a good Swift 6 safety net.

#warning → comments conversion
Converting compiler warnings to // TODO: comments is correct — they were blocking clean builds and the underlying design questions are still worth tracking.

public import SwiftSyntax → import SwiftSyntax
The incorrect access level on the re-export in CodeBlock+Generate.swift and EmptyCodeBlock.swift is properly fixed.

---

⚠️ Issues worth discussing

--strict removed from SwiftFormat in STRICT mode (Scripts/lint.sh)

- SWIFTFORMAT_OPTIONS="--strict --configuration .swift-format"
+ SWIFTFORMAT_OPTIONS="--configuration .swift-format"

Without --strict, swift-format lint exits 0 on formatting differences (only exits non-zero on hard errors). This weakens CI — it will stop failing on unformatted code. If this is intentional (prefer auto-format in CI over rejecting), the PR description should say so; otherwise this looks like an accidental regression.

ProcessError file extraction
ProcessError is moved from ValidationError.swift into its own ProcessError.swift. The cases are identical. No functional change, but the diff is slightly confusing to review because ValidationError.swift still exists and the types had shared file history. A comment in the PR noting this is a file-split-only refactor would help reviewers.

periphery:ignore on @available(*, unavailable) members
The approach works, but consider whether @available(*, unavailable) members should require Periphery suppression. If Periphery flags them as dead code, that's arguably a Periphery false-positive — a baseline suppression or config entry might be cleaner than per-site annotations.

---

🔍 Minor observations

• The run_command function cleanup in lint.sh correctly removes the dead if STRICT / else STRICT branch (both arms were identical).
• FunctionEffectSpecifiersSyntax simplification (replacing the if errorType branching with a unified buildThrowsClause(throwsSpecifier:errorType:String?) helper) is a nice reduction in cyclomatic complexity.
• DeclModifierListSyntax += simplification in Function+Syntax.swift is cleaner.

---

🧪 Test coverage

Test migrations (PlusAssign → Infix("+=", ...), Parameter(isUnnamed:) → Parameter(unlabeled:)) are correct and the test suite reportedly passes 397/397. The CI checklist has three items still pending (new workflows, cache hit, full matrix) — these should be confirmed before merge.

---

Verdict

The PR is mechanically sound. The one question to resolve before merging is whether the --strict removal from SwiftFormat is intentional. Everything else is either clearly correct or clearly documented.

[leogdion]

Thanks for the second pass. Round-2 responses:

A. --strict removed from SwiftFormat in STRICT mode — fixed in 8456e3a. You were right that this was an unintended regression from the MistKit sync. There was an extra wrinkle: --strict is swift-format lint-only — the format subcommand rejects it (Error: Unknown option '--strict'), which is presumably why MistKit dropped it from the shared SWIFTFORMAT_OPTIONS. Split into its own SWIFTFORMAT_LINT_STRICT variable that's only applied to the lint call. Also drops the duplicated --configuration .swift-format the previous shared-options layout was passing on the lint line. CI was never using STRICT mode (the workflow just runs ./Scripts/lint.sh with no env), so no CI-visible regression — only local LINT_MODE=STRICT runs were affected. Verified: LINT_MODE=STRICT ./Scripts/lint.sh exits 0 with no findings; default mode unchanged; 397 tests pass.

B. ProcessError file extraction — confirmed pure file-split refactor. The package enum ProcessError: Error, Sendable declaration moved verbatim (both cases — packageValidationFailed and setupError(any Error) — bodies and the doc comment preserved character-for-character). Done in commit 67fe748 solely to let one_declaration_per_file pass without the swiftlint:disable block. git log -p --follow Sources/DocumentationHarness/ProcessError.swift shows zero behaviour changes. Happy to fold this note into the PR description if useful.

C. periphery:ignore on @available(*, unavailable) members — fair point and I looked into it. Periphery 3.7.4 (periphery scan --help) exposes retain_public, retain_codable_properties, retain_files, retain_unused_imported_modules, and per-rule disable flags, but no retain_unavailable / retain_at_available_unavailable knob for the @available(*, unavailable) pattern. Suppression options are:

1. Inline // periphery:ignore (what this PR uses).
2. Path-based excludes via .periphery.yml — too coarse (would silence real findings in those files).
3. Adding it to a custom rule entry — but no such facet exists for @available attributes.

I went with inline because each annotation carries its own tail-comment justification (- intentionally unavailable; retained for source compatibility) that a config file couldn't capture, and the comment survives file renames. Open to revisiting if Periphery adds the knob.

D. CI checklist — checking now after the new push lands; will tick the boxes on the PR description once the new commits' check-unsafe-flags / swift-source-compat / cache-hit runs report green.

[claude]

Code Review — PR #159: Sync workflows + lint configs from MistKit; fix all warnings

Overview

This PR is a well-scoped housekeeping change: sync CI workflows and lint configs from MistKit, tighten lint rules, and fix every warning they surface. The mechanical warning fixes (deprecated SwiftSyntax inits, unused public imports, periphery annotations) are all correct. CI improvements are meaningful. A few things worth noting:

---

Strengths

• Composite setup-tools action is the right fix. Reusable workflows scope caches separately, so the old pattern silently broke hand-off between a setup job and a consumer job. The two-step approach (restore cache → either install or just configure PATH) correctly handles both paths.
• Improved matrix logic — full matrix on semver branches (not just main) is a good catch. The step-split into check + matrix is clearer than the old monolithic step.
• swift build --build-tests added to lint.sh — ensures the lint run surfaces compilation errors, not just style issues.
• no_unchecked_sendable custom SwiftLint rule — enforcing proper Sendable conformance at error level is a strong default for Swift 6 concurrency.
• public import SwiftSyntax → import SwiftSyntax in internal extension files — correct; public import on a transitive dep was leaking the module into consumers' namespaces unnecessarily.
• run_command() simplification — the if STRICT / else branches were identical; removing the dead branch is correct.
• ProcessError moved to its own file — minor cleanup but consistent with one_declaration_per_file.

---

Concerns

1. SwiftLint version mismatch

.mise.toml (deleted) pinned SwiftLint 0.63.2. The surviving mise.toml pins 0.62.2. The CLAUDE.md quality-tools table still says 0.63.2. The new opt-in rules (discouraged_optional_boolean, one_declaration_per_file) need to be verified against 0.62.2 — if those rules don't exist in that release, swiftlint lint will silently ignore them (or error). Please double-check which version the CI actually installs and update the doc.

2. check-unsafe-flags.yml uses swift:latest

container:
  image: swift:latest

swift:latest is non-deterministic — it will silently pick up a new Swift major on the next pull, which can produce false positives (or hide real ones). Pin to swift:6.1 (or whichever minimum you support) for reproducible results.

3. pushd $PACKAGE_DIR missing quotes

pushd $PACKAGE_DIR   # ← unquoted

This is pre-existing (the prior line used "$PACKAGE_DIR"), but since the line above it was changed in this PR, it's a good time to fix: pushd "$PACKAGE_DIR". Paths with spaces (not uncommon on macOS) will break pushd silently.

4. pattern_matching_keywords removal is unexplained

The rule was removed from the opt-in list without a comment or mention in the PR description. Was this intentional (conflicts with another rule? noisy?) or an accidental drop during the sync? Worth a one-line note.

---

Minor notes

• codeql.yml: adding if: matrix.language == 'swift' guards on both the Xcode setup and swift-version verify steps is correct — the old code was running xcode-select even on non-macOS runners.
• The lint job concurrency setting (cancel-in-progress: false) correctly prevents a thundering-herd on a mise.toml bump. Good.
• swift-source-compat.yml building with --disable-sandbox is necessary for container-mode SPM but worth a comment for future readers.

---

Summary

The CI improvements are solid and the warning fixes are mechanical/correct. Before merging, I'd address: (1) the SwiftLint version discrepancy between mise.toml and CLAUDE.md, (2) pin swift:latest in check-unsafe-flags.yml, and (3) confirm pattern_matching_keywords removal was intentional. Everything else is clean.