Move `src`, `test`, and `app` directories into a `code` directory

[kostmo]

This is to simplify queries for .hs files, whether it be in IDEs or in the terminal, using find.

As is, the simplest find command includes unwanted build artifacts:

$ find . -name *.hs
./src/swarm-lang/Swarm/Language/Typed.hs
./src/swarm-lang/Swarm/Language/LSP/VarUsage.hs
[...]
./dist-newstyle/build/x86_64-linux/ghc-9.6.4/swarm-0.5.0.0/l/swarm-lang/noopt/build/swarm-lang/autogen/PackageInfo_swarm.hs
./dist-newstyle/build/x86_64-linux/ghc-9.6.4/swarm-0.5.0.0/l/swarm-lang/noopt/build/swarm-lang/autogen/Paths_swarm.hs
[...]
./app/doc/Main.hs
./app/tournament/Main.hs
[...]
./.stack-work/dist/x86_64-linux-tinfo6/ghc-9.6.4/build/swarm-tournament/autogen/PackageInfo_swarm.hs
./.stack-work/dist/x86_64-linux-tinfo6/ghc-9.6.4/build/swarm-tournament/autogen/Paths_swarm.hs
[...]

whereas these could be excluded easily if all of the code lived underneath a single code directory:

$ find code -name *.hs

[xsebek]

There is fd (a Rust find alternative) that solves this with better defaults:

fd --glob '*.hs'  # or fd '.*\.hs' or fd --extension hs

app/Main.hs
app/Swarm/App.hs
app/doc/Main.hs
app/scene/Main.hs
app/tournament/Main.hs
images/logo/MkLogo.hs
src/swarm-doc/Swarm/Doc/Command.hs
[...]
test/unit/TestUtil.hs

I would not mind moving the folders closer, though I would prefer cleaning up the top level. For example, it should be possible to move some of the CI configuration files to .github.

[byorgey]

Can you elaborate on when and why we would want to use such commands?

To me, this seems to be optimizing for something that's not a big deal to me, but would make my day-to-day experience navigating the codebase slightly worse.

[byorgey]

We could probably easily move everything in app into src. I know that doesn't completely address the concern but it's something that occurred to me.

[kostmo]

Can you elaborate on when and why we would want to use such commands?

Say, if I want to count lines in files. Or the various scripts that require the paths to .hs files to be specified (code-format.sh, issues-for-todos.sh).

would make my day-to-day experience navigating the codebase slightly worse.

I'd like to understand this more. I would think this path change should be rendered essentially transparent by IDE use.

[byorgey]

I'd like to understand this more. I would think this path change should be rendered essentially transparent by IDE use.

I mean, once I have an IDE open, sure. I just tend to spend a lot of time in the terminal. It's not that uncommon for me to type in the name of a .hs file I want to edit, or to navigate around with cd to look at things. This would just be one more level of indirection.

I should also point out this would make the repository slightly harder to navigate for newcomers --- e.g. anyone looking for a test suite would normally look for a folder called test, and under this scheme they would have to first figure out that they need to look under code.

These inconveniences are minor, to be sure. But it seems like the benefits would be minor as well, so I'm not sure how to judge between them.

[kostmo]

At the risk of spilling ink disproportionate to the payoff (but all in good fun):

It's not that uncommon for me to type in the name of a .hs file I want to edit

It seems to me that the CLI navigation cost is by far dominated by the rest of the filepath?
e.g.
src/swarm-lang/Swarm/Language/Parser/Record.hs
vs
code/src/swarm-lang/Swarm/Language/Parser/Record.hs

This is the cost one commits to when eschewing an IDE, where only six or seven keystrokes are required (e.g. CTRL+p search in VS Code), regardless of module depth.
On that note, are there equivalent objections to introducing intermediate directories ("conids") in the module hierarchy for organizational purposes?

With respect to newbies, I'm hard-pressed to envision a scenario in which tests inside code/ are not trivially located when the need arises.

About convention

The defaults of cabal init do reflect some degree of convention, but is far from immutable or universal; e.g. it offers users a choice for the "library code" directory between:

*  1) src
   2) lib
   3) src-lib
   4) Other (specify)

and for "application code", choices between:

 * 1) app
   2) exe
   3) src-exe
   4) Other (specify)

So the "developer orientation" value in strict adherence to the defaults is questionable.

As it stands, I'd argue that a code/ directory intuitively complements the existing data/ directory for this project.

Quantitative benefit

We might contrast the hypothetical cost to developer onboarding vs. the concrete benefit established in #2020.

Aside from simplifying the ad-hoc CLI queries described above, there are already three places in our codebase that are simplified, including one fixed bug:

• .github/workflows/hlint.yml
• scripts/normalize/code-format.sh
• scripts/validate/issues-for-todos.sh

One should extrapolate this benefit further as the codebase grows.

[xsebek]

@kostmo just to be clear, you want to move only Haskell code to code or everything else as well?

If it is the former, I would much rather install fd and fix our tools. It is user friendly and in many cases 10x faster. One should extrapolate from there. 😉

[kostmo]

I guess I could settle for moving app into src. I'll take the 33% DRY improvement to these scripts if I can't get 66%. 😛

^{unless we can move test into src as well? 😈}

On the topic of unix tool replacements, I am reminded that I should also reinstall ripgrep (rg), which respects .gitignore settings.

[byorgey]

At the risk of spilling ink disproportionate to the payoff (but all in good fun):

OK, I guess I'm convinced that the downsides would not be that bad. And it's really a rather silly thing to argue about, so I won't oppose this change, though it still feels to me like something that should be solved with better tools rather than reorganizing the codebase.

[kostmo]

Thanks for humoring me 😄

it still feels to me like something that should be solved with better tools rather than reorganizing the codebase.

I hypothesize that feeling relates to status quo bias or appeal to tradition.

Consider this framing: one can either have "simple data organization" that necessitates only "simple tools", or have "complex data organization" that must be compensated for by "complex tools".

[byorgey]

Hmm, perhaps! Although an alternative framing would be: one can either use "complex data organization" just so that "simple tools" work, or use "simple data organization" and create "complex tools" to go with it. Perhaps the reason I was initially opposed to this is that it felt like making things easier for our tools at the expense of making things more complex for ourselves, which seems exactly backwards. However, I understand your point that we are the ones who have to create and maintain the tools, so this distinction is actually not so clear-cut.

[xsebek]

I can't shake the feeling that moving only Haskell code optimises for a specific few command line invocations that fail to provide something like --extension hs --ignore-ignored.

@kostmo would you mind waiting to try other approaches mentioned here first? I should have some time on weekend. 🙂

Anyway it might be good idea to make release before this.