using --checkout-path options to provide link to hosting causes DocC convert to fail

[heckj]

Description

In making a sample Swift package with a DocC catalog, I was trying to set up GitHub Pages hosting with it to reference the repository as an example.

When doing including the trio of options (through the Swift-DocC-plugin and the generate-documentation command), it produced the following error:

error: 'docc convert' invocation failed with a nonzero exit code: '64'
error: Error Domain=NSCocoaErrorDomain Code=4 "“ExampleDocs.doccarchive” couldn’t be moved to “outputs” because either the former doesn’t exist, or the folder containing the latter doesn’t exist." UserInfo={NSSourceFilePathErrorKey=/Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/intermediates/ExampleDocs.doccarchive, NSUserStringVariant=(
    Move
), NSDestinationFilePath=/Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/ExampleDocs.doccarchive, NSFilePath=/Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/intermediates/ExampleDocs.doccarchive, NSURL=file:///Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/intermediates/ExampleDocs.doccarchive, NSUnderlyingError=0x104f9c340 {Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory"}}

When invoking without the link-to-GitHub hosting options, it renders correctly and without error.

The command (without the hosting options) that works:

swift package --disable-sandbox generate-documentation \
--hosting-base-path example-docc-project \
--analyze --warnings-as-errors \
--output-path docs

And the command that fails:

swift package --disable-sandbox generate-documentation \
--hosting-base-path example-docc-project \
--analyze --warnings-as-errors \
--checkout-path /Users/heckj/src/example-docc-project \
--source-service github --source-service-base-url heckj/example-docc-project \
--output-path docs

^ in the above, I've cloned the repository heckj/example-docc-project into /Users/heckj/src.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

• generates the docs into the docs/ directory

Actual behavior

docc convert error bubbles up:

error: 'docc convert' invocation failed with a nonzero exit code: '64'
error: Error Domain=NSCocoaErrorDomain Code=4 "“ExampleDocs.doccarchive” couldn’t be moved to “outputs” because either the former doesn’t exist, or the folder containing the latter doesn’t exist." UserInfo={NSSourceFilePathErrorKey=/Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/intermediates/ExampleDocs.doccarchive, NSUserStringVariant=(
    Move
), NSDestinationFilePath=/Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/ExampleDocs.doccarchive, NSFilePath=/Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/intermediates/ExampleDocs.doccarchive, NSURL=file:///Users/heckj/src/example-docc-project/.build/plugins/Swift-DocC/outputs/intermediates/ExampleDocs.doccarchive, NSUnderlyingError=0x104f9c340 {Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory"}}

Steps To Reproduce

The steps to reproduce

1. git clone https://github.com/heckj/example-docc-project
2. cd example-docc-project
3. export THISDIR=$(PWD)
4. run the command:

swift package --disable-sandbox generate-documentation \
--hosting-base-path example-docc-project \
--analyze --warnings-as-errors \
--checkout-path $THISDIR \
--source-service github --source-service-base-url heckj/example-docc-project \
--output-path docs

Swift-DocC Version Information

26.0

Swift Compiler Version Information

swift-driver version: 1.127.8 Apple Swift version 6.2 (swiftlang-6.2.0.13.10 clang-1700.3.13.4)
Target: arm64-apple-macosx26.0

[ktoso]

I saw the same issue over here https://github.com/swiftlang/swift-java/actions/runs/16466834686/job/46546188972?pr=319 and it was manifesting very very confusingly like this.

In the end the "solution" was to bump the base image we're using on CI to swift:6.1-noble but I'll admit I did not continue digging what the core issue was.

The paths here look incorrect though in the failed runs basically (/usr/share/swift/usr/share/docc/render/img looks suspicious):

Build of target: 'SwiftJavaDocumentation' complete! (75.60s)
error: 'docc convert' invocation failed with a nonzero exit code: '1'
error: Error Domain=NSCocoaErrorDomain Code=4 "The file doesn't exist."UserInfo={NSDestinationFilePath=/home/runner/work/swift-java/swift-java/.build/plugins/Swift-DocC/outputs/SwiftJavaDocumentation.doccarchive, NSUserStringVariant=["Move"], NSSourceFilePathErrorKey=/home/runner/work/swift-java/swift-java/.build/plugins/Swift-DocC/outputs/intermediates/SwiftJavaDocumentation.doccarchive, NSURL=file:///home/runner/work/swift-java/swift-java/.build/plugins/Swift-DocC/outputs/intermediates/SwiftJavaDocumentation.doccarchive, NSFilePath=/home/runner/work/swift-java/swift-java/.build/plugins/Swift-DocC/outputs/intermediates/SwiftJavaDocumentation.doccarchive, NSUnderlyingError=Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory"}
Extracting symbol information for 'SwiftJavaDocumentation'...
Finished extracting symbol information for 'SwiftJavaDocumentation'. (77.14s)
Building documentation for 'SwiftJavaDocumentation'...
Error: Error Domain=NSCocoaErrorDomain Code=513 "You don't have permission."UserInfo={NSFilePath=/usr/share/swift/usr/share/docc/render/img, NSSourceFilePathErrorKey=/usr/share/swift/usr/share/docc/render/img, NSURL=file:///usr/share/swift/usr/share/docc/render/img, NSUnderlyingError=Error Domain=NSPOSIXErrorDomain Code=1 "Operation not permitted", NSDestinationFilePath=/tmp/F3E62B64-2D86-49F3-8A0B-E1E956A9E69D-4761-0000008003A1E2AB/img, NSUserStringVariant=["Copy"]}
Error: Process completed with exit code 1.

[d-ronnqvist]

I wonder if this is in any way related to #1136

[heckj]

Working on some docs and the CI that's doing a soundness check is - sometimes - hitting this - the Swift toolchain is installed with Swiftly and uses Swift 6.1 installed using Swiftly. It seems to be intermittent in that scenario