Formatting improvements

[a-frantz]

Assuming none of these features are added to #133 which hasn't merged at time of writing:

Must haves

• max line widths are currently ignored.
• rework how command text is processed
  • The whitespace inside a command block is not considered trivia, which throws off our formatting. This is most obvious when a multi-line placeholder is included in a command. It will be at least one indentation level "short"
• sort inputs
  • this should only be implemented once we've added some configuration abilities
  • That's bc input sorting is potentially divisive and controversial, so we need to offer an easy way to "opt-out"
• some constructs, like input: items, have a single line representation and a multi-line representation. Currently we take a naive approach to this choice, where if there is only one item we go for a single-line representation, even if that single line gets interrupted into multiple lines. We should detect line splits and adapt accordingly.

Maybe we should implement?

Below features are lower priority (if we even want them in the first place). They would potentially also be off by default, and entirely "opt-in".

• sorting things in meta sections. This was proposed by @adthrasher and IDK the specifics of what this would look like
  • there's a lot we could do here, all of which would be somewhat "intrusive" IMO
• sorting runtime/requirement sections
  • I'd call this less intrusive than sorting meta. I don't think anyone would really object to this? I think this would be nice to have
• change whitespace in command blocks
  • treating command whitespace as trivia would greatly simplify the rework how command text is processed point in the Must have list
  • this could potentially break a command that depended on specific whitespace, but yikes you should probably not be writing commands so that they are so fragile.
• format comments
  • we currently trim trailing whitespace from comments, but we can go further if we want
  • we could ensure # signs and text are separated by a space
  • we could shuffle the order of preamble comments/lint directives
  • "downgrade" ## comments found outside of the preamble
  • All of this would probably be pretty intrusive and potentially annoying to users.

[adthrasher]

sorting things in meta sections. This was proposed by @adthrasher and IDK the specifics of what this would look like
there's a lot we could do here, all of which would be somewhat "intrusive" IMO

I'm not certain if this is a good idea or not. If we implement it, I think it needs to be configurable. Essentially there would be a list of default keys that are sorted into the specified order and any other keys are just appended to the list. I think this came about while looking at something like the SEAseq meta below. Things like title, summary, and description likely always belong at the top of a meta section. Obviously, that can be done manually, but if we're formatting anyway, should that be an enforced thing? The example below also is more complicated and contains objects within the meta. I'm not sure if we would need to provide a facility to sort within those objects as well.

    meta {
        title: 'SEAseq Analysis'
        summary: 'Single-End Antibody Sequencing (SEAseq) Pipeline'
        description: 'A comprehensive automated computational pipeline for all ChIP-Seq/CUT&RUN data analysis.'
        version: '2.0.0'
        details: {
            citation: 'https://doi.org/10.1186/s12859-022-04588-z',
            contactEmail: '[email protected]',
            contactOrg: "St Jude Children's Research Hospital",
            contactUrl: "",
            upstreamLicenses: "MIT",
            upstreamUrl: 'https://github.com/stjude/seaseq',
            whatsNew: [
                {
                    version: "2.0",
                    changes: ["version of case/sample only", "single-end sequencing with input/control sequencing data", "Initial release"]
                }
            ]
        }
        parameter_group: {
            reference_genome: {
                title: 'Reference genome',
                description: 'Genome specific files. e.g. reference FASTA, GTF, blacklist, motif databases, FASTA index, bowtie index .',
                help: 'Input reference genome files as defined. If some genome data are missing then analyses using such data will be skipped.'
            },
            input_genomic_data: {
                title: 'Input FASTQ data',
                description: 'Genomic input files for experiment.',
                help: 'Input one or more sample data and/or SRA identifiers.'
            },
            analysis_parameter: {
                title: 'Analysis parameter',
                description: 'Analysis settings needed for experiment.',
                help: 'Analysis settings; such output analysis file name.'
            }
        }
    }

[a-frantz]

I think we hold off on implementing any meta sorting until it's requested by users. Agree that this would need to be configurable, and I'd go further to say it should be off by default. This would potentially annoy users. So I don't see it as a very high priority to get implemented. I'd probably wait till a user asks for it to implement it.