sdggiesbrecht / workspace Goto Github PK

Description

I am getting flagged with a warning for the use of an obsolete - character (U+002D). I understand why these are coming up when found in my documentation comments. But this is happening in my Package.swift file:

The character U+002D is obsolete. Use a hyphen (‐), minus sign (−), dash (—), bullet (•) or range symbol (–). (unicode)
        .package(url: "https://github.com/vapor/fluent-sqlite.git", from: "3.0.0")

I have tried to replace the offending character with hyphens, em-dashes, and a couple of other variants. Unfortunately, changing the URL for an external package breaks my build. The fluent-sqlite.git repository cannot be found when I try to replace the existing U+002D character.

Issue:

With Swift 5, build and linker errors occur when trying to use the Refresh, Validate or installation scripts.

Explanation:

Workspace 0.14.2 must be paired with Swift 4.2.1:

• The executable requires Swift 4.2.1 to be present, but not necessarily active. (If it cannot find it, the error message provides more detailed instructions.) The Swift Version Manager can be used to manage side‐by‐side Swift installations.
• The scripts require a version of Swift compatible with 4.2.1. to be active. (Specifically, $ swift --version in a brand new terminal window must report a compatible version). Unfortunately many inadvertently breaking changes tend to find their way into minor versions of Swift, so often versions Swift intended to be compatible actually aren’t.

Some of Swift’s implementation details make it impossible for Workspace to reliably support more than one version of Swift from the same version of Workspace. These may be weeded out when/if it becomes possible, but at the moment it is not.

Question

I just ran workspace refresh on HandySwift and the first thing which happened was basically no files changed, but three script files created (Refresh (Linux).sh, Refresh (macOS).command and Validate(macOS).command). First question: What are these files for? Their purpose isn't documented anywhere ... also, can I place them into a subfolder? I'd rather not have so many files on the root level ...

Next, because I wanted to make HandySwift actually a cross-platform library and relies on SwiftPM, I removed the .xcodeproj and .xcworkspace folders entirely to move to a Package.swift based project. Then I ran workspace refresh again. This time, nothing happened. I started wondering what the command is doing anyways, I'm not sure if I did something wrong or if this is actually the expected behavior.

Then, I ran workspace test which ran all the tests for all Apple platforms (I'm assuming because I'm on a Mac) except watchOS, so I'm wondering why watchOS isn't tested, too, because it's less common or is there another reason? (OK, that question maybe is off-topic ...)

After running the tests though I had a .swiftpm folder full of test results which were showing in my unstages changes in Git, even running workspace refresh one more time didn't change that. I would expect a refresh command to adjust a project in some ways, for example by adding the .swiftpm folder to the .gitignore file if it's not there yet (I'm assuming that's the best practice here).

Documentation Suggestion

Make it more clear what exactly refresh does both in empty projects but also in existing projects. For example, if I didn't have a LICENSE file, would it add one? (Ok, I just tried, it doesn't – I'd expect that, too...)

From the Swift forums:

It seems to not be finding documentation for some documented symbols. For example, it claims

A symbol has no description:
PNG.Properties.Format

But it does.

Question

I just ran workspace refresh to see what would happen in HandySwift's root directly and it reported the following 'unsupported file types':

podspec (HandySwift.podspec)
stencil (.sourcery/LinuxMain.stencil)
xcplayground (UsageExamples.playground/contents.xcplayground)

The output further states that 'If these are standard file types, please report them' so I'm reporting them. Though, I'm not sure what 'standard file types' are, but interpreting it as 'common types for a Swift package' I think it applies to all of these.

Documentation Suggestion

Maybe be more clear about what a standard file type is? And I also don't understand why I should report it in the first place, or should I just ignore them via repository.ignoredFileTypes as suggested as an alternative? It's also unclear, by which issue type these should be reported, as bugs?

Description

I tried to install workspace for the first time, using the command documented in the documentation. Most of the installation seems to work: The appropriate Swift packages are built, and near the end I see a message stating that installation was successful.

However, after everything is built the installation script does some things to add workspace to my path, and the runs workspace help. Those path configuration changes are broken, and as a result the final workspace help command fails:

bash: line 115: workspace: command not found

I have looked over the installer script, and it appears to be simply a mistake in the script. There is part of the script that does this:

# Register the products.
for tool in tools ; do

If I add a $ before tools it works:

# Register the products.
for tool in $tools ; do

From the Swift forums:

This declaration for the PNG.rgba(path:of:) method is missing the generic parameters, making for some odd spellings

Description

I just read the Docs and also opened some of the links there, but I still don't get the whole picture: What exactly is the purpose of this ... tool? library? package? I don't even understand it's type. It kind of sounds like a command line tool, but then there's a way to include it via SwiftPM and use features in a Swift file. Also, the docs state that this automates management of Swift projects, but which part does it automate? The creation of new ones? Or can it also adjust existing projects to a structure? How does it do that? What best practices does it follow? Does it work with iOS-targeting projects, too? What exactly is considered a "Swift project"?

Just having auto-generated documentation on the classes and commands doesn't really help understand how I can make use of this effectively. For example, you mentioned on the Swift forums that I can use workspace refresh continuous-integration but the README points to this link which doesn't explain what it will do at all. After some search I've found that page in the docs which has some more info (and should be linked in the README IMHO), but again it does not go into any details as for what exactly it will generate. Will it cover building, tests, code coverage, documentation coverage etc. all in one? What if I want to add custom linters or other stuff, do I need to generate things and then adjust them to my needs? How can I then make sure that future changes to Workspace will be easily applicable by re-running those commands? Is there a plugin-type system so I can add my custom changes without affecting the basic configuration?

Of course, people could "just try it out" to see how the tool behaves, but that's another hurdle and I think a README should at least answer the questions as to how I would profit from using this tool as a user. Currently it looks to me like it's a very opinionated set of tools that cover a specific need which is not even documented. So it just feels like I'm adding a dependency that I can't control or understand after reading the README, thus I would not use it. Having a few good full examples in the README would go a long way to explain this tool/package better.

Availability to Help

I would like to help fix it, but I would need a lot of guidance.

Recommended Correction

All in all I think some usage examples are missing. Maybe there should be a blog post (or a series of it) which explain the more general design and use cases this tool covers. I have the feeling it is a potentially amazing tool but can't be used right now due to lack of easy to understand documentation that not only explains how to use it, but also why someone should use it (including its limitations and building trust by explaining why the design is flexible).

When I try to run the refresh script locally, Workspace fails to link:

~/dev/png$ ./Refresh\ \(Linux\).sh 
# Option “-e” is deprecated and might be removed in a later version of gnome-terminal.
# Use “-- ” to terminate the options and put the command line to execute after it.

No cached build detected, fetching Workspace...
Cloning into '/tmp/Workspace'...
remote: Enumerating objects: 616, done.
remote: Counting objects: 100% (616/616), done.
remote: Compressing objects: 100% (324/324), done.
remote: Total 8401 (delta 402), reused 385 (delta 284), pack-reused 7785
Receiving objects: 100% (8401/8401), 1.72 MiB | 14.94 MiB/s, done.
Resolving deltas: 100% (5090/5090), done.
Fetching https://github.com/SDGGiesbrecht/SDGSwift
Fetching https://github.com/apple/swift-package-manager
Fetching https://github.com/SDGGiesbrecht/SDGCommandLine
Fetching https://github.com/apple/swift-syntax
Fetching https://github.com/SDGGiesbrecht/SDGCornerstone
Completed resolution in 4.34s
Cloning https://github.com/SDGGiesbrecht/SDGSwift
Resolving https://github.com/SDGGiesbrecht/SDGSwift at 0.3.7
Cloning https://github.com/apple/swift-syntax
Resolving https://github.com/apple/swift-syntax at 0.40200.0
Cloning https://github.com/SDGGiesbrecht/SDGCommandLine
Resolving https://github.com/SDGGiesbrecht/SDGCommandLine at 0.4.2
Cloning https://github.com/SDGGiesbrecht/SDGCornerstone
Resolving https://github.com/SDGGiesbrecht/SDGCornerstone at 0.12.0
Cloning https://github.com/apple/swift-package-manager
Resolving https://github.com/apple/swift-package-manager at 0.3.0
Compile clibc libc.c
Compile SDGCMarkShims utf8.c
Compile SDGCMarkShims xml.c
Compile Swift Module 'SDGSwiftConfiguration' (4 sources)
Compile Swift Module 'SDGLogic' (6 sources)
Compile Swift Module 'PackageDescription4' (9 sources)
Compile Swift Module 'SDGControlFlow' (17 sources)
Compile Swift Module 'SwiftSyntax' (23 sources)
Compile Swift Module 'PackageDescription' (6 sources)
Compile SDGCMarkShims scanners.c
Compile SDGCMarkShims render.c
Compile Swift Module 'SPMLibc' (1 sources)
Compile SDGCMarkShims references.c
Compile SDGCMarkShims node.c
Compile Swift Module 'POSIX' (11 sources)
Compile SDGCMarkShims man.c
Compile SDGCMarkShims latex.c
Compile SDGCMarkShims iterator.c
Compile SDGCMarkShims inlines.c
Compile SDGCMarkShims html.c
Compile SDGCMarkShims houdini_html_u.c
Compile Swift Module 'Basic' (38 sources)
Compile SDGCMarkShims houdini_html_e.c
Compile SDGCMarkShims houdini_href_e.c
Compile SDGCMarkShims commonmark.c
Compile SDGCMarkShims cmark_ctype.c
Compile SDGCMarkShims cmark.c
Compile SDGCMarkShims buffer.c
Compile SDGCMarkShims blocks.c
Compile Swift Module 'SDGMathematics' (32 sources)
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGMathematics/Float.swift:619:34: warning: '0x1.5BF0A9p1' loses precision during conversion to 'Float'
    public static let e: Float = 0x1.5BF0A9p1
                                 ^

Compile Swift Module 'SDGCollections' (42 sources)
/tmp/Workspace/.build/checkouts/swift-package-manager-cc65b8a0/Sources/Basic/CollectionAlgorithms.swift:36:5: warning: 'public' modifier is redundant for instance method declared in a public extension
    public func findDuplicates() -> [Iterator.Element] {
    ^~~~~~~
    
/tmp/Workspace/.build/checkouts/swift-package-manager-cc65b8a0/Sources/Basic/FileSystem.swift:248:16: warning: 'readdir_r' is deprecated
            if readdir_r(dir, &entry, &entryPtr) < 0 {
               ^
/tmp/Workspace/.build/checkouts/swift-package-manager-cc65b8a0/Sources/Basic/StringConversions.swift:45:5: warning: 'public' modifier is redundant for instance method declared in a public extension
    public func shellEscaped() -> String {
    ^~~~~~~
    
/tmp/Workspace/.build/checkouts/swift-package-manager-cc65b8a0/Sources/Basic/StringConversions.swift:74:5: warning: 'public' modifier is redundant for instance method declared in a public extension
    public mutating func shellEscape() {
    ^~~~~~~
    

Compile Swift Module 'Utility' (19 sources)
Compile Swift Module 'PackageModel' (7 sources)
Compile Swift Module 'SourceControl' (4 sources)
Compile Swift Module 'PackageLoading' (9 sources)
Compile Swift Module 'SDGText' (30 sources)
Compile Swift Module 'SDGPersistence' (10 sources)
Compile Swift Module 'PackageGraph' (6 sources)
Compile Swift Module 'SDGLocalization' (38 sources)
Compile Swift Module 'Xcodeproj' (7 sources)
Compile Swift Module 'Build' (8 sources)
Compile Swift Module 'Workspace' (7 sources)
Compile Swift Module 'WSLocalizations' (2 sources)
Compile Swift Module 'SDGCommandLineLocalizations' (4 sources)
Compile Swift Module 'SDGExternalProcess' (4 sources)
Compile Swift Module 'SDGCornerstoneLocalizations' (4 sources)
Compile Swift Module 'SDGSwiftLocalizations' (3 sources)
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGExternalProcess/ExternalProcess.swift:103:17: warning: 'launchPath' is deprecated: renamed to 'executableURL'
        process.launchPath = executable.path
                ^
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGExternalProcess/ExternalProcess.swift:103:17: note: use 'executableURL' instead
        process.launchPath = executable.path
                ^~~~~~~~~~
                executableURL
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGExternalProcess/ExternalProcess.swift:109:21: warning: 'currentDirectoryPath' is deprecated: renamed to 'currentDirectoryURL'
            process.currentDirectoryPath = location.path
                    ^
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGExternalProcess/ExternalProcess.swift:109:21: note: use 'currentDirectoryURL' instead
            process.currentDirectoryPath = location.path
                    ^~~~~~~~~~~~~~~~~~~~
                    currentDirectoryURL
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGExternalProcess/ExternalProcess.swift:119:17: warning: 'launch()' is deprecated: renamed to 'run'
        process.launch()
                ^
/tmp/Workspace/.build/checkouts/SDGCornerstone-86db4481/Sources/SDGExternalProcess/ExternalProcess.swift:119:17: note: use 'run' instead
        process.launch()
                ^~~~~~
                run

Compile Swift Module 'SDGTesting' (3 sources)
Compile Swift Module 'SDGSwift' (10 sources)
Compile Swift Module 'SDGCalendar' (43 sources)
Compile Swift Module 'SDGXCTestUtilities' (2 sources)
/tmp/Workspace/.build/checkouts/swift-package-manager-cc65b8a0/Sources/Workspace/ToolsVersionWriter.swift:45:5: warning: 'public' modifier is redundant for property declared in a public extension
    public var zeroedPatch: ToolsVersion {
    ^~~~~~~
    

Linking ./.build/x86_64-unknown-linux/release/libSwiftPM.so
Compile Swift Module 'SDGSwiftConfigurationLoading' (4 sources)
Compile Swift Module 'SDGXcode' (9 sources)
Compile Swift Module 'SDGSwiftPackageManager' (8 sources)
Compile Swift Module 'SDGCommandLine' (26 sources)
Compile Swift Module 'SDGPersistenceTestUtilities' (4 sources)
Compile Swift Module 'WorkspaceConfiguration' (36 sources)
Compile Swift Module 'SDGLocalizationTestUtilities' (2 sources)
Compile Swift Module 'SDGCommandLineTestUtilities' (2 sources)
Compile Swift Module 'WSGeneralImports' (3 sources)
Compile Swift Module 'WSSwift' (2 sources)
Compile Swift Module 'WorkspaceProjectConfiguration' (1 sources)
Compile Swift Module 'WSThirdParty' (2 sources)
Compile Swift Module 'WSConfigurationExample' (1 sources)
Linking ./.build/x86_64-unknown-linux/release/WSConfigurationExample
Compile Swift Module 'WSProject' (12 sources)
Compile Swift Module 'WSXcode' (2 sources)
Compile Swift Module 'WSNormalization' (1 sources)
Compile Swift Module 'WSExamples' (1 sources)
Compile Swift Module 'WSScripts' (2 sources)
Compile Swift Module 'WSResources' (2 sources)
Compile Swift Module 'WSValidation' (3 sources)
Compile Swift Module 'WSProofreading' (31 sources)
Compile Swift Module 'WSLicence' (3 sources)
Compile Swift Module 'WSGitHub' (1 sources)
Compile Swift Module 'WSGit' (1 sources)
Compile Swift Module 'WSFileHeaders' (1 sources)
Compile Swift Module 'WSOpenSource' (1 sources)
/tmp/Workspace/.build/checkouts/swift-syntax-e33d5ec5/Sources/SwiftSyntax/SwiftcInvocation.swift:72:11: warning: 'launchPath' is deprecated: renamed to 'executableURL'
  process.launchPath = executable.path
          ^
/tmp/Workspace/.build/checkouts/swift-syntax-e33d5ec5/Sources/SwiftSyntax/SwiftcInvocation.swift:72:11: note: use 'executableURL' instead
  process.launchPath = executable.path
          ^~~~~~~~~~
          executableURL
/tmp/Workspace/.build/checkouts/swift-syntax-e33d5ec5/Sources/SwiftSyntax/SwiftcInvocation.swift:76:11: warning: 'launch()' is deprecated: renamed to 'run'
  process.launch()
          ^
/tmp/Workspace/.build/checkouts/swift-syntax-e33d5ec5/Sources/SwiftSyntax/SwiftcInvocation.swift:76:11: note: use 'run' instead
  process.launch()
          ^~~~~~
          run

Linking ./.build/x86_64-unknown-linux/release/libSwiftSyntax.so
Compile Swift Module 'SDGSwiftSource' (87 sources)
Compile Swift Module 'WSDocumentation' (12 sources)
Compile Swift Module 'WSContinuousIntegration' (2 sources)
Compile Swift Module 'WSTesting' (2 sources)
Compile Swift Module 'WSInterface' (26 sources)
/tmp/Workspace/Sources/WSInterface/Validate/ValidateAll.swift:161:90: warning: string interpolation produces a debug description for a function value; did you mean to make this explicit?
                            StrictString("$ workspace refresh scripts •use‐version \(update.string)"),
/tmp/Workspace/Sources/WSInterface/Validate/ValidateAll.swift:161:97: note: use 'String(describing:)' to silence this warning
                            StrictString("$ workspace refresh scripts •use‐version \(update.string)"),

Compile Swift Module 'test_tvos_simulator' (1 sources)
Compile Swift Module 'test_ios_simulator' (1 sources)
Compile Swift Module 'WorkspaceLibrary' (1 sources)
Compile Swift Module 'WSGeneralTestImports' (1 sources)
Linking ./.build/x86_64-unknown-linux/release/test‐tvos‐simulator
Compile Swift Module 'WorkspaceTool' (1 sources)
Linking ./.build/x86_64-unknown-linux/release/test‐ios‐simulator
Linking ./.build/x86_64-unknown-linux/release/workspace
Linking ./.build/x86_64-unknown-linux/release/arbeitsbereich
/usr/bin/ld.gold: fatal error: out of file descriptors and couldn't close any
clang: error: linker command failed with exit code 1 (use -v to see invocation)

<unknown>:0: error: link command failed with exit code 1 (use -v to see invocation)

I am building on Ubuntu 18.04, with the following Swift, ld, and gold versions:

~/dev/png$ swift --version
Swift version 5.0-dev (LLVM cbe8d5e28f, Clang 3452631569, Swift 201dcba300)
Target: x86_64-unknown-linux-gnu
~/dev/png$ ld --version
GNU ld (GNU Binutils for Ubuntu) 2.30
Copyright (C) 2018 Free Software Foundation, Inc.
This program is free software; you may redistribute it under the terms of
the GNU General Public License version 3 or (at your option) a later version.
This program has absolutely no warranty.
~/dev/png$ ld.gold --version
GNU gold (GNU Binutils for Ubuntu 2.30) 1.15
Copyright (C) 2018 Free Software Foundation, Inc.
This program is free software; you may redistribute it under the terms of
the GNU General Public License version 3 or (at your option) a later version.
This program has absolutely no warranty.

The project is kelvin13/PNG. I’ve tried restarting my machine, and the problem persists. I am also unable to build Workspace directly from a git clone.

Edited issue summary:

On some Linux devices, Workspace crashes with the following message during proofreading:

$ swiftlint lint --strict --reporter emoji
Fatal error: POSIX command failed with error: 13: file Foundation/Process.swift, line 543
Illegal instruction (core dumped)

Workspace retrieves and builds SwiftLint using the package manager, but on some devices the resulting binary ends up with the wrong permissions, prohibiting Workspace from executing it.

As a workaround, manually correcting those permissions allows Workspace to operate normally until the cache is reset or a different version of SwiftLint is needed:

$ chmod +x ~/.cache/ca.solideogloria.Workspace/Tools/SwiftLint/0.27.0/swiftlint

Original first post:

From the Swift forums:

it also just hangs on this step

$ swiftlint lint --strict --reporter emoji

when I run

png$ ~/.SDG/Tools/Workspace/workspace validate

From the Swift forums:

The parsed declatations seem completely messed up:

static func convert(rgba: [, size: (, to code: Code, chromaKey: RGBA<UInt16>? = default, path outputPath: String, level: Int = default) throws

It would be good for Workspace to have a higher standard when it comes to false positives than SwiftLint provides.

This will involve several steps:

• #195: Implementing custom plug‐ins so SwiftLint can still be used by those who want it. ✓
• #196: Refactoring proofreading to use SwiftSyntax. ✓
• Re‐implementing the useful SwiftLint rules as native rules and dropping SwiftLint from the default plug‐in list. SwiftLint had to be dropped early due to issues between it and Swift 5. Many rules have no native equivalents.

From the Swift forums:

PNG.Properties.Format

[...] It also seems to think it only has one case.

The workflow iOS.yaml is referencing action actions/checkout using references v1. However this reference is missing the commit a6747255bd19d7a757dbdda8c654a9f84db19839 which may contain fix to the some vulnerability.
The vulnerability fix that is missing by actions version could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider to update the reference to the action.

Workspace should provide a general plug‐in system to allow custom tasks to be shared across projects.

• A standard plug‐in would be a Swift Package which provides an executable.
• Plug‐ins would be applied using an addition to the WorkspaceConfiguration so that a user can specify the package URL, version, product, command line arguments, etc.
• Plug‐ins would be separately applicable to the refresh, proofread and validate phases.
• To start with, plug‐in output should be displayed and success based on the exit code. Tighter integration could be added at a later date.

(This is almost how SwiftLint integration in implemented now. It just needs to generalized and surfaced in the configuration API. As part of implementing this feature, SwiftLint should lose its privileged status and become default plug‐in for the proofread phase.)

Currently, when generating doc, the flag and language code are displayed without space between them:

🇬🇧EN

On Mac, they are displayed like this:

Please add one space between them.

Sometimes block documentation is dropped, triggering false coverage warnings.

The exact conditions are unknown, but this is a triggering example:

/**
 ...
 */
public static func == (lhs: Something, rhs: Something) -> Bool {
    // ...
}

The workflow Web.yaml is referencing action actions/checkout using references v1. However this reference is missing the commit a6747255bd19d7a757dbdda8c654a9f84db19839 which may contain fix to the some vulnerability.
The vulnerability fix that is missing by actions version could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider to update the reference to the action.

The list of Types is displayed:

After I click on a type, the list is automatically collapsed:

It's not user friendly.

Can you do not collapse the list please?

I think using the old style HTML frames or the modern ReactJS router will fix the problem.

Another feature request:
Please display the list of types by default.

From the Swift forums:

The proofreader is doing a lot of weird stuff such as

Line 2481
“>=” is obsolete. Use the greater‐than‐or‐equal sign (≥). (unicode)
precondition(chunkSize >= 1, "chunk size must be positive")
precondition(chunkSize ≥ 1, "chunk size must be positive")

what??

Line 67
U+0022 is obsolete. Use quotation marks (“, ”) or double prime (′′). (unicode)
///     let names = ["Jacqueline", "Ian", "Amy", "Juan", "Soroush", "Tiffany"]

At first glance, these warnings can appear to be talking about Swift, when they are really about the Unicode text representation. They should be re‐written to make this more clear.

Description

I just installed Workspace using the installation script, but then was confused because none of the commands was working. Running which workspace showed that the tool was not known. Only after restarting iTerm it worked.

Availability to Help

I would like to help fix it, and I think I know my way around.

Recommended Correction

The fact that a restart of the terminal is needed should be documented either in the README installation instructions or in the output of the installation script.

The workflow Miscellaneous.yaml is referencing action actions/checkout using references v1. However this reference is missing the commit a6747255bd19d7a757dbdda8c654a9f84db19839 which may contain fix to the some vulnerability.
The vulnerability fix that is missing by actions version could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider to update the reference to the action.

From the Swift forums:

It seems to think this colon in a doccomment is a swift colon

Line 4600
Colons should be preceded by spaces when denoting protocols or superclasses. (colonSpacing)
- Returns: A chunk iterator, if the PNG magic signature was read from the
- Returns : A chunk iterator, if the PNG magic signature was read from the

The unicode rule should allow customization to restrict it to particular scopes.

At least three levels should be recognized:

• Freeform text (documentation, comments, etc.)
• Machine identifiers (code)
• Either (string literals, etc.)

The general idea originates from @TimothyMDean’s comment in #259:

What would be really helpful for me is to have a way to exert a little more control over where this rule is applied. I understand that Workspace cannot tell the difference between string literal usage, but I can almost guarantee that my projects will almost never want this rule applied to any string literals because my use of String literals will generally not be for anything displayed to users. On the other hand, my documentation comments would absolutely be displayed as generated documentation, and so I like the idea of applying the rule there.

It would be a beginner‐level thing to implement. The parser already knows the difference between token kinds, so that part should be no more difficult than adding a new if condition. The “hardest” part would be designing a configuration API for it.

If anyone is interested in taking it on, I can give more specific directions.

From the Swift forums:

The index.html in the root of the docs/ folder redirects me to png/docs/🇺🇸EN/index.html which 404s.

Description

I just ran workspace document in an existing project to see what it does, but it failed to generate documentation with this output:

No original copyright date is specified.
(Configure it under “documentation.api.yearFirstPublished”.)

There are no localisations specified. (documentation.localisations)

✗ Failed to generate documentation. (See ⌘F ‘§1’)

‘HandySwift’ fails validation.

To me this looks like a Workspace.swift configuration file is actually required for this feature to work. Thus I'd expect there to be a simple way of creating one, for example via workspace configure.

Availability to Help

I would not like to help implement it.

Design Thoughts

I would at least generate an example file with sensible defaults. There might be even a questionnaire-like variant (similar to how Fastlane is configured) to setup the most important options, including copyright date and loclalisations, it seems.

From the Swift forums:

Symbols which have @_specialize-ations seem to get omitted from the documentation. Symbols which have @inlinable seem to lose their documentation.

Various issues occur when trying to document the PNG project.

Some discussion has already taken place in the Swift Forums.

Proofreading will be much faster and smarter if it uses the syntax structure instead of search patterns.

Rules will largely rely on the SyntaxScanner in the SDGSwiftSource library of SDGSwift and make good use of the textFreedom property.

I am using Workspace as a command line tool.
I am really struggling with finding the proper way to declare configurations in the Workspace.swift file.

For instance, how do I define a copyrightNotice?

Is it possible to get a "complete" Workspace.swift example, or having an example on each property in the documentation, so that it appears in this page?

Question

Just to try this tool out, I opened one of my projects and ran workspace normalise which resulted in all my filed to be converted from a 4-whitespaces based indentation to 2-whitespaces based indentation. I wonder, how is 2-whitespaces indentation considered best practice for Swift projects? Shouldn't we default to 4-whitespaces based indentation? Or did it even convert my 4-whitespaces to tabs (which would be an even worse default IMHO)?

Documentation Suggestion

I'd at least expect to find a way to configure this behavior, which I can't find documented anywhere. As a matter of fact, I didn't even find any documentation on the behavior overall. The documentation for normalise only states:

Normalises the project’s files by removing trailing whitespace, applying Unix newlines, performing canonical decomposition and formatting Swift files.

The reindentation isn't mentioned anywhere, or is that part of formatting Swift files? Then I wonder, how is that formatting done, using SwiftFormat? What configuration is applied to SwiftFormat, the default one? Does it really use 2-whitespaces indentation?

From the Swift forums:

The parsed declatations seem completely messed up:

static func convert(rgba: [, size: (, to code: Code, chromaKey: RGBA<UInt16>? = default, path outputPath: String, level: Int = default) throws